creating-subagents
Guide for creating custom Claude Code subagents (Task tool agents). Use when building specialized autonomous agents for specific domains or workflows. Covers agent definition, frontmatter options, tool restrictions, and spawning patterns.
npx skills add majiayu000/claude-skill-registry --skill creating-subagents-hgeldenhuys-claude-code-sdk --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Creating Subagents Build specialized AI agents for Claude Code that handle domain-specific tasks with custom configurations, tools, and system prompts. ## Quick Reference | Element | Requirement | |---------|-------------| | Location | `.claude/agents/` (project) or `~/.claude/agents/` (user) | | Filename | `agent-name.md` | | Name | Lowercase, hyphens only (e.g., `code-reviewer`) | | Required Fields | `name`, `description` | | Optional Fields | `tools`, `model`, `permissionMode`, `skills`, `hooks` | ## What Are Subagents? Subagents are specialized AI assistants that Claude Code delegates tasks to. They provide: - **Separate Context** - Own context window, prevents main conversation pollution - **Custom Tools** - Restricted or expanded tool access - **Specialized Prompts** - Domain-specific instructions and expertise - **Flexible Models** - Can use different models (opus, sonnet, haiku) When Claude encounters a task matching a subagent's expertise, it spawns the subagent via the **Task tool**, which works independently and returns results. ## Built-in vs Custom Agents ### Built-in Agents Claude Code includes several built-in agents: | Agent | Model | Mode | Purpose | |-------|---
- Quick Reference
- What Are Subagents?
- Built-in vs Custom Agents
- Built-in Agents
- When to Create Custom Agents
- Agent Definition Structure
- Frontmatter Fields
- Model Options
- Permission Modes
- Critical Constraint
- Hooks in Agent Frontmatter (2.1.0+)
- Conditional Rules with Hooks
- Creating an Agent
- Via /agents Command (Recommended)
Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
echo "Blocked: Only SELECT queries are allowed" >&2
exit 2
fi
exit 0
Project agent
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
claude --agents '{What does the creating-subagents skill do?
Guide for creating custom Claude Code subagents (Task tool agents). Use when building specialized autonomous agents for specific domains or workflows. Covers agent definition, frontmatter options, tool restrictions, and spawning patterns.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill creating-subagents-hgeldenhuys-claude-code-sdk --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.