Agent Development

Create a Markdown file in the plugin's agents/ directory with YAML frontmatter containing name, description, model, and color fields, followed by a system prompt body. You can generate the configuration with AI assistance or write it manually, then validate it with the validate-agent.sh script.

Agent files require name, description, model, and color fields, with tools being optional. The name must be 3-50 lowercase characters with hyphens, the description must include triggering conditions with example blocks, and model is typically set to inherit.

Write a description field starting with triggering conditions and include 2-4 example blocks showing context, user message, assistant response, and commentary explaining why the agent triggers. Cover both explicit requests and proactive triggering scenarios with varied phrasings.

Yes, the optional tools frontmatter field accepts an array of tool names like Read, Write, Grep, and Bash to limit agent access. If omitted, the agent has access to all tools, but restricting to the minimum needed follows the principle of least privilege.

Triggering failures usually come from descriptions lacking concrete examples, missing context in example blocks, or commentary that does not explain the triggering logic. Add more examples covering different user phrasings and ensure examples show the assistant invoking the agent.

System prompts must be between 20 and 10,000 characters, with 500-3,000 characters recommended for standard agents. Prompts should use second person, define clear responsibilities and process steps, and specify the expected output format.