| name | agent-skill-quality-audit |
| description | Audit a single agent skill (SKILL.md-style instruction file) for spec compliance and optimize it — without deleting the hard-won guards that skills accrete over time. Covers a frontmatter/body spec checklist, a self-contradiction and unsafe-command scan, cross-reference resolution, a five-step delete-then-optimize pass, and a guard-preservation diff that survives naive false positives. Trigger keywords: audit skill, skill quality, skill spec check, optimize skill, skill lint, agent skill review, SKILL.md audit, guard preservation, lesson preservation. |
| license | MIT |
| metadata | {"version":"1.0.0","author":"ngpestelos","hermes":{"tags":["Skills","Audit","Quality","Methodology"],"related_skills":["five-step-optimizer","skill-decomposition-methodology"]}} |
Agent Skill Quality Audit
Purpose: deep-audit ONE agent skill (a SKILL.md-style instruction file with YAML frontmatter) for spec compliance and optimize it, without silently deleting the dated guards and hard rules that mature skills accumulate. Optimization and preservation pull in opposite directions — this skill sequences them so neither wins by accident.
Scope: one skill at a time. For triaging many skills or fanning out, wrap this in a batch/parallel orchestrator; for splitting an over-long skill, hand off to skill-decomposition-methodology.
Phase 1: Spec Check
Read the skill body and any bundled references/. Check:
| Check | Criteria |
|---|
name | Lowercase alphanumeric + single hyphens, 1–64 chars, matches the directory name |
description | Present, ≤1024 chars, and includes trigger keywords so the host can match it |
| Frontmatter keys | Only spec-allowed keys at top level; framework-native extensions nest under a metadata block. Flag stray keys (e.g. permission fields a host ignores) for removal or migration. |
| Body size | ≤300 lines ideal (decompose above — Phase 6); treat ~500 as a hard ceiling |
| Body tokens | Roughly under 5000 (words × 1.3); prose that never changes execution is the first thing to cut |
Phase 2: Contradiction & Safety Scan
Correctness defects, not line savings — scan before optimizing:
- Self-contradiction: a path the how-to recommends that the skill's own Troubleshooting/Edge-cases documents as failing; a rule stated one way in the summary and the opposite in a step. Cross-read the sections against each other and surface both sides.
- Unsafe or banned commands: destructive operations (recursive deletes, history-rewriting or untracked-discarding VCS commands) or anything your environment's safety rules prohibit. Propose the safe replacement.
Behavioral changes (removing a documented option, swapping a command) get surfaced for confirmation; apply only spec and dedup fixes autonomously.
Phase 3: Cross-Reference Resolution
Every reference the skill makes must resolve, or it is dead weight that misleads a reader:
related_skills entries, links to sibling skills, references/* pointers, hardcoded paths, and helper-script references — each must resolve on disk OR by name. If your ecosystem resolves skills through a registry or symlinks (so a skill can live in another repo yet still resolve by name), check by name, not just the local directory.- Trigger references in the description (commands, other skills) must still exist.
Dangling references — dead related_skills, moved paths, renamed-away commands — are among the most common real defects and the cheapest to catch: a plain resolve-check finds them.
Phase 4: Five-Step Optimize
Run five-step-optimizer on the file. High-yield deletion targets specific to skills:
- Generic knowledge the agent already has; duplication of environment-wide instructions.
- Sections that only invert a rule already stated (a "don't" that mirrors an adjacent "do").
- Duplicate sibling sections (the same heading pasted twice from a copy-paste) — grep the headings to catch them.
- Highest yield — body↔reference duplication. When a skill ships a
references/ file, the body often re-pastes that content (worked examples, tables, templates). Collapse each to a one-line summary + pointer so the reference is the single source of truth. Verify the reference actually holds the detail before deleting it from the body.
Phase 5: Guard Preservation (do this before you commit)
Mature skills are accretions of hard-won guards — a rule usually encodes a past failure, and deleting it re-exposes that failure later, unattributed. A delete-biased optimizer (Phase 4) targets exactly these lines, so verify none were lost:
- Diff the optimized file against the pre-edit version and look for dropped markers: dated notes, origin/incident annotations, and hard rules (NEVER / ALWAYS / MANDATORY / MUST NOT). Each dropped marker must be restored, or explicitly retired with a stated reason in the change description.
- Beware false positives in any automated marker check. Naive detectors over-flag two ways: (a) word-match — a marker keyword (e.g. "incident") appearing in ordinary prose makes a non-guard line look like a guard, so deleting that prose trips the check; (b) prefix/key shift — editing the START of a real guard line (adding a path, rewording the lead) can make a line-keyed detector report the untouched guard as lost. When flagged, grep the guard's distinctive phrase in the new file; if the actual text survives, it's a false positive — record it as such rather than blindly restoring. A genuine loss is when the distinctive phrase is gone.
Phase 6: Decompose (if still over the ceiling)
If the body is still over ~300 lines after Phase 4, hand off to skill-decomposition-methodology — extract cohesive chunks into references/ with pointers rather than cutting content that earns its place.
Phase 7: Report
State what changed and why, the before/after size, any files created or removed, any behavioral change awaiting confirmation, and any guard-preservation false positives you recorded.
