Gnothi Claude Code

A subagent is a fresh Claude instance that does a noisy, self-contained job in its own context window and hands back only the summary. Learn to delegate codebase searches and code reviews, restrict each agent's tools and model, and avoid the blank-context pitfall that produces confident wrong answers.

Episode page & show notes

Visit website

A subagent is a fresh Claude instance that does a self-contained job in its own context window and hands back only a summary. This episode covers using them the Act I way: one-off delegation to keep your main session's context clean.

Why isolation matters. The context window fills fast and Claude's performance degrades as it does. From Anthropic's context-window walkthrough: a research subagent read ~6,100 tokens of files and returned a 420-token result. The reading never touched your main thread. The best-practices guide calls subagents one of the most powerful tools available because context is your fundamental constraint.

The Agent tool. As of Claude Code 2.1.63 the Task tool was renamed to Agent (old Task(...) references still work as aliases). Subagents cannot spawn other subagents, which is why the orchestrator pattern needs agent teams later.

Built-in subagents. Explore (read-only, Haiku, codebase search), Plan (read-only, used in plan mode), general-purpose (all tools, inherits your model), plus helpers statusline-setup and claude-code-guide. Explore and Plan skip CLAUDE.md and git status to stay fast.

Custom subagents. Markdown files with YAML frontmatter in .claude/agents/ (project, checked into git) or ~/.claude/agents/ (user). The fields that matter: name, description (drives automatic delegation), tools (allowlist; omit to inherit all), and model (sonnet/opus/haiku/full ID/inherit). Manage them with the /agents command. See Create custom subagents.

Proactive delegation. Put "use proactively" in the description field so Claude reaches for the agent on its own.

Worked examples. A codebase-search delegation that keeps file reads out of your window, and the official read-only code-reviewer (restricted to Read, Grep, Glob, Bash) that judges your diff with fresh eyes.

Subagent vs skill vs slash command. A skill runs in your main context; a subagent runs isolated and returns a summary; a slash command is a typed entry point. Offload noisy, self-contained work to a subagent.

