/skill-auditor

Skill Auditor

Comprehensive audit of the skills library for quality and consistency.

Audit Modes

Routine mode follows .agents/memory/system/routine-standards.md. It is read-only: detect normalized duplicate bodies and prompt-level model, effort, schedule, cwd/workspace/worktree, and environment leakage. Report source identifiers and field names only; never print prompt bodies, environment values, or TOML values. Use --show-paths only when the caller explicitly wants local paths in the report.

Audit Categories

1. Duplicate Detection

Find skills that overlap and should be consolidated:

• Compare descriptions for semantic similarity
• Check for skills with near-identical when_to_use triggers
• Flag naming collisions (e.g., react-patterns vs react-refactor)

2. Spec Compliance

For each SKILL.md, check:

• Frontmatter follows Agent Skills spec (see .agents/memory/system/skill-standards.md)
• version/tags inside metadata: block, not top-level
• No forbidden fields (auto_activate, auto_trigger, risk)
• metadata.tags is a comma-separated string, not YAML list
• No harness-owned execution parameters in reusable content; apply .agents/memory/system/execution-boundary.md to skills, commands, and routine templates

3. Structural Issues

• Orphaned nested directories (skills/<name>/<name>/)
• Empty skill directories (no SKILL.md)
• Skills in README that no longer exist in filesystem
• Skills in filesystem that are missing from README
• Broken references to non-existent files in skill content

4. Content Quality

• Empty or placeholder descriptions
• Hardcoded project-specific paths (/workspace/, @genfeedai/)
• Escaped backtick fences (\```) instead of real fences
• Skills that reference scripts not bundled with the skill

5. README Sync

Compare the skills/ directory listing against the README's categorized skill lists (backticked names under the ## Skills (N) heading — the README has no per-skill link table):

# Get skills from filesystem
REPO_TMP="$(git rev-parse --show-toplevel)/.tmp"
mkdir -p "$REPO_TMP"
find skills -maxdepth 1 -mindepth 1 -type d | sed 's|skills/||' | sort > "$REPO_TMP/fs-skills.txt"

# Get skills from the README's categorized lists
sed -n '/^## Skills (/,/^## How Skills Adapt/p' README.md \
  | grep -oE '`[a-z0-9-]+`' | tr -d '`' | sort -u > "$REPO_TMP/readme-skills.txt"

# Diff
comm -23 "$REPO_TMP/fs-skills.txt" "$REPO_TMP/readme-skills.txt"  # in fs, not README
comm -13 "$REPO_TMP/fs-skills.txt" "$REPO_TMP/readme-skills.txt"  # in README, not fs

Also verify each category heading's (N) count matches the number of names in its list. A skill may appear in more than one category, so the per-category sum exceeding the total is expected.

Output Format

Report findings as a table:

For routine mode, report totals, leakage categories, anonymous source identifiers, duplicate-family groups, and observed app-owned field names. Do not include the matched text or configuration values.