Skill Compliance Auditor

---
name: skill-compliance-auditor
description: Audit reusable plugin skills, project-local .codex skills, AGENTS.md, nested instructions, context cost, stale guidance, duplicated rules, routing gaps, and daily-vs-library placement. Use when maintaining this harness, validating generated local skills, or checking whether agents can actually follow the available instructions.
---

# Skill Compliance Auditor

## Purpose

Find whether agent instructions and skills are usable, discoverable, current, and placed at the right scope instead of bloating daily context.

## Inspect First

- plugin `skills/`, project `.codex/skills`, root and nested `AGENTS.md`
- README, docs indexes, validation scripts, generated local skills, and recent skill changes
- any existing skill compliance report

## Procedure

1. Inventory instruction surfaces.
   - Separate plugin skills, project-local skills, root instructions, nested instructions, and docs.
   - Treat plugin skills as reusable authoring workflows and project-local skills as thin repo-specific operating workflows.

2. Check compliance and signal.
   - Run `scripts/check_skill_compliance.py <repo-or-plugin> --json` when available.
   - Flag missing frontmatter, missing required sections, oversized local skills, stale file links, duplicated hard rules, weak routing links, and instruction content that belongs in docs.
   - Classify local skills as `daily`, `on_demand`, or `library` based on frequency and evidence.

3. Produce a report when requested.
   - Use `assets/templates/skill-compliance-report.md.tmpl`.
   - Prioritize fixes that reduce daily context, remove contradiction, or make a skill trigger more reliably.

4. Route fixes.
   - Use `$project-local-skill-generator` for repo-local skill generation.
   - Use `$agents-md-author` or `$nested-agents-md-author` for instruction map cleanup.
   - Use `$harness-diagnostics` when compliance issues are part of a broader maturity audit.

## Validation

- Run `scripts/check_skill_compliance.py <repo-or-plugin>`.
- Confirm every finding names a concrete file, skill, or missing route.
- Confirm recommendations preserve the plugin/project-local split.

## Completion Criteria

- Skill and instruction issues are grouped by severity and scope.
- Daily instructions are lean, local skills are backed by repo artifacts, and reusable harness logic remains in plugin skills.