audit-subagents

name	audit-subagents
description	Custom agent-configuration audit methodology preloaded by the subagent-auditor agent. Dispatch subagent-auditor to audit custom agent 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 instructions:agent-prompt-standards skill before proceeding. If that skill is unavailable, report the missing skill and continue with the closest available workflow.

Invoke the instructions: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 custom agent configuration file (`.codex/agents/*.toml` or `~/.codex/agents/*.toml`) against the create-subagents and `/agent-prompt-standards` conventions — APPROVED when no critical issue rejects it, or REJECTED 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 custom agent file under audit or any other file — this audit produces a verdict, never a fix or a commit - NEVER report a score; report contextual judgment instead

• MUST check for markdown headings (##, ###) inside developer_instructions 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 custom agent purpose and complexity

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

1. Both skills are already injected above. Read instructions:create-subagents plus its references/subagents.md and references/write-subagent-prompts.md files.
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 REJECTED 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 custom agent 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:

toml_configuration:

• name: Unique, clear purpose, matches the configured agent's role
• description: Includes BOTH what it does AND when to use it, specific trigger keywords
• developer_instructions: Present, substantive, and structured with role, workflow, constraints, and output expectations
• nickname_candidates: When present, a TOML array of concise display names that fit the configured agent's role and avoid misleading aliases

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 inside developer_instructions (##, ###) - 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 structure:

• Does prompt define expected output structure?
• Pass: clear deliverable-structure guidance under any semantically appropriate tag

model_selection:

• Is model choice appropriate for task complexity?
• Guidance: Simple/fast -> gpt-5.4-mini, complex/critical -> gpt-5.4, highest capability -> gpt-5.5

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 custom agent purpose and complexity:

Simple custom agents (single task, minimal tools):

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

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

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

Delegation custom agents (coordinate other subagents):

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

Always explain WHY something matters for this specific custom agent, 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: developer_instructions content is consumed by Codex as prompt text. Pure XML structure provides consistent parsing and keeps task boundaries explicit.

How to detect: Search developer_instructions 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 a structured verdict consumed by the composing verification workflow. The skill's entire output is the verdict payload. The composing workflow records findings, terminal state, and rendered projection through spx verification run.

The skill's overall is APPROVED iff the critical-issues row has no findings with severity REJECT; otherwise it is REJECTED. A missing or unreadable subagent file, or an audit that cannot complete, records a REJECT critical issue and returns REJECTED. Recommendations land as WARNING findings; strengths and quick fixes land as INFO findings.

{
  "schema_version": 1,
  "skill": "audit-subagents",
  "target": "<configured-agent-path>",
  "overall": "APPROVED | REJECTED",
  "rows": [
    {
      "name": "critical-issues",
      "status": "PASS | FAIL",
      "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 TOML configuration 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 — TOML configuration, role definition, workflow specification, constraints, tool access, XML structure, prompt craft, and the recommended areas (coverage-complete).
• The verdict states an overall APPROVED/REJECTED 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 custom agent 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 custom agent type and complexity
7. Examples: At least one concrete example given for major issues