Claude Code技能开发指南——从零打造你自己的Skills

Claude Code技能开发指南——从零打造你自己的Skills 🛠️

📅 更新于：2026年5月15日 | ✍️ 原创文章，转载请注明出处

📌 目录

1. 为什么要自己开发Skills
2. SKILL.md规范详解
3. Frontmatter字段全解
4. 触发条件设计
5. 动态上下文注入
6. 脚本与模板编写
7. 高级特性
8. 实战：从零开发一个完整Skill
9. 测试与调试
10. 发布与分享
11. 最佳实践
12. 总结

1. 为什么要自己开发Skills

🎯 解决团队痛点

📊 真实收益

根据社区反馈：

2. SKILL.md规范详解

基本结构

skill-name/ # 目录名 = 技能名 ├── SKILL.md # 必需：入口文件 ├── scripts/ # 可选：脚本目录 │ ├── validate.sh │ └── deploy.sh ├── templates/ # 可选：模板目录 │ └── component.tsx.template ├── examples/ # 可选：示例目录 │ └── sample-output.md └── references/ # 可选：参考文档 └── api-spec.md

SKILL.md文件格式

--- # YAML Frontmatter（元数据） name: my-skill description: "技能描述" --- # Markdown Content（指令正文） 这是Claude遵循的具体指令... ## 步骤1 ... ## 步骤2 ...

命名规范

3. Frontmatter字段全解

完整字段列表

---# ═══════════════════════════════════════# 基础信息# ═══════════════════════════════════════name:my-skill# 技能名（必需）description:"代码审查技能"# 描述（推荐，Claude根据此自动触发）when_to_use:"用户要求审查代码时"# 补充触发上下文argument-hint:"[file-path]"# 参数提示（显示在自动补全中）# ═══════════════════════════════════════# 参数定义# ═══════════════════════════════════════arguments:-name:targetdescription:"审查目标文件或目录"required:true-name:severitydescription:"最低严重级别"required:falsedefault:"warning"# ═══════════════════════════════════════# 调用控制# ═══════════════════════════════════════disable-model-invocation:true# true = 只能手动 /skill-nameuser-invocable:false# false = 只有Claude能调用# ═══════════════════════════════════════# 工具权限# ═══════════════════════════════════════allowed-tools:-Read# 读取文件-Edit# 编辑文件-Write# 创建文件-Bash(git diff*)# Git差异-Bash(npm run lint:*)# Lint命令-WebSearch# 网络搜索# ═══════════════════════════════════════# 执行配置# ═══════════════════════════════════════model:opus# 覆盖模型（sonnet/opus/haiku）effort:high# 覆盖推理深度context:fork# 在子代理中运行agent:Explore# 使用探索型子代理# ═══════════════════════════════════════# 路径过滤# ═══════════════════════════════════════paths:-"src/**/*.ts"# 只在操作TS文件时激活-"tests/**"# 或测试文件# ═══════════════════════════════════════# Shell配置# ═══════════════════════════════════════shell:bash# bash（默认）或 powershell# ═══════════════════════════════════════# 钩子（生命周期事件）# ═══════════════════════════════════════hooks:PreToolUse:-matcher:"Write"hooks:-type:commandcommand:"echo 'About to write file'"PostToolUse:-matcher:"Bash(npm test *)"hooks:-type:commandcommand:"echo 'Tests completed'"---

字段详解

description— 触发关键

这是最重要的字段，Claude根据它判断何时使用技能。

好的描述：

description:"当用户要求代码审查、PR审查或安全检查时自动触发"

差的描述：

description:"审查代码"# 太模糊

allowed-tools— 工具预授权

避免Claude每次使用工具都询问权限。

语法：

allowed-tools:-Read# 工具名-Bash(git*)# 通配符匹配-Bash(npm run lint:*)# 命令模式-Edit# 文件编辑-mcp__github__*# MCP工具

context: fork— 子代理隔离

适合需要独立上下文的复杂任务：

context:fork# 在子代理中运行agent:Explore# 使用探索型子代理（只读）

适用场景：

• 安全扫描（不污染主上下文）
• 大范围代码分析
• 并行任务

paths— 智能激活

只在操作特定文件时激活：

paths:-"src/**/*.ts"# TypeScript源码-"tests/**/*.test.ts"# 测试文件-"!**/node_modules/**"# 排除node_modules

