claude-skill-spec-audit

Skill Spec Audit

Check installed skills against the agentskills.io specification and local conventions for metadata completeness.

Arguments

• Skill names: tokens after the command -> filter to those skills only
• --fix: automatically add missing fields (prompts for values)
• Default: scan all non-symlinked skills in ~/.claude/skills/

Spec Requirements (agentskills.io)

Naming Conventions

Skill names follow the pattern: [scope]-[platform/org]-[group]-<name-with-layer-suffix>

Rules

1. Lowercase, kebab-case, no consecutive hyphens, 2-4 words, max 40 chars
2. Suffix encodes the layer (see "Layer Conventions" below)
3. Standardized action synonyms: audit (compliance), scan (broad analysis), search (lookup), triage (classify+act)

Scope prefix (required)

Derived from metadata.scope:

Platform prefix (when single-platform dependent)

Multi-platform or general skills stay unprefixed. If a skill touches 2+ platforms, no platform prefix — the scope prefix alone is enough.

Group prefix (when 2+ skills share a domain)

When creating a new skill, check for existing siblings. If a second skill appears in the same domain, retroactively add a shared prefix to both.

Layer Conventions

Every skill is exactly one of four layers, declared via metadata.layer. The suffix of the name must match the layer.

Reference skills must:

• End in -shared.
• Begin their description with: "Internal reference loaded by other <prefix>-* skills. Do not invoke directly."
• Not appear in user-facing trigger phrases.

See ~/.claude/skills/CONVENTIONS.md for full rationale.

Local Conventions (beyond spec)

These are project-specific conventions enforced on top of the spec:

Workflow

Phase 1: Discover Skills

1. Glob for ~/.claude/skills/*/SKILL.md
2. Also check .claude/skills/*/SKILL.md (project-level)
3. Skip symlinks — those point to .agents/skills/ and have their own conventions
4. If user specified skill names, filter to matching directories
5. Read each SKILL.md frontmatter

Phase 2: Validate Each Skill

For each SKILL.md, check:

Spec compliance:

1. name exists, matches directory name, is lowercase with hyphens only, no consecutive hyphens, 1-64 chars
2. description exists, is non-empty, 1-1024 chars
3. compatibility exists (warn if missing — not required by spec but expected locally)

Naming conventions:

4. Scope prefix matches metadata.scope: p- for personal, o- for organization, none for generic
5. Platform prefix present if skill depends on a single platform (gh-, git-, slack-, gws-)
6. No platform prefix if skill uses 2+ platforms
7. Action synonym is standardized: audit not review/check, scan not inspect
8. No single-word names (must have at least one hyphen)
9. Max 40 chars, 2-4 words
10. Abbreviations only from allowlist: pr, cli, oss, dep, mcp, gh, gws

Local conventions:

11. metadata.author is present and non-empty
12. metadata.scope is one of: generic, personal, organization
13. metadata.confirms exists if the skill body references any of these patterns:

• Slack: send_message, post message, post to Slack
• Git: git commit, git push, create commit, push to remote
• GitHub: merge, approve, create PR, create issue, create release, gh release
• Calendar: create event, insert event
• Files: save to, write to, create file
• Install: brew install, install

7. argument-hint exists if the skill body references arg parsing, ## Arguments, or accepts parameters

Phase 3: Report

Print a table:

## Skill Spec Audit

| Skill | name | naming | desc | compat | author | scope | confirms | arg-hint | Issues |
|-------|------|--------|------|--------|--------|-------|----------|----------|--------|
| gh-dep-pr-triage | ok | ok | ok | ok | ok | ok | ok | — | 0 |
| p-blog-writer | ok | ok | ok | ok | ok | ok | ok | ok | 0 |
| new-skill | ok | MISS:scope-prefix | ok | MISS | MISS | MISS | WARN | — | 4 |

Legend: ok = present and valid, MISS = missing, WARN = likely needed but missing, — = not applicable
Summary: N skills checked, M fully compliant, X issues found

Phase 4: Fix (if --fix or user asks)

For each issue, prompt the user for the value or infer it:

After fixing, use Edit to insert missing fields before the closing ---.

Re-run validation and show updated table.

Determining metadata.scope

Determining metadata.confirms

Only add confirms if the skill can perform irreversible or externally-visible operations. Read-only skills (scanning, searching, reporting) do NOT need confirms.

Common confirms patterns: