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.