4. 触发条件设计

三种触发方式

方式1：自动触发（Claude判断）

---description:"当用户要求创建React组件时使用"---

Claude根据用户意图自动匹配。

方式2：手动触发（用户调用）

---name:deploydisable-model-invocation:true---

用户必须输入/deploy才会触发。

方式3：混合触发

---description:"代码审查，也可通过/review手动调用"---

两种方式都可以。

触发设计最佳实践

触发描述模板

# 通用型description:"当用户要求[动作]时使用"# 条件型description:"当用户[条件A]且[条件B]时使用"# 排除型description:"当用户要求[动作]，但不涉及[排除场景]时使用"

5. 动态上下文注入

Shell命令注入

用!`command`在技能加载时执行命令并注入结果：

## 当前状态 分支：!`git branch --show-current` 最近提交：!`git log --oneline -1` 变更文件：!`git diff --name-only HEAD`

注意：命令在技能加载时执行，不是Claude读取时。

多行命令

用```!代码块：

## 项目信息 ```! echo "Node版本: $(node --version)" echo "NPM版本: $(npm --version)" echo "项目名: $(basename $(pwd))"

### 变量替换 | 变量 | 说明 | 示例 | |------|------|------| | `$ARGUMENTS` | 用户输入的全部参数 | `/review src/` → `src/` | | `$0`, `$1`, `$N` | 位置参数 | `/review src/ main` → `$0=src/`, `$1=main` | | `$name` | 命名参数 | 见下方示例 | | `${CLAUDE_SESSION_ID}` | 当前会话ID | - | | `${CLAUDE_EFFORT}` | 当前推理级别 | - | | `${CLAUDE_SKILL_DIR}` | 技能目录路径 | 引用附属文件 | ### 命名参数示例 ```yaml --- arguments: - name: target description: "审查目标" required: true - name: level description: "严格程度" default: "normal" --- 审查目标：$target 严格程度：$level

用户调用：/review --target src/ --level strict

引用附属文件

## 审查规则 参考规则文件： ${CLAUDE_SKILL_DIR}/references/rules.md 运行验证脚本： ${CLAUDE_SKILL_DIR}/scripts/validate.sh $ARGUMENTS

6. 脚本与模板编写

脚本集成

目录结构：

my-skill/ ├── SKILL.md └── scripts/ ├── validate.sh ├── lint.sh └── deploy.sh

在SKILL.md中调用：

## 验证步骤 1. 运行验证脚本： ${CLAUDE_SKILL_DIR}/scripts/validate.sh $ARGUMENTS 2. 检查输出结果 3. 如果有错误，报告并停止

脚本示例（scripts/validate.sh）：

#!/bin/bash# validate.sh - 代码验证脚本set-eTARGET=${1:-.}echo"🔍 Validating:$TARGET"# ESLint检查ifcommand-veslint&>/dev/null;thenecho"Running ESLint..."eslint"$TARGET"--format=compactfi# TypeScript检查ifcommand-vtsc&>/dev/null;thenecho"Running TypeScript check..."tsc--noEmitfi# 测试if[-f"package.json"];thenecho"Running tests..."npmtest----passWithNoTestsfiecho"✅ Validation complete!"

模板集成

目录结构：

my-skill/ ├── SKILL.md └── templates/ ├── component.tsx.template ├── test.spec.ts.template └── api-route.ts.template

在SKILL.md中引用：

## 创建组件 根据模板创建新组件： ${CLAUDE_SKILL_DIR}/templates/component.tsx.template 将模板中的占位符替换为： - `{{ComponentName}}` → 用户指定的组件名 - `{{Description}}` → 组件描述

模板示例（templates/component.tsx.template）：

