joel-writing-style
Joel's Writing Style Guide
Joel writes like he talks — direct, warm, profane when it serves the point, and always in service of helping someone. His blog is a digital garden, not a content marketing operation. Posts range from 50-word observations to 4,000-word deep dives. Not everything is polished. That's by design.
This guide is derived from analyzing 127 posts across joelhooks.com (2012–2026).
For curated voice examples from the corpus, see references/voice-examples.md.
Core Voice Rules
1. Write conversationally in first person
Address the reader as "you." Use "I" and "we" freely. Write like you're explaining something to a smart friend over coffee — not like you're writing a blog post.
- Contractions always: it's, doesn't, I've, they're, we've, can't, won't
- Never stilted: "one might consider" → "you might try"
- No "Dear reader" or "In this post I will" throat-clearing
More from joelhooks/joelclaw
cli-design
Design and build agent-first CLIs with HATEOAS JSON responses, context-protecting output, and self-documenting command trees. Use when creating new CLI tools, adding commands to existing CLIs (joelclaw, slog), or reviewing CLI design for agent-friendliness. Triggers on 'build a CLI', 'add a command', 'CLI design', 'agent-friendly output', or any task involving command-line tool creation.
131k8s
>-
88docker-sandbox
Create, manage, and execute agent tools (claude, codex) inside Docker sandboxes for isolated code execution. Use when running agent loops, spawning tool subprocesses, or any task requiring process isolation. Triggers on "sandbox", "isolated execution", "docker sandbox", "safe agent execution", or when working on agent loop infrastructure.
86contacts
Add, enrich, and manage contacts in Joel's Vault. Fire the Inngest enrichment pipeline for full multi-source dossiers, or create quick contacts manually. Use when: 'add a contact', 'enrich this person', 'who is X', 'VIP contact', 'update contact', or any task involving the Vault/Contacts directory.
64task-management
Manage Joel's task system in Todoist. Triggers on: 'add a task', 'create a todo', 'what's on my list', 'today's tasks', 'what do I need to do', 'remind me to', 'inbox', 'complete', 'mark done', 'weekly review', 'groom tasks', 'what's next', or when actionable items emerge from other work. Also triggers when Joel mentions something he needs to do in passing — capture it.
54skill-review
Audit and maintain the joelclaw skill inventory. Use when checking skill health, fixing broken symlinks, finding stale skills, or running the skill garden. Triggers: 'skill audit', 'check skills', 'stale skills', 'skill health', 'skill garden', 'broken skill', 'skill review', 'fix skills', 'garden skills', or any task involving skill inventory maintenance.
49