audit

Files (1)

• SKILL.md

SKILL.md (first lines)

# Skill Audit

Verify a skill follows best practices and the official specification.

## Instructions

Given a skill path (SKILL.md or skill directory), check each item below. Report findings as PASS/WARN/FAIL.

## Audit Checklist

### Structure
- [ ] Valid YAML frontmatter with `---` delimiters
- [ ] `name` field present (lowercase, hyphens, max 64 chars)
- [ ] `description` field present and specific (includes trigger keywords)
- [ ] SKILL.md under 500 lines
- [ ] References one level deep from SKILL.md (no nested chains)
- [ ] SKILL-compact.md exists if SKILL.md > 200 lines (run `gen-skill-compact.sh --check <dir>` to verify freshness)

### Invocation Control
- [ ] `disable-model-invocation: true` set if skill has side effects (deploy, commit, send)
- [ ] `user-invocable: false` set if skill is background knowledge only
- [ ] `allowed-tools` declared if specific tools needed
- [ ] `context: fork` used for isolation where appropriate

### Content Quality
- [ ] Uses standard markdown headings (NOT XML tags)
- [ ] Description includes both "what" and "when" triggers
- [ ] Examples are concrete, not abstract
- [ ] Has Quick Start or Instructions section
- [ ] No vague guidance ("use best judgment") — specific steps

### Anti-Patterns
- [ ] No XML tags in body
- [ ] No deep reference nesting
- [ ] No "punting" patterns (scripts handle errors, not "ask Claude to fix")
- [ ] No overly broad descriptions ("helps with things")

### Optional Intermesh Manifest

- [ ] If `intermesh.yaml` exists and `command -v intermesh >/dev/null 2>&1` succeeds, run `intermesh manifest validate <path>/intermesh.yaml`; report its diagnostics as normal audit findings.
- [ ] If Intermesh is unavailable, mark manifest validation `SKIP` rather than WARN/FAIL and continue the existing audit unchanged.
- [ ] The absence of `intermesh.yaml` is not an audit finding unless the user explicitly requires Intermesh routing metadata.

## Output Format

```
Skill Audit: {skill-name}
──────────────────────────────
Structure:          {N}/6 pass
Invocation Control: {N}/4 pass
Content Quality:    {N}/5 pass
Anti-Patterns:      {N}/4 pass
──────────────────────────────
Overall: {PASS | WARN (N issues) | FAIL (N issues)}

Issues:
- [WARN] Description could be more specific
- [FAIL] Missing disable-model-invocation for deploy workflow
```

From mistakeknot/interskill, MIT.

More from mistakeknot/interskill