agentleFS
LazyIsEfficientLazyIsEfficient/agentic-os/.claude/skills/skill-library-review/SKILL.md

skill-library-review

Skill17 starsChanged 25 days agoMITView on GitHub

Use when reviewing or auditing a library of Claude Code skills, agents, slash commands, and workflows — frontmatter correctness, routing quality, tool allowlists, command arg-hints, workflow meta/phase coherence, cross-reference coherence, single-responsibility, file structure, and anti-pattern detection. Triggers on mentions of "review skills", "audit agents", "skill library", "agent definition review", "review this command", "review this workflow", "is this skill right", or when iterating on `.claude/skills/`, `.claude/agents/`, `.claude/commands/`, or `.claude/workflows/` directories. For code review of source code see code-review-and-quality.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Cite the file: Every finding references a specific file (and line if applicable).

    line 28
  2. Distinctive:

    One coherent role per agent, one coherent concern per skill: If a description has to use "or" to span two unrelated domains, it's two …

    line 33
  3. Distinctive:

    Cross-references resolve: Every "For X see Y" must point to a real file.

    line 34
  4. Very specific:

    Portable language only: No company names, project-specific paths, or apps/foo/...

    line 37
  5. Distinctive:

    No invented criticism: If a description is short but the role is genuinely narrow, "too short" is not a finding.

    line 38

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill Library Review

You are reviewing a library of Claude Code agent and skill definitions, plus slash commands (.claude/commands/*.md) and workflows (.claude/workflows/*.js) — markdown files with YAML frontmatter (and, for workflows, executable JS) that the loader uses to route and run work. The loader picks badly when descriptions are vague, single-responsibility is violated, or cross-references are stale; commands and workflows fail silently when their frontmatter promises something the body doesn't deliver. Your job is to catch those problems before users hit them.

You operate read-only when reviewing. Cite file:line for every concrete finding.

Universal Rules

  • Verdict first. Lead with pass / fix-before-merge / hold and a one-line reason. Detail follows.
  • Cite the file. Every finding references a specific file (and line if applicable). Vague advice is not actionable.
  • Quote the live line. Every finding must quote the exact text from the current file at the cited file:line. If the quoted text isn't in the file as written, the finding is invalid — discard it. Memory of "how skills like this usually read" is not evidence. Because a finding the author can't quote from the live file is a hallucination, and it sends maintainers chasing a defect that was never there.
  • Mark severity. Blocking, should-fix, or nit. Don't conflate.
  • Specificity for routing is non-negotiable. A description that says "use for anything code-related" is broken — it forces the loader to guess. Demand concrete triggers and discriminating cross-refs.
  • Tool allowlist must match declared role. A "read-only reviewer" with Edit in tools: is a contradiction; flag as blocking.
  • One coherent role per agent, one coherent concern per skill. If a description has to use "or" to span two unrelated domains, it's two definitions in a trench coat.
  • Cross-references resolve. Every "For X see Y" must point to a real file. Bidirectional refs preferred when the relationship is symmetric.
  • A shared keyword is not a collision by itself. First confirm the two skills genuinely contend for the same request — a shared trigger keyword or an overlapping file-glob. Two skills that don't compete aren't colliding just because neither names the other (a code-review skill and a test-strategy skill don't contend). If they do contend, read both skills' when_to_use/"not when": if each already deflects to the other, the overlap is resolved — not a finding. Report a collision only when the skills truly overlap and a reciprocal tiebreaker is missing on at least one side. Because deliberately shared keywords disambiguated by "not when" are the intended routing pattern, and two non-competing skills aren't a collision at all — flagging either refiles noise.
  • SKILL.md stays under ~100 lines. Long content goes in references/. Templates the agent fills out go in assets/.
  • Portable language only. No company names, project-specific paths, or apps/foo/... globs in SKILL.md body or descriptions.
  • No invented criticism. If a description is short but the role is genuinely narrow, "too short" is not a finding.

Review order

Most expensive to fix → least expensive. Stop at first blocking issue if a quick verdict was requested.

  1. Library shape — is this a skill, an agent, an ambient rule, a command, or a workflow? Are two definitions doing one job, or is one doing two? For commands and workflows, review the frontmatter against the body — see references/commands-and-workflows.md (command argument-hint/allowed-tools; sub-agent invocation uses Agent; workflow pure-literal meta, node --check, schema-guaranteed fields).
  2. Frontmatter correctness — name matches file/dir, description structure, tools field validity
  3. Description quality — routing specificity, trigger vocabulary, proactive markers; verify any keyword collision against both skills' "not when" before flagging (see references/description-and-routing.md)
  4. Tool allowlist coherence — matches the declared role
  5. Cross-reference coherence — resolve, bidirectional, no orphans
  6. Anti-patterns — the catch-all

Tier discipline

Tier definitions: review-tiers (.claude/rules/review-tiers.md) — stochastic judgment proposes, deterministic verification disposes.

  • Tier 0: everything scripts/validate.sh already checks (frontmatter presence, kebab-case name/dir match, dangling links and @-imports). Cite the validator; don't re-find its territory.
  • Tier 1 (may gate, evidence attached): findings whose quoted live line is the reproducible evidence — a tools: line contradicting a declared read-only role, a cross-reference whose target path does not exist. State the line and the failing check.
  • Tier 2 (advisory, never gates): routing specificity, description vagueness, single-responsibility judgments, keyword bloat. A fix-before-merge verdict riding only on Tier 2 findings is a proposal to the operator, not a gate — log these to findings-ledger; recurrence, not rhetoric, escalates them.

References

  • references/frontmatter-rules.md — required fields, format, validation, common errors
  • references/description-and-routing.md — writing descriptions for the loader, trigger vocabulary, proactive markers, cross-references
  • references/tool-allowlists.md — agent tool permissions matrix, role-to-allowlist map, why Bash is a soft-write vector
  • references/library-shape.md — skill vs agent vs ambient rule, consolidation and split heuristics, single-responsibility checks
  • references/anti-patterns.md — catch-all: name collisions, keyword bloat, frontmatter drift, dangling refs, orchestrator-only agents
  • references/commands-and-workflows.md — validation rules for slash commands (.claude/commands/) and workflows (.claude/workflows/): arg-hints, allowed-tools, meta/phase() coherence
  • assets/review-template.md — verdict-first review output format

Related skills

  • code-review-and-quality — applies the same review discipline to source code rather than agent definitions
  • adversarial-claims-reviewer — applies adversarial verification to formal/technical claims in documents rather than library definitions
  • library-investigator — the mechanical, evidence-only counterpart: probes files against RULESET and reports CONFORMS/VIOLATES counts with no quality verdict; this skill owns the judgment axis (routing, specificity, single-responsibility) it defers back
  • findings-ledger — where this skill's Tier 2 (unevidenced) findings get recorded and tallied for recurrence

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.