Agent Development

Agent Development for Claude Code Plugins

Overview

Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Each agent is a markdown file in the agents/ directory with YAML frontmatter defining its configuration and a markdown body serving as its system prompt.

Canonical agent frontmatter template (MANDATORY shape)

This is the template every new agent MUST follow. Deviating from this shape is the #1 cause of agents that never trigger.

---
name: my-agent                                    # REQUIRED: kebab-case, 3-50 chars, alphanumeric start/end
model: inherit                                    # REQUIRED: always `inherit` unless you have a hard reason
color: blue                                       # RECOMMENDED: one of blue/cyan/green/yellow/magenta/red
tools: Read, Write, Edit, Glob, Grep, Bash        # RECOMMENDED: minimal set; omit for full access
description: |
  One-sentence summary of what the agent does. PROACTIVELY activate for: (1) concrete trigger, (2) concrete trigger, ..., (N) concrete trigger. Provides: comma-separated capability nouns.

  <example>
  Context: Realistic situation where the agent should fire
  user: "A realistic user quote -- the kind of thing someone would actually type"
  assistant: "Short 1-2 sentence response. Mention loading a specific skill if relevant."
  <commentary>Triggers for specific-keyword-1, specific-keyword-2, specific-keyword-3</commentary>
  </example>

  <example>
  Context: Another realistic situation covering a different capability
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A debugging / troubleshooting scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A "when to pick this vs. that" scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>
---

You are [role] specializing in [domain]. [Lean orchestrator body -- see "Lean Orchestrator Pattern" below.]

Hard rules for the frontmatter

1. `name:` is required. Do NOT use the deprecated agent: true flag — that pattern is legacy and results in an unnamed agent that cannot be referenced or routed to reliably. If you find agent: true in an existing file, replace it with name: <kebab-name-from-filename>. 2. `model: inherit` is required. Never hard-code a model unless the agent has a documented capability requirement. 3. `description:` MUST include the enumerated `PROACTIVELY activate for: (1)... (2)... (N)...` pattern AND a `Provides: ...` capability list. A description that only says "Use this agent for help with X" will not route reliably. 4. `<example>` blocks are conditional, not unconditional. Whether the description needs <example> blocks depends on the agent's body word count — see "Example-block requirement by agent body size" below. Lean orchestrators deliberately omit them; fat agents need them. Do not blanket-require examples on every agent. 5. Use `description: |` (YAML block scalar) whenever the description spans multiple lines or contains <example> blocks. A folded scalar (>) or implicit flow scalar will mangle the examples. 6. Do NOT put cross-cutting boilerplate (Windows path rules, documentation policy, etc.) inside the YAML `description:` block. That text is used for routing-match, and boilerplate that appears in many agents poisons the signal. Put it in the markdown body under a clearly named ## Windows file path requirements section (or similar) instead.

Example-block requirement by agent body size (UNIFIED RULE)

The number of <example> blocks a description needs is a function of the agent's markdown body word count. This rule reconciles two earlier conflicting recommendations ("always add 4-6 examples" vs. "lean orchestrators don't need examples") into a single tier table that authoring guidance, the canonical checklist, and scripts/validate_plugins.py all share.

The validator only flags "missing examples" when the body crosses 2,500 words (AGENT_EXAMPLES_THRESHOLD_WORDS). Lean orchestrators under that threshold pass cleanly without examples — that absence is by design.

Authoring distilled: decide lean-orchestrator vs. fat-agent first; if lean, the PROACTIVELY activate for: enumeration carries routing and examples are not required. When refactoring fat -> lean, stripping examples is a legitimate part of the refactor. When auditing, compute body word count BEFORE recommending example-block fixes — see "Pre-recommendation intent check" below.

Deprecated / broken patterns to migrate

Frontmatter Fields Reference

Detailed rules for each frontmatter field (name, description, model, color, tools) live in references/frontmatter-fields-reference.md. Highlights:

