agent-development

intent

agent development is the skill for building autonomous subprocesses that handle complex, multi-step tasks independently. use this when you need to create a new agent, configure agent triggering logic, design system prompts, or validate agent file structure. agents differ from commands in that they run autonomously based on triggering conditions rather than explicit user invocation.

inputs

required inputs:

• agent purpose statement (what the agent does and when it triggers)
• triggering examples (2-4 concrete scenarios showing when claude should invoke the agent)
• system prompt foundation (role, responsibilities, workflow, output format, edge cases)
• agent identifier (3-50 character lowercase slug with hyphens, must start and end alphanumeric)

optional inputs:

• specific model requirement (sonnet, opus, haiku; default is inherit from parent)
• tool restrictions list (array of tool names to limit agent access; default is all tools)
• color assignment (blue, cyan, green, yellow, magenta, red for ui differentiation)
• reference examples from examples/complete-agent-examples.md or agent creation prompt at examples/agent-creation-prompt.md

procedure

1. define agent scope

   • input: agent purpose statement, domain context
   • output: clear one-sentence intent and list of responsibilities (2-5 items)
   • action: write what the agent specializes in and what it does not do

2. create agent identifier

   • input: agent purpose
   • output: slug 3-50 chars, lowercase, hyphens only, alphanumeric start/end
   • action: examples: code-reviewer, test-generator, api-docs-writer (not: helper, -agent-, my_agent, ag)

3. write triggering description with examples

   • input: agent purpose, use cases, alternative phrasings
   • output: description field (200-1000 chars) with 2-4 concrete blocks
   • action: each example must include context (situation), user request, assistant response (how claude invokes agent), and commentary (why this triggers the agent)

4. design system prompt

   • input: responsibilities, workflow, quality standards, edge cases
   • output: markdown body (500-3000 chars) with structure: you are [role], core responsibilities (numbered), analysis process (numbered steps), quality standards (bullet list), output format (explicit structure), edge cases (how to handle specific scenarios)
   • action: write in second person, be specific about process steps, include 3-5 edge cases the agent will encounter

5. select model and tools

   • input: agent complexity, required capabilities, performance needs
   • output: model field (recommended: inherit), tools array (optional, principle of least privilege)
   • action: use inherit unless agent needs specific model. examples: read-only agents get ["Read", "Grep", "Glob"], code generation gets ["Read", "Write", "Grep"], testing gets ["Read", "Bash", "Grep"]

6. assign visual color

   • input: agent type, existing agent colors in plugin
   • output: color field (one of: blue, cyan, green, yellow, magenta, red)
   • action: blue/cyan for analysis and review, green for success-oriented tasks, yellow for validation and caution, red for security and critical tasks, magenta for creative generation

7. assemble frontmatter

   • input: identifier, description, model, color, tools (optional)
   • output: yaml frontmatter block (--- delimited) with all required and optional fields
   • action: follow exact field order: name, description, model, color, tools

8. validate agent file

   • input: complete agent markdown file
   • output: validation report or error list
   • action: check identifier format, description length (10-5000 chars), system prompt length (20-10000 chars), triggering examples present, no first-person pronouns in system prompt, all frontmatter fields valid

9. test triggering behavior

   • input: agent file with triggering examples, test scenarios similar to examples
   • output: confirmation that agent triggers or list of triggering issues
   • action: write test scenario matching example context and phrasing, verify claude loads correct agent, verify agent produces expected output, test edge cases mentioned in system prompt

decision points

• if agent needs specific model capabilities (e.g., only opus can handle this task): set model field to sonnet, opus, or haiku. else set model to inherit.

• if agent should have restricted tool access (security, performance, or focus): include tools array with specific tool names (e.g., ["Read", "Grep"]). else omit tools field to grant all tools.

• if triggering is ambiguous (agent triggers in multiple scenarios or sounds similar to another agent): add commentary to each example explaining exactly why that agent should trigger in that context and when not to trigger. clarify boundaries.

• if system prompt exceeds 10000 characters: refactor to remove redundant sections or combine similar edge cases. keep process steps and output format explicit.

• if no examples exist for a use case: do not create the agent or add examples by generating real user scenarios from chat logs or plugin documentation.

• if identifier conflicts with existing agent name: append version suffix (e.g., code-reviewer-v2) or rename to avoid collision.

output contract

successful agent development produces a markdown file with:

• location: agents/[identifier].md inside plugin directory
• frontmatter: valid yaml block with name, description (2-4 examples), model, color, and optional tools
• system prompt body: 500-3000 characters structured as: role statement, core responsibilities (numbered), analysis process (numbered), quality standards (bullet list), output format (explicit), edge cases (how to handle)
• triggering examples: 2-4 blocks inside description, each with context, user request, assistant response, and commentary
• validation status: passes validate-agent.sh script with no errors
• test results: agent triggers correctly on test scenarios matching example phrasings

outcome signal

you know agent development worked when:

• claude correctly triggers the agent when given prompts matching the examples in the description
• the agent executes its system prompt workflow without ambiguity or errors
• test scenarios similar to the triggering examples invoke the agent as expected
• the agent does not trigger in scenarios where it should not (boundaries respected)
• the agent output matches the defined output format in the system prompt
• validate-agent.sh script returns clean validation with no warnings
• other agents in the plugin have distinct colors and do not trigger unexpectedly