Defame1297
3a85632df0
- Move validate.sh ownership to skill-audit/scripts/ — it is the canonical structural validator; skill-write now delegates Step 5 to /skill-audit - Add skill-write/references/scripts.md and deployment-modes.md for progressive disclosure of package runner patterns and plugin cache isolation rules - Fix skill-audit Step 1 cross-skill path reference (was repo-absolute, now skill-relative); add manual fallback for sandboxed/Bash-denied contexts - Scope Step 2 "read every file" to exclude binaries and unreferenced files - Fix new-skill.sh next-steps output to reference /skill-audit instead of the removed validate.sh - Remove stale Dependencies section from skill-audit README; flip dependency arrow — skill-write depends on skill-audit, not vice versa Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
4.8 KiB
4.8 KiB
name, description, allowed-tools, metadata
| name | description | allowed-tools | metadata | ||
|---|---|---|---|---|---|
| skill-audit | Audit a skill directory against the agentskills.io specification — structural checks plus qualitative review of description quality, body discipline, formatting, file structure, and internal consistency. Produces a PASS/FAIL/SUGGESTION punch list with a specific fix proposal for every FAIL. Use when the user wants to review a skill they wrote, says "audit this skill", "check if my skill follows best practices", "review my SKILL.md", or wants to know if a skill is ready to ship — even if they don't use the word "audit". Do not use to run evals, fix application code bugs, or perform general code review unrelated to skill quality. | Bash Read |
|
Step 1 — Structural validation
bash scripts/validate.sh <skill-dir>
List every FAIL from the structural check in the punch list before continuing. If the script cannot execute (python3 unavailable, Bash denied, or permission error), perform structural checks manually: name format, name matches directory, description length ≤1024 chars, SKILL.md ≤500 lines, no unfilled FILL IN: placeholders, scripts executable and free of interactive prompts.
Step 2 — Read all skill files
Read every file in the skill directory: SKILL.md, README.md (if present), all files in scripts/, references/, and assets/. Skip binary files and files not directly referenced from SKILL.md. Do not skip text files — internal consistency checks require the full picture.
Step 3 — Qualitative audit
Work through each dimension. Cite file and line number for every finding.
Description
- Imperative phrasing: does it use "Use when..." not "This skill..."?
- Specificity: are capabilities stated precisely ("parses OpenAPI specs") or vaguely ("helps with APIs")?
- Indirect triggers: does it cover cases where the user doesn't name the domain directly?
- Near-miss exclusions: are "Do not use when..." clauses present if a near-miss skill could steal activations?
- Length: under 1024 characters?
Body discipline
For each sentence in the body, apply: "Would the agent get this wrong without this sentence?" Flag any that answer "no" as padding.
- Defaults not menus: every decision point gives one default + one escape hatch, not a list of options
- Why rationale: include/exclude rules explain why, not just what
- Control calibration: prescriptive for fragile or critical sequences; flexible where multiple approaches are valid
Patterns
Check each pattern is appropriate and correctly formed:
- Gotchas: placed near the top; each entry is a specific fact that defies a reasonable assumption — not a general tip
- Prescriptive sequence: inner code fences escaped as
\``` when nested inside a markdown block - Checklists: used for multi-step workflows, not single steps
- Conditional references: specific trigger stated ("If X, read
references/file.md") — not a generic "see references/" - Output templates: present when the agent must produce a specific format; absent otherwise
File structure
- Only spec-defined directories present:
scripts/,references/,assets/ - No non-spec files (e.g. META.md, extra config files)
- Optional directories contain real content — not just unfilled placeholder READMEs
README.mdpresent and accurately describes the skill and its files- No cross-plugin path references — paths using
../,../../, or absolute repo paths (e.g.plugins/kyberforge/skills/...) break when the plugin is installed to a cache; flag any found
Formatting
- Heading levels consistent: H2 for main sections, H3 for subsections
- Code blocks fenced with a language tag where applicable (
bash,markdown,python) - Consistent whitespace: blank line between sections, consistent list indentation
- No broken relative paths in file references
Scripts
- No interactive TTY prompts (
read,input(),readline) --helpexposed with concise usage- Data to stdout, diagnostics to stderr
- Idempotent ("create if not exists")
- Meaningful exit codes documented in
--help --dry-runpresent for destructive operations
Internal consistency
- SKILL.md steps match what scripts actually do
README.mdfile table lists every file that exists — no missing entries, no stale entries- Placeholder READMEs in
scripts/,references/,assets/consistent with what SKILL.md says about each directory
Step 4 — Report
Output a punch list grouped by dimension:
PASS/FAIL/SUGGESTION <finding> — <file>:<line>
Follow with a priority table:
| Priority | Severity | Finding | File:Line |
|---|
Then for each FAIL, a fix proposal:
FAIL: <finding>
Fix: <exact change — quote before/after where applicable>
Do not apply fixes. Report and propose only.