Auditing Subagents

This ensures subagents follow proper structure, configuration, pure XML formatting, and implementation patterns.

1. Read best practices from the creating-subagents skill and its reference files
2. Read the subagent configuration file at $ARGUMENTS
3. Evaluate against all areas: YAML, role, workflow, constraints, tools, XML structure
4. Report findings using the severity-based output format

1. Locate the creating-subagents skill and its references:
   • Use Glob: .claude/plugins/cache/**/creating-subagents/SKILL.md
   • Then read its references/subagents.md, references/writing-subagent-prompts.md
2. Before penalizing any missing section, search entire file for equivalent content under different tag names
3. Read the subagent configuration file at $ARGUMENTS
4. Evaluate against best practices from steps 1-2, focusing on functionality over formatting

Use ACTUAL patterns from references, not memory.

yaml_frontmatter:

• name: Lowercase-with-hyphens, unique, clear purpose
• description: Includes BOTH what it does AND when to use it, specific trigger keywords

role_definition:

• Does <role> section clearly define specialized expertise?
• Anti-pattern: Generic helper descriptions ("helpful assistant", "helps with code")
• Pass: Role specifies domain, expertise level, and specialization

workflow_specification:

• Does prompt include workflow steps (under any tag like <workflow>, <approach>, <critical_workflow>, etc.)?
• Anti-pattern: Vague instructions without clear procedure
• Pass: Step-by-step workflow present and sequenced logically

constraints_definition:

• Does prompt include constraints section with clear boundaries?
• Anti-pattern: No constraints specified, allowing unsafe or out-of-scope actions
• Pass: At least 3 constraints using strong modal verbs (MUST, NEVER, ALWAYS)

tool_access:

• Are tools limited to minimum necessary for task?
• Anti-pattern: All tools inherited without justification or over-permissioned access
• Pass: Either justified "all tools" inheritance or explicit minimal list

xml_structure:

• No markdown headings in body (##, ###) - use pure XML tags
• All XML tags properly opened and closed
• No hybrid XML/markdown structure
• Note: Markdown formatting WITHIN content (bold, italic, lists, code blocks) is acceptable

focus_areas:

• Does prompt include focus areas or equivalent specificity?
• Pass: 3-6 specific focus areas listed somewhere in the prompt

output_format:

• Does prompt define expected output structure?
• Pass: <output_format> section with clear structure

model_selection:

• Is model choice appropriate for task complexity?
• Guidance: Simple/fast → Haiku, Complex/critical → Sonnet, Highest capability → Opus

success_criteria:

• Does prompt define what success looks like?
• Pass: Clear definition of successful task completion

error_handling:

• Does prompt address failure scenarios?
• Pass: Instructions for handling tool failures, missing data, unexpected inputs

examples:

• Does prompt include concrete examples where helpful?
• Pass: At least one illustrative example for complex behaviors

context_management: For long-running agents, context/memory strategy extended_thinking: For complex reasoning tasks, thinking approach guidance prompt_caching: For frequently invoked agents, cache-friendly structure testing_strategy: Test cases, validation criteria, edge cases observability: Logging/tracing guidance evaluation_metrics: Measurable success metrics

Simple subagents (single task, minimal tools):

• Focus areas may be implicit in role definition
• Minimal examples acceptable
• Light error handling sufficient

Complex subagents (multi-step, external systems, security concerns):

• Missing constraints is a real issue
• Comprehensive output format expected
• Thorough error handling required

Delegation subagents (coordinate other subagents):

• Context management becomes important
• Success criteria should measure orchestration success

Always explain WHY something matters for this specific subagent, not just that it violates a rule.

Why this matters: Subagent.md files are consumed only by Claude, never read by humans. Pure XML structure provides ~25% better token efficiency and consistent parsing.

How to detect: Search file for ## or ### symbols outside code blocks/examples.

Fix: Convert to semantic XML tags (e.g., ## Workflow → <workflow>)

Why this matters: Breaks parsing, creates ambiguous boundaries, harder for Claude to parse structure.

How to detect: Count opening/closing tags, verify each <tag> has </tag>.

Fix: Add missing closing tags, fix nesting order.

Why this matters: Inconsistent structure makes parsing unpredictable, reduces token efficiency benefits.

How to detect: File has both XML tags (<role>) and markdown headings (## Workflow).

Fix: Convert all structural headings to pure XML.

Why this matters: Tags should convey meaning, not just structure. Semantic tags improve readability and parsing.

How to detect: Tags with generic names instead of purpose-based names.

Fix: Use semantic tags (<workflow>, <constraints>, <validation>).

## Audit Results: [subagent-name]

### Assessment

[1-2 sentence overall assessment: Is this subagent fit for purpose? What's the main takeaway?]

### Critical Issues

Issues that hurt effectiveness or violate required patterns:

1. **[Issue category]** (file:line)
   - Current: [What exists now]
   - Should be: [What it should be]
   - Why it matters: [Specific impact on this subagent's effectiveness]
   - Fix: [Specific action to take]

2. ...

(If none: "No critical issues found.")

### Recommendations

Improvements that would make this subagent better:

1. **[Issue category]** (file:line)
   - Current: [What exists now]
   - Recommendation: [What to change]
   - Benefit: [How this improves the subagent]

2. ...

(If none: "No recommendations - subagent follows best practices well.")

### Strengths

What's working well (keep these):

- [Specific strength with location]
- ...

### Quick Fixes

Minor issues easily resolved:

1. [Issue] at file:line → [One-line fix]
2. ...

### Context

- Subagent type: [simple/complex/delegation/etc.]
- Tool access: [appropriate/over-permissioned/under-specified]
- Model selection: [appropriate/reconsider - with reason if latter]
- Estimated effort to address issues: [low/medium/high]

1. Completeness: All evaluation areas assessed
2. Precision: Every issue has file:line reference where applicable
3. Accuracy: Line numbers verified against actual file content
4. Actionability: Recommendations are specific and implementable
5. Fairness: Verified content isn't present under different tag names before flagging
6. Context: Applied appropriate judgment for subagent type and complexity
7. Examples: At least one concrete example given for major issues

1. Implement all fixes automatically
2. Show detailed examples for specific issues
3. Focus on critical issues only
4. Other

• Assessment summary (1-2 sentences on fitness for purpose)
• Critical issues identified with file:line references
• Recommendations listed with specific benefits
• Strengths documented (what's working well)
• Quick fixes enumerated
• Context assessment (subagent type, tool access, model selection)
• Estimated effort to fix
• Post-audit options offered to user
• Fair evaluation that distinguishes functional deficiencies from style preferences