---
name: skill-audit
description: >
  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.
allowed-tools: Bash Read
metadata:
  category: factory
---

## Step 1 — Structural validation

Locate the `validate.sh` script from `skill-write`:

```bash
bash plugins/kyberforge/skills/skill-write/scripts/validate.sh <skill-dir>
```

If `validate.sh` is not found, note it and proceed — perform the checks it would cover manually.

List every FAIL from the structural check in the punch list before continuing.

## 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/`. Do not skip 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.md` present and accurately describes the skill and its files

### 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.