The pitfall. Subagents start blank, with no conversation history. Vague delegation produces confident, wrong answers. Scope tightly and restate load-bearing constraints. Plus the costs: tokens still get spent, cold-start latency, and no mid-task steering (a subagent can't even ask you a clarifying question).

You keep pasting the same procedure into chat. Package it once as a skill, a folder with a SKILL.md, and Claude loads it on demand when the task matches, deep when you need it and nearly free when you don't. We build one from scratch, wire live shell output straight into it, and fix the number one reason a good skill silently never fires.

Episode page & show notes

Visit website

Episode 5 of Act I. Custom slash commands turned a repeated prompt into one word. Skills are the next rung: a folder of reusable expertise Claude pulls in on its own when the task matches, plus supporting files and scripts that ride along.

The core idea: progressive disclosure. Three loading levels. The name and description are always loaded (~100 tokens each). The SKILL.md body loads only when the skill is triggered. Reference files and scripts load only when referenced, and scripts execute without their code ever entering context. That's why a 2,000-line skill costs almost nothing on the days you don't use it. See Claude Code's skills documentation and the Agent Skills overview.

The copyable workflow. Build a summarize-changes skill: YAML frontmatter with a trigger-shaped description, plus a body that injects live git diff output using the !`command` dynamic-context syntax. Where skills live (personal in ~/.claude/skills/, project in .claude/skills/ committed to git so the team inherits them, plus plugin and managed scope), name-collision precedence, and live reload with no restart. A worked second example: a Postgres migrations skill with a bundled template and a type-generation step.

The knobs that matter. disable-model-invocation and user-invocable to control who triggers a skill, allowed-tools and disallowed-tools tying back to the permissions episode, named arguments, and a peek at context: fork.

When to use what. Facts that are always true go in CLAUDE.md; a prompt you retype becomes a command; a procedure with depth becomes a skill; a task you want quarantined becomes a subagent (coming up next).

The pitfall: the skill that never fires. Almost always a vague description, the only thing Claude sees before invoking. How to diagnose it with "what skills are available?" and /doctor, the description-budget truncation that bites once you have many skills, and the opposite fix when a skill triggers too eagerly. Plus bundled skills, treating untrusted skills like untrusted software, and letting Claude author and refine the skill for you. From Anthropic's skill-authoring best practices.

You've been using the slash commands Claude Code ships with. Now write your own, and wire the hooks that fire on their own. Bundle a repeatable workflow into a command you trigger with a slash, then back it with hooks that enforce the rules a command can only ask for: build a /commit command, auto-lint after every edit, block writes to your migrations folder, and force the tests to pass before a turn can end.

Episode page & show notes

Visit website

Episode 3 covered the slash commands Claude Code ships with. This one is about writing your own, plus the automation that fires whether Claude remembers it or not. Two primitives, one rule for choosing between them: a custom slash command is a shortcut you trigger; a hook is a guarantee that runs on its own.

Custom slash commands. Where they live (a per-command folder under your project's .claude or your home .claude, with the folder name becoming the command), the SKILL.md file and its YAML frontmatter, and the fields that matter: description, argument-hint, allowed-tools, model, and disable-model-invocation. Passing arguments with $ARGUMENTS and positional $1/$2, injecting live shell output into the prompt with the !`...` prefix, and pre-approving tools so a workflow runs without permission prompts. Worked example: a /commit command that stages, writes a real message, pushes, and opens a PR. From the skills documentation.

Hooks. The lifecycle events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart/End, compaction, notifications, subagent events), how they're configured under the hooks key in settings.json, the matcher syntax, the JSON a hook receives on stdin, and how it answers back through exit codes (0 success, 2 blocks) and a decision JSON that can allow, deny, ask, modify tool input, or add context. Three hooks worth stealing: auto-lint and format after every edit, block writes to the migrations folder, and a Stop hook that forces tests to pass before a turn can end. From the hooks documentation.

The pitfall. Putting an "always" or "never" rule inside a command's prose and trusting it. Command instructions are advice, like CLAUDE.md; if the cost of the model forgetting is real, that rule belongs in a hook. Plus quick traps: hook timeouts, unquoted arguments, and vague descriptions that never auto-invoke. Browse what you've built with /hooks, /skills, and /help.

A tour of the commands that ship in the box, the four steering keys you will use every run, and the decision you make constantly: clear versus compact, plus how to spot when compaction silently drops the context you were relying on.

Episode page & show notes

Visit website

Episode three of the OCDevel Claude Code arc, and the first one that's purely about speed. You can already drive a session from episodes one and two. This one makes you fast: the commands that ship in the box, and the keyboard moves you stop thinking about.

What we cover:

Recency note for mid-2026: /vim moved into /config → Editor mode (removed in 2.1.92), /cost is now an alias for /usage, and the auto-compact threshold is version-dependent. Verify against /help in your own install.

Next episode: writing your own custom slash commands.

You can't automate a tool you don't trust. This episode is the control surface: where settings live and which file wins, how to write tight allow/ask/deny permission rules (the real fence, not CLAUDE.md), the permission modes and the Shift+Tab plan-to-act toggle, and the slash commands a power user reaches for first, including the /rewind safety net. Plus the one pitfall everyone hits: the overly broad Bash(*) allow rule.

Episode page & show notes

Visit website

Episode 1 got a session running. This one makes it safe to leave running. We cover the control surfaces that turn Claude Code from a sharp tool you babysit into one you actually trust.

Settings files and precedence. The four scopes you touch (~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, and enterprise-managed settings), which file wins when they collide, and the catch that permission rules merge across layers instead of overriding, with deny always winning. See the settings reference.

The permission grammar. Why rules are enforced by Claude Code, not the model, so CLAUDE.md is advice and permission rules are the fence. The allow/ask/deny lists and their deny-first evaluation order. Bash glob patterns and the space-before-star word boundary, compound-command parsing, wrapper stripping (and the devbox run footgun), and gitignore-style path anchors for Read/Edit/Write. From the permissions reference.

Modes and the plan-to-act toggle. default, acceptEdits, plan, plus auto, dontAsk, and the genuinely dangerous bypassPermissions (--dangerously-skip-permissions). The Shift+Tab cycle, the plan-mode workflow, and editing a proposed plan with Ctrl+G. See the permission modes reference.

Slash commands a power user hits early. /clear vs /compact, /context, /config (where the removed /vim moved), /model, /permissions, /cost (now an alias for /usage), /review and /code-review, and the safety net of the episode: /rewind and double-Esc, plus the checkpointing gotcha that bash-modified files aren't tracked.

The pitfall: the overly broad Bash(*) allow rule, why argument-constraining Bash patterns are fragile, and the deny-curl-use-WebFetch pattern instead. If you've stopped seeing prompts but never wrote specific allow rules, that's your cue to open /permissions and find what's too wide.

How the gather-act-verify loop actually works and how to steer it without starting over. What belongs in your CLAUDE.md project memory and what to keep out, generating a first draft with /init, and resuming yesterday's session instead of re-explaining everything. Plus the pitfall every beginner hits, context going stale, and the habits that fix it.

Episode page & show notes

Visit website

The first episode of the OCDevel Claude Code arc, the show that climbs from driving one session by hand all the way to a pipeline that ships to production while you're on the beach. This one is the on-ramp: everything you need to be genuinely productive in your first session, with no single primitive over-explained.

What we cover:

Recency notes for mid-2026: Claude Code is on the 2.1 line with the native installer now recommended over npm, and your default model depends on your plan (Opus 4.8 on Max/API, Sonnet 4.6 on Pro). See Model configuration.

Next episode: settings.json, permissions, and plan mode in depth.