importReactfrom'react';interface{{ComponentName}}Props{// TODO: 定义属性}/** * {{Description}} */exportconst{{ComponentName}}:React.FC<{{ComponentName}}Props>=(props)=>{return(<div className="{{component-name}}">{/* TODO: 实现组件 */}</div>);};exportdefault{{ComponentName}};

7. 高级特性

子代理执行

---context:forkagent:Explore---

子代理类型：

条件逻辑

在Markdown中用自然语言描述条件：

## 处理流程 1. 检查 `$target` 是否存在 2. 如果是目录： - 递归扫描所有.ts文件 - 生成目录级别的报告 3. 如果是文件： - 详细分析单个文件 - 生成文件级别的报告 4. 如果不存在： - 报告错误并停止

错误处理

## 错误处理 如果任何步骤失败： 1. 记录错误信息 2. 尝试恢复（如果可能） 3. 生成错误报告 4. 停止后续步骤 **不要**： - 忽略错误继续执行 - 修改用户文件导致不一致

权限控制

---allowed-tools:-Read-Bash(git diff*)-Bash(git log*)# 不包含Write和Edit → 只读技能---

8. 实战：从零开发一个完整Skill

需求：团队代码审查技能

目标：

• 统一审查标准
• 自动检查常见问题
• 生成结构化报告

步骤1：创建目录

mkdir-p~/.claude/skills/team-review/{scripts,references}

步骤2：编写SKILL.md

# ~/.claude/skills/team-review/SKILL.md---name:team-reviewdescription:"当用户要求代码审查、PR审查时自动触发"allowed-tools:-Read-Bash(git diff*)-Bash(git log*)-Bash(git show*)arguments:-name:targetdescription:"审查目标（文件、目录或PR号）"required:falsedefault:"HEAD"-name:severitydescription:"最低报告级别（info/warning/error）"required:falsedefault:"warning"---# 团队代码审查技能你是一个严格的代码审查员。按照以下标准审查代码。## 审查标准### 🔴 严重问题（必须修复）1.**安全漏洞**-SQL注入-XSS攻击-命令注入-硬编码密码/密钥-不安全的反序列化 2.**数据安全**-敏感信息泄露（日志、响应）-缺少输入验证-权限检查缺失 3.**逻辑错误**-空指针未处理-资源未释放-并发竞态条件### 🟡 警告问题（建议修复）1.**代码质量**-函数超过50行-嵌套超过3层-重复代码-命名不清晰 2.**性能问题**-N+1查询-不必要的循环-内存泄漏风险 3.**可维护性**-缺少注释（复杂逻辑）-魔法数字-过度耦合### 🟢 信息提示（可选改进）1.**代码风格**-格式不一致-import顺序-未使用的变量 2.**最佳实践**-可以用更现代的语法-可以提取公共方法## 审查流程### 1. 获取变更内容```bash# 如果是PRgit diff main...$target# 如果是文件git diff HEAD--$target# 如果是最新提交git show HEAD--stat

2. 逐文件审查

对每个变更文件：

1. 理解变更目的
2. 检查上述标准
3. 记录问题

3. 生成报告

输出格式：

## 代码审查报告 **审查范围**：$target **审查时间**：$(date) **最低级别**：$severity --- ### 📊 统计 | 级别 | 数量 | |------|------| | 🔴 严重 | N | | 🟡 警告 | N | | 🟢 信息 | N | --- ### 🔴 严重问题 #### [问题标题] - **文件**：`path/to/file.ts:42` - **描述**：[问题详细描述] - **建议**：[修复建议] - **示例**： ```typescript // ❌ 当前代码 const query = `SELECT * FROM users WHERE id = ${userId}`; // ✅ 建议修改 const query = 'SELECT * FROM users WHERE id = ?'; db.query(query, [userId]);

🟡 警告问题

（同上格式）

🟢 信息提示

（同上格式）

✅ 亮点

值得肯定的地方：

• [亮点1]
• [亮点2]

📝 总结

[总体评价和建议]

## 上下文注入 当前分支：!`git branch --show-current` 最近提交：!`git log --oneline -5` 变更统计：!`git diff --stat HEAD`

步骤3：编写参考文档

# ~/.claude/skills/team-review/references/rules.md # 团队编码规范 ## 命名规范 - 变量：camelCase - 常量：UPPER_SNAKE_CASE - 类：PascalCase - 文件：kebab-case ## 注释规范 - 公共API必须JSDoc - 复杂逻辑必须行内注释 - TODO必须关联Issue号 ## 测试规范 - 新功能必须有测试 - Bug修复必须有回归测试 - 覆盖率不低于80%

步骤4：测试使用

# 在Claude Code中测试claude# 方式1：自动触发>帮我审查一下最近的改动# 方式2：手动触发>/team-review# 方式3：指定目标>/team-review--targetsrc/auth/

步骤5：迭代优化

根据使用反馈调整：

• 补充遗漏的检查项
• 调整严重级别
• 优化报告格式

9. 测试与调试

测试清单

• 自动触发是否正常（描述匹配）
• 手动触发是否正常（/skill-name）
• 参数替换是否正确
• 动态上下文是否注入
• 工具权限是否生效
• 路径过滤是否正确
• 子代理是否正常（如使用）
• 错误处理是否完善

调试技巧

1. 查看技能是否加载

# 在Claude Code中/help# 检查技能是否出现在命令列表中

2. 测试动态上下文

在SKILL.md中添加调试输出：

## 调试信息（发布前删除） 当前目录：!`pwd` 环境变量：!`echo $NODE_ENV`

3. 检查触发条件

临时修改description，测试不同触发词：

description:"测试触发：当用户提到'review'时"

4. 查看上下文使用

# 在Claude Code中/context# 检查技能占用的token

常见问题

10. 发布与分享

方式1：项目内共享（推荐团队）

# 1. 技能放在项目目录cp-r~/.claude/skills/team-review /path/to/project/.claude/skills/# 2. 提交到gitcd/path/to/projectgitadd.claude/skills/team-reviewgitcommit-m"feat: add team code review skill"# 3. 团队成员pull后自动可用

方式2：GitHub仓库分享（推荐社区）

# 1. 创建仓库mkdirmy-claude-skillscdmy-claude-skillsgitinit# 2. 添加技能cp-r~/.claude/skills/my-* skills/# 3. 编写READMEcat>README.md<<'EOF' # My Claude Code Skills ## 安装 \`\`\`bash git clone https://github.com/yourname/my-claude-skills.git cp -r my-claude-skills/skills/* ~/.claude/skills/ \`\`\` ## 技能列表 - **skill-1**：描述 - **skill-2**：描述 EOF# 4. 推送到GitHubgitadd.gitcommit-m"Initial commit"gitpush origin main

方式3：NPM包分享

// package.json{"name":"@yourname/claude-skills","version":"1.0.0","description":"Claude Code skills collection","files":["skills/"],"scripts":{"postinstall":"cp -r skills/* ~/.claude/skills/"}}

用户安装：

npminstall-g@yourname/claude-skills

方式4：插件发布

# 1. 创建插件结构my-plugin/ ├── plugin.json ├── skills/ │ └── my-skill/ │ └── SKILL.md └── README.md# 2. plugin.json{"name":"my-plugin","version":"1.0.0","skills":["skills/my-skill"]}# 3. 用户安装/install-plugin my-plugin

发布检查清单

• 技能名不与已有技能冲突
• description清晰准确
• 包含使用示例
• 脚本有执行权限
• 测试通过
• README完整
• LICENSE明确

11. 最佳实践

设计原则

代码规范

# ✅ 好的实践---name:code-reviewdescription:"当用户要求代码审查时自动触发，检查安全、质量、性能"allowed-tools:-Read-Bash(git diff*)---# ❌ 差的实践---name:skill1description:"审查"allowed-tools:-"*"# 过度授权---

性能优化

1. 精简动态注入：只注入必要信息
2. 路径过滤：避免在无关文件上激活
3. 子代理隔离：复杂任务用context: fork
4. 按需加载：支持文件用相对路径引用

团队协作

1. 统一命名：team-前缀区分团队技能
2. 版本控制：SKILL.md纳入git
3. 变更日志：在SKILL.md头部记录变更
4. 代码审查：技能本身也需要审查

12. 总结

开发流程

需求分析 → 设计触发 → 编写指令 → 添加脚本 → 测试调试 → 发布分享

核心要点

下一步

• 📖上一篇：Claude Code 2026热门技能Top 20推荐 →
• 📖下一篇：Claude Code技能实战——5个真实项目中的技能组合打法 →
• 🔗官方文档：https://code.claude.com/docs/en/skills

📚 参考资料

1. Claude Code Skills官方文档：https://code.claude.com/docs/en/skills
2. Agent Skills开放标准：https://github.com/anthropics/claude-code
3. SKILL.md规范：https://code.claude.com/docs/en/skills#skillmd-format
4. 动态上下文注入：https://code.claude.com/docs/en/skills#dynamic-context
5. 子代理执行：https://code.claude.com/docs/en/skills#subagent-execution

💬 你开发过Claude Code技能吗？遇到了哪些坑？欢迎评论区分享经验！

📌 下一篇将带来5个真实项目中的技能组合实战，手把手教你用技能提升开发效率！