auditing-subagents

<objective> Evaluate subagent configuration files against best practices for role definition, prompt quality, tool selection, model appropriateness, and effectiveness. Provide actionable findings with contextual judgment, not arbitrary scores.

This ensures subagents follow proper structure, configuration, pure XML formatting, and implementation patterns. </objective>

<quick_start>

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

</quick_start>

<constraints> - MUST check for markdown headings (##, ###) in subagent body and flag as critical - MUST verify all XML tags are properly closed - MUST distinguish between functional deficiencies and style preferences - NEVER flag missing tag names if the content/function is present under a different name (e.g., `<critical_workflow>` vs `<workflow>`) - ALWAYS verify information isn't present under a different tag name or format before flagging - DO NOT flag formatting preferences that don't impact effectiveness - MUST flag missing functionality, not missing exact tag names - ONLY flag issues that reduce actual effectiveness - ALWAYS apply contextual judgment based on subagent purpose and complexity </constraints>

<critical_workflow> MANDATORY: Read best practices FIRST, before auditing:

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. </critical_workflow>

<evaluation_areas> <area name="critical" priority="must-fix"> These issues significantly hurt effectiveness - flag as critical:

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

</area> <area name="recommended" priority="should-fix"> These improve quality - flag as recommendations:

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

</area> <area name="optional" priority="nice-to-have"> Note these as potential enhancements - don't flag if missing:

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

</area> </evaluation_areas>

<contextual_judgment> Apply judgment based on subagent purpose and complexity:

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. </contextual_judgment>

<anti_patterns> Flag these structural violations:

<pattern name="markdown_headings_in_body" severity="critical"> Using markdown headings (##, ###) for structure instead of XML tags.

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>) </pattern>

<pattern name="unclosed_xml_tags" severity="critical"> XML tags not properly closed or mismatched nesting.

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. </pattern>

<pattern name="hybrid_xml_markdown" severity="critical"> Mixing XML tags with markdown headings inconsistently.

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. </pattern>

<pattern name="non_semantic_tags" severity="recommendation"> Generic tag names like `<section1>`, `<part2>`, `<content>`.

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>). </pattern> </anti_patterns>

<output_format> Audit reports use severity-based findings, not scores. Generate output using this markdown template:

## 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]

</output_format>

<validation> Before completing the audit, verify:

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

</validation>

<final_step> After presenting findings, offer:

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

</final_step>

<success_criteria> A complete subagent audit includes:

• 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

</success_criteria>