• name — kebab-case, 3-50 chars, alphanumeric start/end; role-based convention (code-reviewer, domain-expert).
• description — most critical field; must include PROACTIVELY activate for: (1)... (N)... enumeration and Provides: ... capability list. <example> blocks gated by the body-word-count tier table above.
• model — inherit is the default; only deviate with a documented capability reason.
• color — blue/cyan (analysis), green (generation), yellow (validation), red (critical/security), magenta (creative/architecture).
• tools — principle of least privilege; common: Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Skill, Agent. MCP tools as mcp__server__tool.

Load references/frontmatter-fields-reference.md when authoring or auditing a real agent.

System Prompt Design

The markdown body becomes the agent's system prompt. Write in second person ("You are...", "You will..."). Required sections: Core Responsibilities, Process, Quality Standards, Output Format, Edge Cases. DO be specific and define output clearly; DON'T write in first person, be vague, or embed domain knowledge that belongs in skills. Full template + DO/DON'T list: references/design-principles-and-mistakes.md.

Lean Orchestrator Pattern (CRITICAL)

An agent body must be a lean orchestrator, NOT a domain knowledge dump. The agent delegates to skills for detailed knowledge.

Agent Body Size Limits

What Belongs in the Agent Body

What Does NOT Belong in the Agent Body

• Detailed domain knowledge — belongs in skills
• Complete CLI/API references — belongs in skill references/
• Full code examples — belongs in skill examples/
• Duplicated skill content — if it's in a skill, do NOT repeat it in the agent

Anti-Pattern: Content Duplication

NEVER duplicate content between the agent body and skills. This is the most common mistake and causes massive context bloat.

Bad: Agent body contains a full "Plugin.json Schema" section AND the plugin-master skill also contains it. Good: Agent body says "For plugin.json schema details, load plugin-master:plugin-master" and keeps only a 1-sentence summary.

Lean Orchestrator Template

You are [role] specializing in [domain].

## Skill Activation - CRITICAL
[Topic-to-skill mapping table -- this is the heart of the agent]

## Core Responsibilities
[2-5 bullet points on what this agent does]

## Process
[5-7 step workflow for handling user requests]

## Quality Standards
[Brief checklist -- 5-10 items]

## Output Format
[What to include in responses]

Description Size Limits

Agent descriptions should be concise and effective:

Agent Design Principles & Common Mistakes

Detailed design principles (agent-first design, single responsibility, skill integration, preventing trigger phrase overlap) and the full Common-Mistakes table live in references/design-principles-and-mistakes.md. Core distillation:

• One expert agent per plugin, named {domain}-expert. Users converse, not navigate menus.
• Single responsibility per agent; multi-topic needs become skills, not new agents.
• Skill activation instructions belong in the system prompt.
• Trigger-phrase overlap between skills must be audited and disambiguated in the skill activation table.

Validation Checklist

Before finalizing an agent:

• [ ] Name: 3-50 chars, lowercase, hyphens, starts/ends alphanumeric
• [ ] Description: includes PROACTIVELY activate for: enumeration and Provides: capability list
• [ ] <example> blocks present if and only if required by the agent's body word count (see "Example-block requirement by agent body size" tier table). Lean orchestrators under 2,500 words are exempt.
• [ ] If examples ARE present, every skill the agent delegates to has at least one example that routes to it
• [ ] No trigger phrase overlap: no ambiguous keyword claimed by multiple skills without disambiguation
• [ ] Model: set to inherit (unless specific need)
• [ ] Color: appropriate for agent function
• [ ] Tools: restricted to minimum needed (or omitted for full access)
• [ ] System prompt: second person, clear responsibilities, defined process and output
• [ ] Frontmatter: valid YAML with all required fields
• [ ] File location: agents/agent-name.md

Testing

1. Write agent with specific triggering examples 2. Use similar phrasing to examples in your test queries 3. Verify Claude loads the agent for matching requests 4. Test that the agent follows its defined process 5. Check output matches defined format 6. Test edge cases mentioned in system prompt

