creating-an-agent_skill

Overview

This skill guides creation of specialized Claude subagents for Claude Code plugins or the Task tool. It covers writing effective agent descriptions for auto-delegation, choosing minimal toolsets, structuring system prompts, and verifying agent behavior through tests. Follow it to build focused, reliable agents that behave consistently across runs.

How this skill works

The skill explains what to include in an agent file (frontmatter, description, tools, model) and how the description drives Claude's auto-delegation. It recommends tool selections matched to responsibilities, a clear role/responsibilities/workflow/output structure in the system prompt, and a testing loop to validate delegation, workflow adherence, and edge-case handling. It emphasizes iterative refinement when agents fail tests.

When to use it

• When a task needs specialized expertise or consistent, repeatable behavior
• When tool restrictions improve safety or reduce accidental changes
• When complex workflows benefit from context isolation across runs
• When you want predictable auto-delegation for recurring task types

Best practices

• Write the description in third person, starting with 'Use when...', and include specific triggers and file patterns
• Include only the tools the agent actually needs to stay focused and predictable
• Define clear responsibilities, a step-by-step workflow, and a strict output format
• Specify constraints: what the agent must not do and when to escalate
• Choose a model aligned to task complexity (haiku < sonnet < opus)
• Test without the agent, then with the agent, plus edge-case scenarios

Example use cases

• Security code reviewer: Read, Grep, Glob; scans for injection, auth flaws, and insecure deps
• Researcher: Read, WebSearch, WebFetch; synthesize API docs and cite sources
• Implementor: Read, Edit, Write, Bash; follow TDD to add a failing test, implement, run tests, commit
• Task spawner: TaskCreate/TaskUpdate; coordinate multi-step plans and hand off subtasks