Claude Code Skills |（2）开发进阶指南（2026最新）

一、创建第一个 Skill

1.1 最小结构

创建一个 Skill 最简单的方式：只需要一个文件。

C:\Users\用户名\.claude\skills\my-first-skill\ └── SKILL.md # 只需要这一个文件

1.2 创建步骤

REM 1. 创建目录 mkdir "%USERPROFILE%\.claude\skills\hello-skill" REM 2. 创建 SKILL.md cd /d "%USERPROFILE%\.claude\skills\hello-skill" notepad SKILL.md

1.3 SKILL.md 基本格式

--- name: hello-skill description: 简单的问候技能 --- # Hello Skill ## 目的 这是一个简单的示例技能，用于学习 Skills 的基本结构。 ## 执行指令 1. 向用户问好 2. 询问用户需要什么帮助 3. 提供友好的回应 ## 示例 用户输入：`/hello-skill` AI 响应：你好！我是 Hello Skill，很高兴为你服务！

1.4 测试 Skill

1. 保存文件
2. 重启 Claude Code
3. 测试：/hello-skill

二、SKILL.md 详解

2.1 完整结构

一个完整的 SKILL.md 包含两部分：

--- ← YAML Frontmatter 开始 name: my-skill ← 基本信息 description: 功能描述 argument-hint: [参数1] [参数2] disable-model-invocation: false ← 调用控制 user-invocable: true allowed-tools: [] ← 工具限制 --- ← YAML Frontmatter 结束 # Skill 内容（Markdown） ← Markdown 内容开始 ## 目的 说明用途... ## 执行指令 1. 步骤1 2. 步骤2 ## 示例 使用示例...

2.2 Frontmatter 字段速查表

2.3 调用控制配置

场景1：仅手动调用（敏感操作）

---name:deploy-proddescription:部署到生产环境disable-model-invocation:true# AI 不能自动调用user-invocable:true# 用户可以手动调用---

适用场景：

• 部署到生产环境
• 删除数据库
• 发送邮件通知
• 其他敏感操作

场景2：仅 AI 调用（背景知识）

---name:coding-standardsdescription:公司编码规范disable-model-invocation:false# AI 可以自动加载user-invocable:false# 不在菜单中显示---

适用场景：

• 编码规范
• 项目约定
• 背景知识
• 参考文档

场景3：双向调用（默认）

---name:code-reviewdescription:代码审查# 默认配置，两者都可以调用---

适用场景：

• 代码审查
• 文档生成
• 测试编写
• 大多数常规操作

2.4 工具访问限制

只读模式

---name:code-explorerdescription:探索代码库（只读）allowed-tools:-readFile-readMultipleFiles-listDirectory-grepSearch-fileSearch---

文件操作模式

---name:code-refactordescription:代码重构allowed-tools:-readFile-readMultipleFiles-listDirectory-grepSearch-fileSearch-strReplace-fsWrite---

2.5 Markdown 内容结构

推荐的章节结构：

# Skill 名称 ## 目的（Purpose） 说明这个 Skill 的用途和价值。 ## 触发条件（Trigger Conditions） 列出会触发此 Skill 的关键词或场景。 ## 执行指令（Instructions） 1. 第一步操作 2. 第二步操作 3. 第三步操作 ## 示例（Examples） **示例1**： - 用户输入：`/my-skill example` - AI 响应：执行相应操作... ## 支持文件（Supporting Files） 如果需要引用其他文件： - `scripts/process.py`: 数据处理脚本 - `references/api-spec.md`: API 规范文档

三、参数与动态内容

3.1 参数传递

使用 $ARGUMENTS 占位符

---name:fix-issuedescription:修复 GitHub Issueargument-hint:[issue-number]---# Fix GitHub Issue修复 Issue#$ARGUMENTS，遵循以下步骤：1. 查看 Issue 详情 2. 分析问题根源 3. 实现修复方案 4. 编写测试用例 5. 提交 PR

使用方法：

/fix-issue 123

Claude 会将$ARGUMENTS替换为123。

使用索引访问参数

---name:migrate-componentargument-hint:[component-name][from-framework][to-framework]---# Migrate Component将组件 $0 从 $1 迁移到 $2。# 或使用完整语法将组件 $ARGUMENTS[0]从 $ARGUMENTS[1]迁移到 $ARGUMENTS[2]。

使用方法：

/migrate-component Button React Vue

3.2 命令注入

语法

!command"

执行命令并将输出替换到 Skill 内容中。

示例：获取当前分支

---name:git-status-summarydescription:Git 状态摘要---# Git Status Summary## 当前分支!gitbranch--show-current"## 未提交的更改!gitstatus--short"## 最近的提交!gitlog--oneline-5" 请分析当前 Git 状态并提供建议。

工作流程

1. Skill 被触发
2. 所有!command"立即执行
3. 命令输出替换占位符
4. Claude 接收完整渲染的内容

⚠️注意：这是预处理，不是 Claude 执行的命令。

3.3 实战案例：API 文档生成器

---name:api-docdescription:生成 API 文档argument-hint:[method][path]---# API Documentation Generator## 参数-HTTP 方法：$0-API 路径：$1## 生成内容1. API 概述 2. 请求参数表格 3. 响应示例 4. 多语言代码示例（cURL、JavaScript、Python）## 使用方法/api-doc POST /users

四、管理多个 Skills

4.1 目录结构说明

推荐目录结构：

