claude-skill-spec-audit · diff
git:20260421.19f33a5 to git:20260604.c9bb57f
37 added, 14 removed. Audit A to A.
---
name: claude-skill-spec-audit
license: MIT
description: >
- Audit skill SKILL.md files for compliance with the agentskills.io specification.
- Checks frontmatter fields (name, description, compatibility, metadata, argument-hint)
- and metadata sub-fields (author, scope, confirms). Use when adding new skills,
- reviewing skill quality, or ensuring all skills follow the spec.
- Triggers: "audit skills", "check skill spec", "skill compliance", "are my skills
- up to spec", "/claude-skill-spec-audit".
+ Audit skill SKILL.md files for compliance with the agentskills.io specification
+ and house conventions. Checks frontmatter fields (name, description,
+ compatibility, metadata, argument-hint), metadata sub-fields (author, scope,
+ layer, confirms), and layer/suffix consistency. Use when adding new skills,
+ reviewing skill quality, or ensuring all skills follow the spec. Triggers:
+ "audit skills", "check skill spec", "skill compliance", "are my skills up
+ to spec", "/claude-skill-spec-audit".
argument-hint: "[skill-name ...] [--fix]"
compatibility: Designed for Claude Code
metadata:
author: jackchuka
scope: generic
+ layer: workflow
confirms:
- add missing frontmatter fields
---
# Skill Spec Audit
Check installed skills against the [agentskills.io specification](https://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)
| Field | Required | Notes |
| --------------- | -------- | -------------------------------------------------------------- |
| `name` | Yes | 1-64 chars, lowercase, hyphens only, must match directory name |
| `description` | Yes | 1-1024 chars, non-empty |
| `compatibility` | No | Max 500 chars, environment requirements |
| `metadata` | No | Arbitrary key-value map |
| `allowed-tools` | No | Space-delimited tool list (experimental) |
## Naming Conventions
- Skill names follow the pattern: `[scope]-[platform/org]-[group]-[name]`
+ 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. Role-noun suffixes allowed (`-writer`, `-scheduler`, `-namer`)
+ 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`:
| Scope | Prefix | Example |
| -------------- | ------ | -------------------------------------- |
| `personal` | `p-` | `p-slack-triage`, `p-daily-standup` |
| `organization` | `o-` | `o-org-release-digest` |
| `generic` | (none) | `skill-spec-audit`, `gh-dep-pr-triage` |
### Platform prefix (when single-platform dependent)
| Platform | Prefix | When to use |
| ---------------- | -------- | ------------------------------------- |
| GitHub | `gh-` | Skill requires `gh` CLI or GitHub API |
| Git | `git-` | Skill requires git but not GitHub |
| Slack | `slack-` | Skill requires Slack MCP server |
| Google Workspace | `gws-` | Skill requires `gws` CLI |
**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)
| Group | Skills in group |
| -------- | -------------------------------------------------------------- |
| `daily-` | standup, report, reflection |
| `skill-` | dry-run, prereq-audit, spec-audit |
| `blog-` | writer, post-mining |
| `oss-` | release, release-prep |
| `org-` | release-digest, incident-investigation, sync-skills-to-plugins |
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.
+
+ | Layer | `metadata.layer` | Suffix family | Example |
+ | --- | --- | --- | --- |
+ | Primitive | `primitive` | verb: `-read`, `-list`, `-fetch`, `-search`, `-post`, `-insert`, `-append`, `-query`, `-get`, `-scan` | `gws-sheets-read` |
+ | Renderer | `renderer` | format noun (`-slides`, `-docs`, `-pdf`, `-card`, `-message`) or agent noun (`-writer`, `-explainer`, `-namer`, `-generator`) | `gws-slides`, `visual-explainer` |
+ | Workflow | `workflow` | outcome noun: `-digest`, `-deck`, `-report`, `-triage`, `-audit`, `-standup`, `-prep`, `-recap`, `-investigation` | `o-tailor-allhands-deck` |
+ | Reference | `reference` | `-shared` | `o-tailor-shared` |
+
+ **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`](../CONVENTIONS.md) for full rationale.
+
## Local Conventions (beyond spec)
These are project-specific conventions enforced on top of the spec:
- | Field | Expected | Values |
- | ------------------- | ------------------------- | ---------------------------------------------- |
- | `argument-hint` | If skill accepts args | Short usage hint string |
- | `metadata.author` | Always | Must be present (non-empty) |
- | `metadata.scope` | Always | `generic`, `personal`, or `organization` |
- | `metadata.confirms` | If skill has side effects | List of operations requiring user confirmation |
+ | Field | Expected | Values |
+ | ------------------- | ------------------------- | ------------------------------------------------------------ |
+ | `argument-hint` | If skill accepts args | Short usage hint string |
+ | `metadata.author` | Always | Must be present (non-empty) |
+ | `metadata.scope` | Always | `generic`, `personal`, or `organization` |
+ | `metadata.layer` | Always | `primitive`, `renderer`, `workflow`, or `reference` |
+ | `metadata.confirms` | If skill has side effects | List of operations requiring user confirmation |
## 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:
| Field | Inference strategy |
| ------------------- | --------------------------------------------------------------------- |
| `compatibility` | Scan for CLI tools, MCP servers in body -> suggest "Requires X, Y" |
| `metadata.author` | Infer from existing skills or ask user |
| `metadata.scope` | Ask user: generic, personal, or organization? |
| `metadata.confirms` | Extract side-effect patterns from body, present list for confirmation |
| `argument-hint` | Extract from `## Arguments` section if present, otherwise ask |
After fixing, use Edit to insert missing fields before the closing `---`.
Re-run validation and show updated table.
## Determining `metadata.scope`
| Scope | Criteria |
| -------------- | ----------------------------------------------------------------- |
| `generic` | Works for anyone, no personal/org-specific data |
| `personal` | References your specific accounts, channels, search terms, voice |
| `organization` | References company repos, internal tools, team-specific workflows |
## 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:
| Operation | confirms entry |
| --------------------- | ------------------------ |
| Post Slack message | `send Slack messages` |
| Merge PR | `merge PRs` |
| Approve PR | `approve PRs` |
| Create GitHub issue | `create GitHub issues` |
| Create GitHub release | `create GitHub releases` |
| Create calendar event | `create calendar event` |
| Git commit | `create git commit` |
| Git push | `push to remote` |
| Write files | `save to filesystem` |
| Install tools | `install missing tools` |
| Create PR | `create PR` |
| Modify settings | `modify settings files` |