Back to Details

claude-skill-spec-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Spec Audit

Skill规范审核

Check installed skills against the agentskills.io specification and local conventions for metadata completeness.
检查已安装的Skill是否符合agentskills.io规范以及元数据完整性的本地约定。

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/
  • Skill名称：命令后的令牌 -> 仅筛选这些Skill
  • --fix：自动添加缺失字段（提示输入值）
  • 默认行为：扫描
    ~/.claude/skills/
    中所有非符号链接的Skill

Spec Requirements (agentskills.io)

规范要求（agentskills.io）

FieldRequiredNotes
name
Yes1-64 chars, lowercase, hyphens only, must match directory name
description
Yes1-1024 chars, non-empty
compatibility
NoMax 500 chars, environment requirements
metadata
NoArbitrary key-value map
allowed-tools
NoSpace-delimited tool list (experimental)
字段是否必填说明
name
是1-64字符，小写，仅含连字符，必须与目录名匹配
description
是1-1024字符，非空
compatibility
否最多500字符，环境要求
metadata
否任意键值对映射
allowed-tools
否空格分隔的工具列表（实验性）

Naming Conventions

命名约定

Skill names follow the pattern: 
[scope]-[platform/org]-[group]-[name]
Skill名称遵循以下格式：
[scope]-[platform/org]-[group]-[name]

Rules

规则

  1. Lowercase, kebab-case, no consecutive hyphens, 2-4 words, max 40 chars
  2. Role-noun suffixes allowed (
    -writer
    , 
    -scheduler
    , 
    -namer
    )
  3. Standardized action synonyms: 
    audit
    (compliance), 
    scan
    (broad analysis), 
    search
    (lookup), 
    triage
    (classify+act)
  1. 小写、短横线命名法，无连续连字符，2-4个词，最多40字符
  2. 允许使用角色名词后缀（
    -writer
    、
    -scheduler
    、
    -namer
    ）
  3. 标准化动作同义词：
    audit
    （合规性检查）、
    scan
    （广泛分析）、
    search
    （查找）、
    triage
    （分类+执行）

Scope prefix (required)

范围前缀（必填）

Derived from 
metadata.scope
:
ScopePrefixExample
personal
p-
p-slack-triage
, 
p-daily-standup
organization
o-
o-org-release-digest
generic
(none)
skill-spec-audit
, 
gh-dep-pr-triage
由
metadata.scope
派生：
范围前缀示例
personal
p-
p-slack-triage
、
p-daily-standup
organization
o-
o-org-release-digest
generic
无
skill-spec-audit
、
gh-dep-pr-triage

Platform prefix (when single-platform dependent)

平台前缀（依赖单一平台时使用）

PlatformPrefixWhen 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.
平台前缀使用场景
GitHub
gh-
Skill需要
gh
CLI或GitHub API
Git
git-
Skill需要git但不需要GitHub
Slack
slack-
Skill需要Slack MCP服务器
Google Workspace
gws-
Skill需要
gws
CLI
多平台或通用Skill无需添加平台前缀。如果Skill涉及2个及以上平台，仅保留范围前缀即可。

Group prefix (when 2+ skills share a domain)

分组前缀（同一领域有2个及以上Skill时使用）

GroupSkills 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.
分组组内Skill
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
创建新Skill时，检查是否存在同领域的现有Skill。如果同一领域出现第二个Skill，需为两个Skill追溯添加共享前缀。

Local Conventions (beyond spec)

本地约定（超出规范要求）

These are project-specific conventions enforced on top of the spec:
FieldExpectedValues
argument-hint
If skill accepts argsShort usage hint string
metadata.author
AlwaysMust be present (non-empty)
metadata.scope
Always
generic
, 
personal
, or 
organization
metadata.confirms
If skill has side effectsList of operations requiring user confirmation
这些是项目特定的约定，在规范基础上额外强制执行：
字段要求取值范围
argument-hint
若Skill接受参数简短的使用提示字符串
metadata.author
必须存在非空值
metadata.scope
必须存在
generic
、
personal
或
organization
metadata.confirms
若Skill有副作用需要用户确认的操作列表

Workflow

工作流

Phase 1: Discover Skills

阶段1：发现Skill

  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
  1. 匹配
    ~/.claude/skills/*/SKILL.md
    文件
  2. 同时检查
    .claude/skills/*/SKILL.md
    （项目级）
  3. 跳过符号链接 —— 这些链接指向
    .agents/skills/
    ，有其自身约定
  4. 如果用户指定了Skill名称，筛选出匹配的目录
  5. 读取每个SKILL.md的前置元数据

Phase 2: Validate Each Skill

