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)

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]

Rules

Lowercase, kebab-case, no consecutive hyphens, 2-4 words, max 40 chars
Role-noun suffixes allowed (
```
-writer
```
,
```
-scheduler
```
,
```
-namer
```
)
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.

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

Workflow

Phase 1: Discover Skills

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

Phase 2: Validate Each Skill

For each SKILL.md, check:

Spec compliance:

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

Naming conventions:

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

Local conventions:

```
metadata.author
```
is present and non-empty

metadata.scope

is one of:

generic

personal

organization

```
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
```

```
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`

claude-skill-spec-audit

NPX Install

Tags

SKILL.md Content