# Claude Skill

> Claude Code Skill/Command 开发规范与最佳实践。当用户需要创建、修改、调试 skill 或 slash command 时使用。

- Skill: `accelizero/claude-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add accelizero/claude-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/accelizero/claude-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: accelizero (https://skillmd.com/u/accelizero)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/accelizero/claude-skill

---


# 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 的工作指令。

正确写法（指令）：
```markdown
Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
Provide specific line numbers and severity ratings.
```

错误写法（说明）：
```markdown
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 完整字段

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

## 文件引用

使用 `@` 语法引用文件内容：

```markdown
Review @$1 for code quality       # 动态引用
Review @package.json              # 静态引用
@${CLAUDE_SKILL_DIR}/template.md  # 引用 skill 目录下的文件
```

## allowed-tools 权限控制

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

```yaml
---
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 修复模式
```yaml
---
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
```

### 文档生成模式
```yaml
---
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：

1. **确定 scope**：个人级（~/.claude/skills/）还是项目级（.claude/skills/）
2. **创建目录**：`mkdir -p <path>/<skill-name>`
3. **编写 SKILL.md**：填写 frontmatter + 指令内容
4. **添加辅助文件**：模板、示例、脚本等（如需要）
5. **测试**：直接 `/skill-name` 或让 Claude 自动触发
6. **迭代**：根据测试结果调整 description 和指令

现在请告诉我你想开发什么 skill，我来帮你实现。