66 lines
6 KiB
Markdown
66 lines
6 KiB
Markdown
# Skill Quality Checklist
|
|
|
|
Complete the applicable parts before finalizing, reviewing, or substantially revising an Agent Skill. Match evidence and validation to the requested outcome, and record evidence rather than checking boxes from intent alone. For a narrow review, inspect and report without requiring creation or execution evidence unless needed to verify a material risk. Do not manufacture artifacts solely to satisfy this checklist.
|
|
|
|
## Purpose and evidence
|
|
|
|
- The skill has one coherent job, explicit non-goals, and clear adjacent-skill boundaries.
|
|
- For creation, substantial revision, or behavioral evaluation, two or three realistic use cases record inputs, expected outputs, observable success criteria, and material constraints.
|
|
- For creation, substantial revision, or routing evaluation, two or three strong near misses identify the correct adjacent skill or direct workflow.
|
|
- An existing-skill change cites applicable evidence, is the smallest durable correction, and does not encode a one-off preference. Claims of behavioral improvement compare the old and revised versions when feasible. Reusability uncertainty was resolved with the user.
|
|
- Current tool names, command flags, schemas, paths, runtime assumptions, and examples were checked rather than copied from stale memory.
|
|
|
|
## Frontmatter and routing
|
|
|
|
- `name` is lowercase kebab-case, at most 64 characters, and exactly matches the directory.
|
|
- `description` is under 1024 characters and uses: third-person capability + literal `Use this skill when...` + material `Do not use when/for...`.
|
|
- Routing focuses on user intent/outcomes, includes realistic phrasing and useful co-activation, and keeps all activation guidance out of the body.
|
|
- No unresolved starter sentinel, sample name, bare ellipsis, bracket instruction, or other placeholder remains.
|
|
- `compatibility` names material runtime, CLI, credential, platform, or capability assumptions when applicable.
|
|
|
|
## Main body
|
|
|
|
- Critical constraints, mandatory resource loads, fragile sequencing, validation, and safety rules appear early.
|
|
- The workflow is concrete enough to execute without guessing; defaults replace unnecessary menus.
|
|
- Prescriptiveness matches risk, and failure/cleanup/recovery behavior is explicit where material.
|
|
- Generic explanations, duplicated policy, transcript history, redundant examples, and unrelated guidance are removed.
|
|
- The main file matches nearby catalog density and is normally under roughly 150 lines; longer files retain only execution-critical material and move conditional detail into resources.
|
|
- The body favors short headings, compact bullets, numbered procedures, and small tables. Prose is retained only where it improves clarity.
|
|
- Bullets express one instruction or tightly coupled behavior; paragraph-length bullets, repeated rationale, and introductory filler are absent.
|
|
- Cross-skill references use skill names, not relative paths to another skill's `SKILL.md`.
|
|
|
|
## Resources and progressive disclosure
|
|
|
|
- Every referenced file exists at the exact relative path, is one level deep, and has a clear content summary plus read/use/run condition.
|
|
- Mandatory resources are named early and repeated at the point of use with “Before doing X, read/use...” force.
|
|
- No vague “see references”, “as needed”, nonexistent fake link, empty resource directory, or unreferenced resource remains.
|
|
- References over roughly 100 lines have a short table of contents.
|
|
- Assets are reusable output skeletons rather than duplicated instructions; unused sections and all template sentinels were removed.
|
|
|
|
## Scripts and safety
|
|
|
|
- Every script is justified by repeated/fragile deterministic work, not a simple pinned one-off command.
|
|
- Scripts follow the target repository's established language, runtime, dependency, packaging, and test conventions; introducing a runtime solely for a helper script is justified only when existing tooling is insufficient.
|
|
- Command-line scripts are non-interactive by default, bound output, return meaningful exit statuses, provide `--help` or the ecosystem-equivalent, and document prerequisites, working directory, inputs, outputs, and side effects.
|
|
- Primary or machine-readable output goes to stdout and diagnostics to stderr where the environment supports that convention.
|
|
- Stateful/destructive scripts are idempotent, default to a dry run, or require an explicit opt-in; confirmation is added where appropriate.
|
|
- No secrets, tokens, sessions, `.env` contents, generated credentials, unsafe third-party code, or accidental machine-only paths are included.
|
|
|
|
## Evaluation
|
|
|
|
Apply this section when evaluating behavior, finalizing a substantial skill, or claiming improvement.
|
|
|
|
- Three to five realistic should-trigger prompts route from the description alone; broadly distributed/high-risk skills use additional cases only when warranted.
|
|
- Two to three near-miss prompts do not trigger incorrectly and retain useful co-activation where intended.
|
|
- At least one representative real-use task ran with realistic input; its actual output meets the recorded success criteria.
|
|
- A fresh safely available subagent performed execution/review when useful, or the direct fallback and independence limitation are recorded.
|
|
- Material evidence-backed gaps received one concise revision and affected routing/output checks were rerun; no benchmark framework was added without need.
|
|
|
|
## Validation
|
|
|
|
Run applicable repository checks with the repository's documented commands and established runtime, and retain exact results.
|
|
|
|
- Run an available Agent Skills specification validator when the repository provides or permits one; otherwise check specification compliance manually and report the unavailable automated gate.
|
|
- Metadata, names, literal routing, description length, placeholders, and resource links pass mechanically where repository validators exist; unavailable gates are checked manually and reported.
|
|
- Every added/changed command-line script's `--help` or ecosystem-equivalent, focused repository-native tests, and one representative safe execution pass.
|
|
- Final diff/status inspection shows only intended files, no stale generated artifacts, and no owner work lost.
|