Common Mistakes

Full table (vague descriptions, model overrides, tool over-grants, cross-cutting boilerplate in every skill, re-adding examples to a lean orchestrator, etc.) lives in references/design-principles-and-mistakes.md.

Pre-recommendation intent check (audit caveat)

Before recommending a fix to an existing agent — especially one that involves re-adding content that has been stripped — confirm the apparent defect is not the result of a deliberate prior decision. Example-block stripping during lean-orchestrator refactors is routine and intentional; a follow-up audit that flags "agent missing examples" without checking word count produces a false-positive backlog of contradictory remediation work.

Short rule: before listing any agent finding, run the three-question intent check (size tier, git log, validator output). Only if all three say "real defect" should it appear in the audit report.

Full check, with rationale, expanded list of stripped-on-purpose patterns, and the authoring-vs-auditing contrast: see references/validation-and-audits.md.

Validation by scripts/validate_plugins.py

The repo ships a read-only quality gate at scripts/validate_plugins.py. It is the single source of truth for what counts as "good" agent frontmatter in this marketplace. When the validator and this skill disagree, the validator wins.

Quick invocations:

python scripts/validate_plugins.py                    # whole marketplace
python scripts/validate_plugins.py --plugin my-plugin # one plugin
python scripts/validate_plugins.py --strict           # warnings fail the build

The complete rule tables (agent-level, skill-level, plugin-level) plus the list of known validator gaps live in references/validation-and-audits.md.

Agent Design Principles & Common Mistakes

System Prompt Structure Template

The markdown body of an agent becomes its system prompt. Write in second person.

You are [role] specializing in [domain].

## Core Responsibilities
1. [Primary responsibility]
2. [Secondary responsibility]

## Process
1. [Step one]
2. [Step two]
3. [Step three]

## Quality Standards
- [Standard 1]
- [Standard 2]

## Output Format
- [What to include]
- [How to structure results]

## Edge Cases
- [Situation]: [How to handle]

Best Practices

DO:

• Write in second person ("You are...", "You will...")
• Be specific about responsibilities and process steps
• Define output format clearly
• Address edge cases
• Include skill activation instructions if the agent should load skills
• Keep the agent body as a lean orchestrator

DON'T:

• Write in first person ("I am...", "I will...")
• Be vague or generic ("help with stuff")
• Skip process steps
• Leave output format undefined
• Omit quality standards
• Embed domain knowledge that belongs in skills

Agent Design Principles (2025)

Agent-First Plugin Design

• Primary plugin interface is ONE expert agent named {domain}-expert
• Plugin named docker-master → agent named docker-expert
• Only 0-2 slash commands for automation workflows
• Users interact conversationally, not through command menus

Single Responsibility

Each agent should have a clear, focused purpose. Don't create "do everything" agents. If a plugin needs multiple capabilities, use one expert agent that loads different skills based on context.

Skill Integration

Expert agents should load relevant skills before answering. Include skill activation instructions in the system prompt:

## Skill Activation
When the user asks about [topic], load `plugin-name:skill-name` before responding.

Preventing Trigger Phrase Overlap Between Skills

When a plugin has multiple skills, their trigger phrases and description terms must not create ambiguity. If two skills both claim the same keyword (e.g., both "programmatic-development" and "tmdl-mastery" claim "TMDL"), the agent cannot reliably route requests.

Disambiguation rules: 1. Audit trigger terms across all skills — list every trigger phrase from every skill description side by side. Flag any term that appears in more than one skill. 2. Assign exclusive ownership — each ambiguous term must belong to exactly one skill. The other skill should use a more specific phrase (e.g., "TMDL file editing" vs. "programmatic deployment using TMDL"). 3. Add disambiguation hints to the agent's skill activation table — for terms that could route to multiple skills, add a clarifying note: "TMDL editing/syntax → tmdl-mastery; TMDL in deployment pipelines → programmatic-development". 4. Test with ambiguous queries — after writing descriptions, mentally test phrases like "help me with TMDL" and verify the routing is unambiguous.

