Create subagents

A subagent is a Markdown file whose body is a system prompt. It runs in its own context, optionally with fewer tools or another model, and returns a summary.

Related skills in this group: create-skill (SKILL.md folders), create-rule, create-hook, create-command, convert-as-skill, and create-agents-md (AGENTS.md).

Principles

1. The description is the router. The model decides to delegate from description alone. Write what it does, when to use it, and the words a user would say.
2. Assume the model is smart. Add only what it lacks: your conventions, your commands, the traps. Cut explanations of common knowledge.
3. One job per agent. If it needs "and", split it. If two overlap, merge them.
4. Smallest authority. Grant the fewest tools and the smallest model that works. Read-only unless it must write.
5. Keep the prompt short. About 80 lines. Link to rules and references instead of pasting them.
6. Test by using it. An untested description is a guess.

Choose the right mechanism

A skill can run as a subagent: in Claude Code set context: fork and agent: <type> (see create-skill).

What do you want to do?

1. New subagent → New subagent
2. Audit existing agents → Audit
3. New or oversized skill → use create-skill

Infer the intent from the request; ask only if it is unclear. If the conversation already described a recurring task, derive the agent from it instead of asking again.

New subagent

1. Check for overlap. List the existing agents (project, user, plugin). Extend or merge before creating. A large roster of vague agents makes delegation worse.
2. Pick the location. Shared with the team: the project's agents/ (plugin) or .claude/agents/ / .cursor/agents/. Personal: ~/.claude/agents/ or ~/.cursor/agents/. Cursor also reads .claude/agents and .codex/agents, so one file can serve several tools. See subagents.md.
3. Write the frontmatter from templates/subagent.md: name, a description that says when to call it, tools (or readonly), and model only if the work is mechanical.
4. Write the body as a short system prompt: mission, the inputs the caller must pass, numbered steps, how to verify, the output format, an explicit "Do not" list. About 80 lines at most.
5. Lint with node scripts/lint.mjs <file>.
6. Test: ask for it by name ("use the X subagent to ..."), then give a task that should delegate on its own. Adjust the description until it triggers on the second and not on unrelated tasks.

Audit

1. Run node scripts/lint.mjs <path> on an agent file or a directory of agents. The same linter also checks skill folders (create-skill uses it).
2. Walk the checklist in audit.md for what a linter cannot judge (is the description specific, are the steps actionable, is the tool list minimal).
3. Report a score and findings by priority, each with a concrete fix: Broken (will not load or trigger), Weak (loads but misroutes or wastes context), Polish.
4. Apply only the fixes the user asked for. Preserve the author's structure and voice.

Related skills

• create-skill: the job is a procedure the main agent runs, not a delegate.
• create-command: the job is a saved prompt you type as /name.
• create-hook: the job must run on an event, with no model decision.
• create-rule: the guidance must apply on every task.
• convert-as-skill: turn an existing agent into a skill.

Done when

• name matches the filename; description states when to call it; the linter reports no errors.
• Tools and model are the minimum that works.
• It was exercised at least once on a real task, and the description triggered correctly.
• No overlap with an existing agent, or the overlap was merged.