阶段2：验证每个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:
  1. Scope prefix matches 
    metadata.scope
    : 
    p-
    for personal, 
    o-
    for organization, none for generic
  2. Platform prefix present if skill depends on a single platform (
    gh-
    , 
    git-
    , 
    slack-
    , 
    gws-
    )
  3. No platform prefix if skill uses 2+ platforms
  4. Action synonym is standardized: 
    audit
    not 
    review
    /
    check
    , 
    scan
    not 
    inspect
  5. No single-word names (must have at least one hyphen)
  6. Max 40 chars, 2-4 words
  7. Abbreviations only from allowlist: 
    pr
    , 
    cli
    , 
    oss
    , 
    dep
    , 
    mcp
    , 
    gh
    , 
    gws
Local conventions:
  1. metadata.author
    is present and non-empty
  2. metadata.scope
    is one of: 
    generic
    , 
    personal
    , 
    organization
  3. 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
  1. argument-hint
    exists if the skill body references arg parsing, 
    ## Arguments
    , or accepts parameters
对每个SKILL.md，检查以下内容：
规范合规性：
  1. name
    存在，与目录名匹配，仅含小写字母和连字符，无连续连字符，长度1-64字符
  2. description
    存在，非空，长度1-1024字符
  3. compatibility
    存在（若缺失则发出警告 —— 规范不强制要求但本地预期存在）
命名约定：
  1. 范围前缀与
    metadata.scope
    匹配：
    p-
    对应personal，
    o-
    对应organization，generic无前缀
  2. 若Skill依赖单一平台，需添加平台前缀（
    gh-
    、
    git-
    、
    slack-
    、
    gws-
    ）
  3. 若Skill使用2个及以上平台，无需添加平台前缀
  4. 动作同义词符合标准化：使用
    audit
    而非
    review
    /
    check
    ，使用
    scan
    而非
    inspect
  5. 禁止单字名称（必须至少包含一个连字符）
  6. 最多40字符，2-4个词
  7. 仅允许使用允许列表中的缩写：
    pr
    、
    cli
    、
    oss
    、
    dep
    、
    mcp
    、
    gh
    、
    gws
本地约定：
  1. metadata.author
    存在且非空
  2. metadata.scope
    为以下值之一：
    generic
    、
    personal
    、
    organization
  3. 若Skill主体引用以下任一模式，
    metadata.confirms
    必须存在：
  • 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
  • 日历: 
    create event
    、
    insert event
  • 文件: 
    save to
    、
    write to
    、
    create file
  • 安装: 
    brew install
    、
    install
  1. 若Skill主体引用参数解析、
    ## Arguments
    章节或接受参数，
    argument-hint
    必须存在

Phase 3: Report

阶段3：生成报告

Print a table:
undefined
打印表格：
undefined

Skill Spec Audit

Skill Spec Audit

Skillnamenamingdesccompatauthorscopeconfirmsarg-hintIssues
gh-dep-pr-triageokokokokokokok—0
p-blog-writerokokokokokokokok0
new-skillokMISS:scope-prefixokMISSMISSMISSWARN—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
undefined
Skillnamenamingdesccompatauthorscopeconfirmsarg-hintIssues
gh-dep-pr-triageokokokokokokok—0
p-blog-writerokokokokokokokok0
new-skillokMISS:scope-prefixokMISSMISSMISSWARN—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
undefined

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

阶段4：修复（若使用--fix或用户要求）

For each issue, prompt the user for the value or infer it:
FieldInference 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.
针对每个问题，提示用户输入值或自动推断：
字段推断策略
compatibility
扫描主体中的CLI工具、MCP服务器 -> 建议"Requires X, Y"
metadata.author
从现有Skill推断或询问用户
metadata.scope
询问用户：generic、personal或organization?
metadata.confirms
从主体中提取副作用模式，列出供用户确认
argument-hint
若存在
## Arguments
章节则从中提取，否则询问用户
修复完成后，使用编辑功能在闭合的
---
前插入缺失字段。
重新运行验证并显示更新后的表格。

Determining 
metadata.scope

确定
metadata.scope

ScopeCriteria
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
范围判断标准
generic
适用于所有人，无个人/组织特定数据
personal
引用您的特定账户、频道、搜索词、语音
organization
引用公司仓库、内部工具、团队特定工作流

Determining 
metadata.confirms

确定
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:
Operationconfirms 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
仅当Skill可执行不可逆或外部可见操作时才添加
confirms
。只读Skill（扫描、搜索、报告）不需要
confirms
。
常见
confirms
模式：
操作confirms条目
发送Slack消息
send Slack messages
合并PR
merge PRs
批准PR
approve PRs
创建GitHub issue
create GitHub issues
创建GitHub release
create GitHub releases
创建日历事件
create calendar event
Git提交
create git commit
Git推送
push to remote
写入文件
save to filesystem
安装工具
install missing tools
创建PR
create PR
修改设置
modify settings files