Defame1297
95ba57d0d5
- Reorder skill-audit description to lead with 'Use when...' trigger (P3) - Add concrete example to 'control calibration' body discipline check (P4) - Add bats test files to README file tables for both skills - Fix REPO_ROOT and SCRIPT paths in bats files after tests/ subdirectory removed - Add three lessons: plugin cache isolation, spec-grounded rubrics, test file placement Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
114 lines
5.2 KiB
Markdown
114 lines
5.2 KiB
Markdown
---
|
|
name: skill-audit
|
|
description: >
|
|
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".
|
|
Audits 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. Do not use to run evals, fix
|
|
application code bugs, or perform general code review unrelated to skill quality.
|
|
allowed-tools: Bash Read
|
|
metadata:
|
|
category: factory
|
|
---
|
|
|
|
## Step 1 — Structural validation
|
|
|
|
```bash
|
|
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?
|
|
|
|
If a description finding is borderline or the distinction between PASS and FAIL is unclear, read `references/description-quality.md`.
|
|
|
|
### 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 (e.g. a script invocation where flag order or exact arguments must not change); flexible where multiple approaches are valid
|
|
|
|
If uncertain whether a sentence is padding or whether a control decision is correctly calibrated, read `references/body-discipline.md`.
|
|
|
|
### 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.md` present 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`)
|
|
- `--help` exposed with concise usage
|
|
- Data to stdout, diagnostics to stderr
|
|
- Idempotent ("create if not exists")
|
|
- Meaningful exit codes documented in `--help`
|
|
- `--dry-run` present for destructive operations
|
|
|
|
### Internal consistency
|
|
|
|
- SKILL.md steps match what scripts actually do
|
|
- `README.md` file 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.
|