Validation Checklist

Before finalizing an agent:

• [ ] Name: 3-50 chars, lowercase, hyphens, starts/ends alphanumeric
• [ ] Description: includes PROACTIVELY activate for: enumeration and Provides: capability list
• [ ] <example> blocks present if and only if required by the agent's body word count (see "Example-block requirement by agent body size" tier table). Lean orchestrators under 2,500 words are exempt.
• [ ] If examples ARE present, every skill the agent delegates to has at least one example that routes to it
• [ ] No trigger phrase overlap: no ambiguous keyword claimed by multiple skills without disambiguation
• [ ] Model: set to inherit (unless specific need)
• [ ] Color: appropriate for agent function
• [ ] Tools: restricted to minimum needed (or omitted for full access)
• [ ] System prompt: second person, clear responsibilities, defined process and output
• [ ] Frontmatter: valid YAML with all required fields
• [ ] File location: agents/agent-name.md

Testing

1. Write agent with specific triggering examples 2. Use similar phrasing to examples in your test queries 3. Verify Claude loads the agent for matching requests 4. Test that the agent follows its defined process 5. Check output matches defined format 6. Test edge cases mentioned in system prompt

Common Mistakes

Frontmatter Fields Reference

Detailed rules for each agent frontmatter field — name, description, model, color, tools. Authoritative source; SKILL.md links here.

name (required)

Agent identifier for namespacing and invocation.

Invalid names: ag (too short), -agent- (starts/ends with hyphen), my_agent (underscores)

description (required - most critical field)

Defines WHEN Claude should trigger this agent. Poor descriptions = agent never triggers.

Must include: 1. Triggering conditions phrased as PROACTIVELY activate for: (1)... (N)... 2. A Provides: ... capability list 3. <example> blocks only when required by the agent's body word count — see the tier table in "Example-block requirement by agent body size" above. For lean orchestrators under 2,500 body words, examples are optional and routinely omitted. 4. Both proactive and reactive triggering scenarios reflected in the PROACTIVELY activate for: enumeration

Good description pattern:

description: |
  Use this agent when the user needs help with [domain]. Trigger for:
  - [Scenario 1]
  - [Scenario 2]
  - [Scenario 3]

  <example>
  Context: [Specific situation]
  user: "[What user says]"
  assistant: "[How Claude responds and invokes agent]"
  <commentary>
  [Why this is the right agent for this request]
  </commentary>
  </example>

Common mistake: Vague descriptions without examples. "Helps with code review" will rarely trigger. Include concrete examples with exact user phrases.

Example block rules (when examples ARE included):

• Keep example blocks concise — assistant response should be 1-2 sentences, not full code
• When the agent body crosses 2,500 words, target 3-5 example blocks (caps at 7 to avoid dilution)
• Do NOT include full JSON schemas, code samples, or CLI output in examples
• Examples show when to trigger and how to respond, not the domain content itself

Skill coverage requirement (applies only when examples are present): If the agent description includes <example> blocks at all, every skill the agent delegates to should have at least one example that would route to it. Count skills, count examples, and verify coverage. This rule does NOT compel adding examples to a lean orchestrator that has none by design — for lean orchestrators, routing is driven by the PROACTIVELY activate for: enumeration and the skill activation table in the body, not by <example> blocks.

model (required)

Always use `inherit` unless the agent specifically needs a different capability level.

color (required)

Visual identifier in UI. Choose based on agent function:

Use distinct colors for different agents within the same plugin.

tools (optional)

Restrict agent to specific tools. Principle of least privilege - only grant what's needed.

# Read-only analysis
tools: ["Read", "Grep", "Glob"]

# Code generation
tools: ["Read", "Write", "Edit", "Grep", "Glob"]

