skill-quality-review
Skill Quality Review
Audit SKILL.md quality across a set of skills. Identifies the most-used skills, classifies them as self-developed vs builtin, then runs batch writing-for-agents checks and fixes.
The review framework blends Matt Pocock's writing-for-agents (context pointers, two loads, information hierarchy, completion criteria, leading words, pruning) with hermes-agent-skill-authoring peer-matched structure and cross-reference parity. See references/writing-for-agents-framework.md for the full lever set.
references/skill-review-methodology.md lives HERE in this skill — it covers per-skill grep-based review (3-sources-of-truth drift, pricing registry, guardrail asymmetry). This skill covers batch automated checks, the deep per-skill methodology, and usage-based prioritisation across all skills in a repo or local library. Authoring-time mechanical sweeps (TOC coverage, nesting, orphans) run via scripts/check_references.py in this skill — format-agnostic, works on any repo (this skill vendors it so plugin repos do not depend on a Hermes-side script). For Hermes in-repo skills, hermes-agent-skill-authoring/scripts/audit_references.py remains the canonical checker; see references/hermes-library-review.md. Deep methodology below.
Know the skill format first
Before running any checks, identify the skill format — the frontmatter fields, structural sections, and validation rules differ:
| Aspect | Hermes in-repo | Claude Code plugin |
|---|---|---|
| Required frontmatter | name, description, version, author, license, metadata.hermes.{tags, related_skills} |
name + description only |
| Description trigger convention | Starts with "Use when ..." | Often carries Triggers: "phrase1", "phrase2" inline |
| Structural sections | ## Overview → ## When to Use → ## Common Pitfalls → ## Verification Checklist |
## What this skill is for → ## Workflow → skill-specific sections |
| Validator source | tools/skill_manager_tool.py in hermes-agent repo |
.claude-plugin/plugin.json + tools/build_plugin.py in the plugin repo |
| License field | In frontmatter | In .claude-plugin/plugin.json, not per-skill |