accelizero Claude Code Skill 开发规范
整合自 Claude 官方文档与 GitHub 工程示例，定期检查官方更新。
官方参考资源
维护与更新时请检索以下 URL：
- 官方 Skills 文档: https://docs.anthropic.com/en/docs/claude-code/skills （会重定向至 https://code.claude.com/docs/en/skills）
- 官方 Command Development SKILL.md: https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/SKILL.md
- 官方插件开发文档: https://docs.anthropic.com/en/docs/claude-code/plugins
- 官方子代理文档: https://docs.anthropic.com/en/docs/claude-code/sub-agents
- 官方 Hooks 文档: https://docs.anthropic.com/en/docs/claude-code/hooks
- 官方权限文档: https://docs.anthropic.com/en/docs/claude-code/permissions
- Claude Code GitHub 仓库: https://github.com/anthropics/claude-code
- Agent Skills 开放标准: https://agentskills.io
核心原则
Skill 内容是写给 Claude 的指令，不是写给用户的说明。
用户调用 /skill-name 时，内容直接成为 Claude 的工作指令。
正确写法（指令）：
Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
Provide specific line numbers and severity ratings.
错误写法（说明）：
This command will review your code for security issues.
You'll receive a report with vulnerability details.
Skill 目录结构
my-skill/
├── SKILL.md # 主指令文件（必需）
├── template.md # 模板（可选）
├── examples/ # 示例（可选）
├── references/ # 参考资料（可选）
└── scripts/ # 脚本（可选）
SKILL.md 建议控制在 500 行以内，详细资料放 references/ 等单独文件，在 SKILL.md 中引用即可。
存放位置与优先级
| 级别 | 路径 | 作用范围 |
|---|---|---|
| 企业级 | managed settings 配置 | 组织内所有用户 |
| 个人级 | ~/.claude/skills/<name>/SKILL.md |
所有项目 |
| 项目级 | .claude/skills/<name>/SKILL.md |
当前项目 |
| 插件级 | <plugin>/skills/<name>/SKILL.md |
启用插件处 |
优先级：企业 > 个人 > 项目。插件用 plugin-name:skill-name 命名空间，不冲突。
旧的 .claude/commands/*.md 文件继续兼容，同名时 skill 优先。
YAML Frontmatter 完整字段
---
name: my-skill # 名称，小写+连字符，最长64字符（可选，默认用目录名）
description: 做什么以及何时使用 # 描述（推荐，Claude 用此判断是否自动加载）
argument-hint: [arg1] [arg2] # 参数提示，自动补全时显示
disable-model-invocation: true # 禁止 Claude 自动调用（仅用户手动 / 触发）
user-invocable: false # 隐藏用户 / 菜单（仅 Claude 自动使用）
allowed-tools: Read, Grep, Glob # 限制可用工具
model: sonnet # 指定模型（sonnet/opus/haiku）
context: fork # 在子代理中隔离运行
agent: Explore # 子代理类型（搭配 context: fork）
hooks: ... # 生命周期钩子
version: 1.0.0 # 版本号（可选）
---
调用控制矩阵
| 配置 | 用户可调用 | Claude 可调用 | 上下文加载 |
|---|---|---|---|
| 默认 | Yes | Yes | 描述始终在上下文，调用时加载全文 |
disable-model-invocation: true |
Yes | No | 描述不在上下文，用户调用时加载 |
user-invocable: false |
No | Yes | 描述始终在上下文，调用时加载 |
动态变量
| 变量 | 说明 |
|---|---|
$ARGUMENTS |
所有传入参数 |
$ARGUMENTS[N] 或 $N |
第 N 个参数（0 起始），如 $0、$1 |
${CLAUDE_SESSION_ID} |
当前会话 ID |
${CLAUDE_SKILL_DIR} |
skill 所在目录路径 |
${CLAUDE_PLUGIN_ROOT} |
插件根目录（仅插件内可用） |
动态上下文注入
使用 ! + 反引号包裹的 shell 命令语法，在发送给 Claude 前执行命令，输出替换占位符。
语法格式：感叹号 + 反引号 + 命令 + 反引号，如 ! 后接 `gh pr diff`
示例 SKILL.md 内容（注意：以下为示例说明，实际编写时使用感叹号反引号语法）：
---
name: pr-summary
context: fork
agent: Explore
---
- PR diff: [感叹号反引号]gh pr diff[反引号]
- Changed files: [感叹号反引号]gh pr diff --name-only[反引号]
Summarize this pull request...
文件引用
使用 @ 语法引用文件内容：
Review @$1 for code quality # 动态引用
Review @package.json # 静态引用
@${CLAUDE_SKILL_DIR}/template.md # 引用 skill 目录下的文件
allowed-tools 权限控制
allowed-tools: Read, Grep, Glob # 只读模式
allowed-tools: Read, Write, Edit, Bash(git:*) # 含 git 操作
allowed-tools: Bash(npm:*) # 仅 npm 命令
allowed-tools: Bash(gh:*) # 仅 GitHub CLI
还可在 /permissions 中对 skill 做细粒度控制：
Skill(commit) # 精确匹配
Skill(review-pr *) # 前缀匹配
子代理模式 (context: fork)
---
name: deep-research
context: fork
agent: Explore # 可选: Explore, Plan, general-purpose, 或自定义代理
---
Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Analyze the code
3. Summarize findings
context: fork 适用于有明确任务指令的 skill。纯指导性内容（如编码规范）不适合 fork，因为子代理没有可执行的任务。
常用 Skill 模式
代码审查模式
---
name: review
description: Review code changes
allowed-tools: Read, Bash(git:*)
---
Files changed: [感叹号反引号]git diff --name-only[反引号]
Review each file for code quality, bugs, test coverage.
Issue 修复模式
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
argument-hint: [issue-number]
---
Fix GitHub issue #$ARGUMENTS:
1. Read the issue
2. Implement the fix
3. Write tests
4. Create a commit
文档生成模式
---
name: gen-docs
description: Generate documentation for file
argument-hint: [source-file]
---
Generate documentation for @$1 including function descriptions, parameters, return values, and usage examples.
可视化输出模式
Skill 可捆绑脚本生成 HTML 等交互式输出：
my-visual-skill/
├── SKILL.md
└── scripts/
└── visualize.py
SKILL.md 中指示 Claude 运行脚本，生成文件后在浏览器打开。
输入验证模式
Validate: [感叹号反引号]echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"[反引号]
If valid, proceed. Otherwise, show usage.
命名与组织
命名规范
- 使用 动词-名词 模式：
review-pr、fix-issue、gen-docs - 小写字母 + 数字 + 连字符，最长 64 字符
- 避免过于通用的名称（test、run）
目录组织
- 5-15 个 skill：扁平结构
- 15+ 个 skill：按类别分子目录（ci/、git/、docs/）
排错指南
| 问题 | 排查 |
|---|---|
| Skill 不触发 | 检查 description 关键词；运行 What skills are available?；尝试直接 /skill-name |
| Skill 触发太频繁 | 缩窄 description；加 disable-model-invocation: true |
| 参数不生效 | 检查 $1/$ARGUMENTS 语法；确认 argument-hint |
| Bash 执行失败 | 检查 allowed-tools 含 Bash；先在终端测试命令 |
| 文件引用无效 | 检查 @ 语法和路径；确保 Read 工具可用 |
| Skill 太多被截断 | 运行 /context 查看；设置 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量 |
开发工作流
当用户描述需求后，按以下步骤开发 skill：
- 确定 scope：个人级（~/.claude/skills/）还是项目级（.claude/skills/）
- 创建目录：
mkdir -p <path>/<skill-name> - 编写 SKILL.md：填写 frontmatter + 指令内容
- 添加辅助文件：模板、示例、脚本等（如需要）
- 测试：直接
/skill-name或让 Claude 自动触发 - 迭代：根据测试结果调整 description 和指令
现在请告诉我你想开发什么 skill，我来帮你实现。