Skill review

Trust the workflow because it earned trust.

Review skills before asking them to steer an agent. The first question is not “does this sound clever?” It is “does this skill make the right behavior more likely, within a clear scope, with evidence I can inspect?”

Review rubric

Score each dimension 0–2: 0 missing or harmful, 1 partial, 2 clear and demonstrated. A high score is not a substitute for a realistic test.

Dimension	Look for	Red flag
Trigger	Precise capability, trigger words, and a meaningful “do not use for” boundary.	Catch-all description that attracts unrelated tasks.
Purpose	Observable outcome and the decisions the skill improves.	Generic advice that any capable agent already knows.
Scope	Named files, systems, permissions, ownership, and side-effect limits.	Implied permission to install, publish, delete, or contact people.
Inputs and outputs	What the skill needs, what it produces, and how the result is handed off.	Workflow starts without a usable starting state.
Workflow quality	Imperative, focused instructions with room for judgment where risk allows.	Huge fixed sequences, repeated policy, or brittle over-specification.
Progressive disclosure	Core routing in `SKILL.md`; optional detail in relevant references.	Every mode, example, and manual is loaded up front.
Verification	Checks, invariants, counterexamples, stopping rules, and honest reporting.	“Looks good” or one happy-path screenshot is the completion gate.
Security	Untrusted input, secrets, authorization, privacy, and retry behavior are handled.	External text can redirect the workflow or secrets appear in examples.
Maintainability	References resolve, scripts are deterministic when needed, and facts have an owner.	Dangling links, stale versions, unexplained dependencies.
Trigger behavior	Positive examples activate it; near-misses do not.	It activates for everything or never activates implicitly.

Review process

01Read metadata first. Check lowercase naming, required name and description, and whether the description discriminates the skill from neighbors.

02Read the full entrypoint. Identify inputs, outputs, side effects, dependencies, stopping conditions, and claims that need proof.

03Follow only relevant references. Inspect scripts, references, assets, and metadata where the main workflow routes you to them.

04Run structural validation. For local skills, use the bundled quick validator when available; remember that it checks structure, not decision quality.

05Forward-test independently. Give the skill a realistic request and minimum raw context without revealing the intended answer. Check the actual artifact and side effects.

06Classify. Keep, revise, isolate, or reject. Record why, what was tested, and what remains uncertain.

Reviewed here

Meta-skills with the clearest contracts

skill-creator emphasizes focused jobs, progressive disclosure, real triggers, user intent, and independent forward-testing. review-agent is read-only and defect-first. The prior agent-harness-review adds benchmark cases, ownership separation, and before/after evidence.

Use with care

Large or environment-specific skills

UI, artifact, deployment, and browser skills can be excellent while still requiring their exact environment, dependencies, permissions, and rendering checks. A valid file is not the same as a valid result.

Quality threshold

Do not call a skill “good” because it has a complete frontmatter block. Call it ready when its routing is discriminating, its instructions preserve scope, its resources are discoverable, and a realistic test shows the intended behavior without unsafe side effects.