C:\Users\用户名\.claude\skills\ # 已安装的技能（带前缀） ├── ccs-anth-pdf\ # 来自 anthropics ├── ccs-anth-docx\ # 来自 anthropics ├── ccs-sup-test-driven-development\ # 来自 superpowers ├── ccs-jeff-react-expert\ # 来自 jeffallan └── my-custom-skill\ # 自己创建的（不需要前缀） C:\Users\用户名\claude-skills-repos\ # 仓库缓存目录（不要删除） ├── anthropics-skills\ ├── superpowers\ └── jeffallan-skills\

前缀说明：

• ccs-表示通过脚本安装的技能
• anth-、sup-、jeff-表示来源仓库
• 自己创建的技能不需要前缀

4.2 使用管理脚本

第一篇文章提供了完整的skills-manager.cmd脚本，功能包括：

• ✅ 一键安装三大仓库
• ✅ 一键更新（自动 git pull）
• ✅ 一键卸载
• ✅ 查看已安装列表

使用方法：

skills-manager.cmd install # 安装 skills-manager.cmd update # 更新 skills-manager.cmd uninstall # 卸载 skills-manager.cmd list # 查看列表

详见：《Claude Code Skills 安装使用完全指南》3.3 节

4.3 版本控制建议

团队项目：将项目级 Skills 提交到 Git

REM .gitignore 不要忽略 .claude 目录 REM !.claude/skills/ git add .claude\skills\ git commit -m "feat: add team skills" git push

创建 INSTALLED.txt 记录：

已安装的 Skills 来自 anthropics/skills - ccs-anth-pdf (v1.0, 2026-02-15) - ccs-anth-docx (v1.0, 2026-02-15) 来自 obra/superpowers - ccs-sup-test-driven-development (v2.0, 2026-02-10) - ccs-sup-code-review (v2.0, 2026-02-10) 自定义 Skills - my-workflow (v1.0, 2026-02-20)

4.4 手动管理命令

REM 查看已安装技能 dir /B "%USERPROFILE%\.claude\skills" REM 删除单个技能 rmdir /S /Q "%USERPROFILE%\.claude\skills\技能名" REM 删除所有脚本安装的技能 for /d %%i in ("%USERPROFILE%\.claude\skills\ccs-*") do rmdir /S /Q "%%i" REM 打开技能目录 explorer "%USERPROFILE%\.claude\skills"

五、最佳实践

5.1 编写黄金法则

法则1：Description 是触发器，不是文档

❌错误：

description:这是一个复杂的工具，用于处理各种文档格式，包括 PDF、Word、Excel 等，支持转换、合并、拆分等多种操作...

✅正确：

description:处理文档转换和合并

原因：Claude 使用 description 判断何时触发，简洁的关键词更有效。

法则2：专注单一功能

❌错误：

---name:super-skilldescription:做所有事情---支持：-代码生成-测试编写-文档生成-部署-监控

✅正确：

---name:commit-messagedescription:生成 Git 提交信息---# Commit Message Generator根据代码变更生成规范的提交信息。

原因：专注的 Skill 更可靠、更易维护、触发更精准。

法则3：避免过度预判

❌错误：

如果用户想要 A，则执行 X 如果用户想要 B，则执行 Y 如果用户想要 C，则执行 Z 如果用户没说清楚，则询问...

✅正确：

执行以下步骤： 1. 分析需求 2. 实施方案 3. 验证结果

原因：让 Claude 根据实际情况灵活处理。

5.2 安全注意事项

敏感信息处理

❌错误：

---name:deploy---使用以下凭证部署： API_KEY=sk-1234567890abcdef DATABASE_URL=postgresql://user:password@host/db

✅正确：

---name:deploy---部署步骤： 1. 确保环境变量已设置：-%API_KEY%-%DATABASE_URL% 2. 运行部署脚本

命令执行安全

❌危险：

!%ARGUMENTS%"

✅安全：

!gh pr view %ARGUMENTS% --json title"

5.3 性能优化

优化 Description

• 使用简洁的关键词
• 避免冗长的描述
• 专注核心功能
• 不超过 50 字符

使用引用文件

❌不推荐：

---name:api-guide---[10000 行 API 文档内容...]

✅推荐：

---name:api-guide---# API Guide核心指令...## 详细文档需要时查看 `references\api-spec.md`

控制技能数量

• 个人使用：10-20 个
• 团队项目：5-15 个
• 总计：不超过 30 个

5.4 常见陷阱

六、速查表

6.1 命令速查

6.2 Windows 命令速查

6.3 目录结构速查

个人级配置：

C:\Users\用户名\.claude\skills\ ├── skill-1\ │ ├── SKILL.md │ ├── scripts\ # 可选 │ ├── templates\ # 可选 │ └── references\ # 可选 └── skill-2\ └── SKILL.md

项目级配置：

D:\Projects\项目文件夹\ ├── .claude\ │ └── skills\ │ └── project-skill\ │ └── SKILL.md ├── src\ └── package.json

6.4 Skills 参数变量（在 SKILL.md 中使用）

💡注意：这些是 Skills 的参数变量，用$符号。

6.5 Windows 环境变量（在命令行/脚本中使用）

💡注意：这些是 Windows 系统环境变量，用%符号，在 CMD/脚本中使用。

6.6 常见错误速查

七、学习资源

官方资源

社区 Skills 资源

MCP 扩展（与 Skills 不同，是另一套体系）

💡提示：MCP（Model Context Protocol）是另一套扩展体系，与 Skills 不同。如需了解 MCP，请参考专门的 MCP 教程。

持续学习建议

每周任务：

• 使用 3-5 个技能，记录体验
• 发现改进点

每月任务：

• 更新技能仓库
• 清理不用的技能
• 优化性能