Agent Development for Claude Code Plugins

--- name: agent-development description: This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins. version: 0.1.0 --- # Agent Development for Claude Code Plugins ## Overview Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities. Key concepts: - Agents are FOR autonomous work, commands are FOR user-initiated actions - Markdown file format with YAML frontmatter - Triggering via description field with examples - System prompt defines agent behavior - Model and color customization ## Agent File Structure ### Complete Format ``markdown --- name: agent-identifier description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios. model: inherit color: blue tools: ["Read", "Write", "Grep"] --- You are [agent role description]... ## When to invoke [Two to four representative scenarios written as prose, e.g.:] - **[Scenario name].** [What the situation looks like and what the agent should do.] - **[Scenario name].** [Same.] **Your Core Responsibilities:** 1. [Responsibility 1] 2. [Responsibility 2] **Analysis Process:** [Step-by-step workflow] **Output Format:** [What to return] ` ## Frontmatter Fields ### name (required) Agent identifier used for namespacing and invocation. **Format:** lowercase, numbers, hyphens only **Length:** 3-50 characters **Pattern:** Must start and end with alphanumeric **Good examples:** - code-reviewer - test-generator - api-docs-writer - security-analyzer **Bad examples:** - helper (too generic) - -agent- (starts/ends with hyphen) - my_agent (underscores not allowed) - ag (too short, < 3 chars) ### description (required) Defines when Claude should trigger this agent. **This is the most critical field** : it is loaded into context whenever the agent is registered, so the harness can decide when to dispatch. **Must include:** 1. Triggering conditions ("Use this agent when...") 2. A short prose summary of the typical trigger scenarios 3. A pointer to a "When to invoke" section in the agent body for the detailed worked scenarios **Format:** ` Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios. ` **Best practices:** - Name 2-4 trigger scenarios in the prose summary - Cover both proactive (assistant invokes itself) and reactive (user requests) triggering - Cover different phrasings of the same intent - Be specific about when NOT to use the agent - Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptions ### model (required) Which model the agent should use. **Options:** - inherit - Use same model as parent (recommended) - sonnet - Claude Sonnet (balanced) - opus - Claude Opus (most capable, expensive) - haiku - Claude Haiku (fast, cheap) **Recommendation:** Use inherit unless agent needs specific model capabilities. ### color (required) Visual identifier for agent in UI. **Options:** blue, cyan, green, yellow, magenta, red **Guidelines:** - Choose distinct colors for different agents in same plugin - Use consistent colors for similar agent types - Blue/cyan: Analysis, review - Green: Success-oriented tasks - Yellow: Caution, validation - Red: Critical, security - Magenta: Creative, generation ### tools (optional) Restrict agent to specific tools. **Format:** Array of tool names `yaml tools: ["Read", "Write", "Grep", "Bash"] ` **Default:** If omitted, agent has access to all tools **Best practice:** Limit tools to minimum needed (principle of least privilege) **Common tool sets:** - Read-only analysis: ["Read", "Grep", "Glob"] - Code generation: ["Read", "Write", "Grep"] - Testing: ["Read", "Bash", "Grep"] - Full access: Omit field or use ["*"] ## System Prompt Design The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly. ### Structure **Standard template:** ``markdown You are [role] specializing in [domain]. Your Core Responsibilities: 1. [Primary responsibility] 2. [Secondary responsibility] 3. [Additional responsibilities...] Analysis Process: 1. [Step one] 2. [Step two] 3. [Step three] [...] Quality Standards: - [Standard 1] - [Standard 2] Output Format: Provide results in this format: - [What to include] - [How to structure] **Edge Case