# Full access (omit field entirely)
# tools: (not specified)

Common tool names: Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Skill, Agent

MCP tools use format: mcp__server-name__tool-name

Agent validation and audit caveats

This reference expands the agent-development SKILL.md on two related topics:

1. How scripts/validate_plugins.py enforces agent rules in this marketplace. 2. How to avoid the "contradictory audit" failure mode where a follow-up review recommends re-adding content that an earlier refactor deliberately removed.

Pre-recommendation intent check (audit caveat)

Before recommending a fix to an existing agent — especially one that involves re-adding content that has been stripped — confirm that the apparent defect is not the result of a deliberate prior decision. This caveat exists because example-block stripping during lean-orchestrator refactors is a routine and intentional operation, and a follow-up audit that flags "agent missing examples" without checking word count produces a false-positive backlog of contradictory remediation work.

Three-question check before listing an agent issue in an audit report

1. What does the size tier say? Compute the agent body word count. If it's under 2,500 words, the lean-orchestrator rule applies and missing examples are by design. The tier table lives in SKILL.md under "Example-block requirement by agent body size". 2. What does `git log` say? Has the agent been touched in a recent refactor that explicitly removed examples? A commit message like "lean orchestrator refactor" or "stripped redundant example blocks" is a strong signal that the absence is intentional. 3. What does `scripts/validate_plugins.py` say? Run the validator on the plugin. If it does not flag the agent, the absence is consistent with current marketplace policy. Do not invent stricter rules in the audit than the validator enforces.

Only after all three questions return "the defect is real" should missing examples appear as a remediation item.

Why this matters

The first-encounter failure mode that produced this reference: an earlier pass through the marketplace refactored fat agents into lean orchestrators and deliberately stripped <example> blocks below the 2,500-word threshold. A subsequent validator-and-audit pass then flagged every one of those agents as "missing examples" and recommended re-authoring them — which would have undone the refactor. The fix is structural: gate the example-block check on body word count (already in the validator) AND require auditors to check intent before listing example-block findings (this caveat).

The same pattern applies to other "stripped on purpose" content:

• Cross-cutting boilerplate moved from skill YAML descriptions to a shared body section — do not re-add it to YAML during a later sweep.
• Domain-knowledge dumps moved from agent bodies into skills — do not pull them back into the agent body during a "completeness" audit.
• Trigger-phrase enumerations consolidated to remove overlap — do not re-broaden them during a later "trigger coverage" audit.

In all of these cases the corrective action is the same: read the recent commit history, identify the intent behind the absence, and either honour it or open a discussion to revisit the design — never silently re-add removed content.

Validation by scripts/validate_plugins.py

The repo ships a read-only quality gate at scripts/validate_plugins.py. It is the single source of truth for what counts as "good" agent frontmatter in this marketplace. When the validator and the SKILL.md disagree, the validator wins — open a PR to bring the SKILL.md back into sync rather than working around the validator.

Agent-level rules the validator enforces (current as of 2026)

Skill-level rules the validator also enforces

Plugin-level rules

Recommended invocations

python scripts/validate_plugins.py                    # whole marketplace
python scripts/validate_plugins.py --plugin my-plugin # one plugin
python scripts/validate_plugins.py --strict           # warnings fail the build
python scripts/validate_plugins.py --json             # machine-readable

Known gaps in the current validator

The current implementation does not yet flag:

• Project-specific references (company names, internal repo paths) that violate the public-marketplace constraint.
• tools: field schema (presence and shape) — currently advisory only.
• Trigger-phrase overlap between sibling skills (this remains a manual audit step).
• Cross-skill duplicate content blocks (the DRY-gate is a manual grep, not a validator pass).

If you want to add or change a rule, change the validator first and update the table in this reference and the SKILL.md tier table in lockstep.

Authoring vs. auditing: a quick contrast

Treating these as the same activity is the proximal cause of the contradictory-audit failure mode this reference exists to prevent.