audit-subagents

name	audit-subagents
description	Subagent-configuration audit methodology preloaded by the subagent-auditor agent. Dispatch subagent-auditor to audit subagent configuration files; the main conversation reaches this audit only through that agent.
argument-hint	<configured-agent-path>
arguments	configured_agent_path
allowed-tools	Read, Grep, Glob, Bash, Skill

Invoke the develop:agent-prompt-standards skill before proceeding. If that skill is unavailable, report the missing skill and continue with the closest available workflow.

Invoke the develop:create-subagents skill before proceeding. If that skill is unavailable, report the missing skill and continue with the closest available workflow.

<dispatch_gate>

This audit runs in the subagent-auditor agent's isolated context. When this skill loads in the main conversation rather than inside a dispatched audit agent, STOP — dispatch the subagent-auditor agent instead of running this audit here. The separate context keeps the verdict free of the bias the main conversation accumulates while doing the work under audit. An already-dispatched agent that preloaded this skill is in the right context and proceeds.

</dispatch_gate>

A verdict on one subagent configuration file (`.claude/agents/*.md` or `~/.claude/agents/*.md`) against the create-subagents and `/agent-prompt-standards` conventions — PASS when no critical issue rejects it, FAIL when one does. Findings group as critical issues (role definition, workflow specification, constraints, tool access, XML structure, and prompt craft), recommendations, strengths, and quick fixes, each naming the location, the convention at issue, and the consequence — contextual judgment, never a score. - NEVER modify the subagent file under audit or any other file — this audit produces a verdict, never a fix or a commit

• 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

• NEVER 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

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

1. Both skills are already injected above. Read the develop:create-subagents skill guidance, specifically its Subagent usage and configuration and Writing effective prompts reference topics.
2. The agent-prompt-standards skill is already injected above — covers voice, description style, constraint language, and anti-patterns.
3. If $configured_agent_path is empty, STOP with FAIL and a critical issue naming the missing required path argument.
4. Before penalizing any missing section, search entire file for equivalent content under different tag names.
5. Read the subagent configuration file at $configured_agent_path.
6. Evaluate against best practices from steps 1-4, focusing on functionality over formatting.

Use ACTUAL patterns from references, not memory. </audit_workflow>

<evaluation_areas> 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

Check against `/agent-prompt-standards` conventions:

• Voice: Uses imperative mood for instructions, "Claude" for failure modes/tendencies. Never "the agent", "the model", or "you"
• Description style: Directive pattern for description field. Matches user speech
• Constraint language: Strong modal verbs (MUST/NEVER/ALWAYS) in constraint blocks
• Anti-patterns: No banned phrases ("helpful assistant", "helps with", "please"). No structural anti-patterns (explaining Claude to Claude, motivational prose)

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

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

<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:

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

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.

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.

Generic tag names like ``, ``, ``.

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

<verdict_format> Emit the verdict as JSON conforming to the canonical audit-verdict schema consumed by the composing audit workflow. The skill's entire output is the JSON verdict. The composing audit workflow records and renders the verdict through the audit journal path.

The skill's overall is PASS iff the critical-issues row has no findings with severity REJECT; FAIL if any critical finding is REJECT; UNKNOWN if the subagent file cannot be read or the audit cannot complete. Recommendations land as WARNING findings; strengths and quick fixes land as INFO findings.

{
  "schema_version": 1,
  "skill": "audit-subagents",
  "target": "<configured-agent-path>",
  "overall": "PASS | FAIL | UNKNOWN",
  "rows": [
    {
      "name": "critical-issues",
      "status": "PASS | FAIL | UNKNOWN",
      "findings": [
        {
          "id": "f-001",
          "file": "<configured-agent-file>",
          "line": null,
          "rule": "<issue-category>",
          "severity": "REJECT",
          "message": "Current: <…>. Should be: <…>. Why it matters: <…>. Fix: <…>."
        }
      ]
    },
    { "name": "recommendations", "status": "PASS", "findings": [] },
    { "name": "strengths", "status": "PASS", "findings": [] },
    { "name": "quick-fixes", "status": "PASS", "findings": [] }
  ],
  "metadata": {
    "configured_agent_type": "simple | complex | delegation",
    "tool_access": "appropriate | over-permissioned | under-specified",
    "model_selection": "appropriate | reconsider"
  }
}

</verdict_format>

<failure_modes>

Failure 1: Flagged a missing tag name when the content was present under a different name. Claude penalized a subagent for lacking <workflow> when its procedure lived under <approach>. The audit checks for functionality, not exact tag spelling; a missing function is a finding, a renamed-but-present section is not. Search the whole file for equivalent content before flagging.

Failure 2: Scored the subagent instead of judging it. Claude assigned "role clarity 7/10" instead of naming the specific deficiency and its consequence. A score names no location, convention, or fix and the author cannot act on it. Emit findings, never scores.

Failure 3: Skipped an evaluation area and missed a whole class. Claude judged YAML frontmatter and role, formed a verdict, and stopped — leaving tool-access over-permissioning unexamined, so a class of issues passed unseen. The verdict is sound only when every evaluation area was judged; cover them all before issuing the verdict.

</failure_modes>

<success_criteria> The verdict is sound when:

• Every evaluation area was judged with none skipped — YAML frontmatter, role definition, workflow specification, constraints, tool access, XML structure, prompt craft, and the recommended areas (coverage-complete).
• The verdict states an overall PASS/FAIL with findings grouped critical-issues / recommendations / strengths / quick-fixes.
• Each finding is falsifiable: it names the location, the convention at issue, and the consequence — every critical issue names what breaks if unfixed, judged on functionality rather than exact tag spelling.
• The same subagent file yields the same verdict.

</success_criteria>

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