Claude Code Skills 基础教程

第一部分：入门基础

1. 什么是 Skills
2. Skills 规范详解
3. 创建你的第一个 Skill
4. Skills 使用方法

第二部分：作用域与协作

5. 作用域详解与优先级
6. 团队协作与隔离策略

第三部分：高级特性（扩展规范）

7. Skills 格式高级扩展
8. 触发器高级配置
9. 工具权限详细规约
10. Skill 组合与继承
11. 版本控制与兼容性
12. 调试与测试规范

第四部分：实战与发布

13. 实战案例：微信公众号转 Markdown
14. 发布与分发规范
15. 最佳实践与注意事项

附录

• 附录 A：常用 Tools 参考
• 附录 B：完整 YAML Schema 参考
• 附录 C：常见错误与解决方案
• 附录 D：内置变量一览

---

阅读指南

• 快速上手：阅读第一部分（1-4章），约 15 分钟即可创建第一个 Skill
• 团队使用：继续阅读第二部分（5-6章），了解多人协作的最佳实践
• 深入学习：第三部分包含高级扩展规范，部分特性可能需要 Claude Code 未来版本支持
• 参考查阅：附录提供完整的字段参考和错误排查

---

Skills 是 Claude Code 的扩展机制，允许你创建自定义的工作流和指令集，让 Claude 以特定方式完成复杂任务。

核心价值

• 复用性：一次编写，多次使用
• 标准化：统一团队的工作流程
• 专业化：为特定领域定制 Claude 的行为
• 效率提升：通过 快速调用复杂工作流

Skills vs 普通 Prompt

---

文件结构

Skills 以 Markdown 文件形式存储，遵循特定的结构规范：

YAML Front Matter 规范

Front Matter 字段详解（官方规范）

注意： 所有字段都是可选的。仅推荐使用 ，以便 Claude 知道何时使用该 Skill。

基础字段

调用控制字段

工具与执行字段

字符串替换变量

Markdown Body 规范

Body 部分是 Skill 的核心指令，使用标准 Markdown 格式：

---

💡 学以致用：在深入高级特性之前，让我们先创建一个简单的 Skill 来巩固基础知识。

示例：创建一个简单的代码审查 Skill

Step 1：创建 Skill 目录

Step 2：创建 SKILL.md 文件

Step 3：编写 Skill 内容

将以下内容写入 ：

Step 4：测试 Skill

在 Claude Code 中测试：

Skill 存储位置

Skills 采用四级作用域体系：

注意： 每个 Skill 是一个目录， 是必需的入口文件。

详细的作用域说明、优先级规则和团队协作策略，请参阅第二部分。

---

1. 直接调用

使用 前缀加 Skill 名称：

2. 带参数调用

参数通过 变量传递给 Skill：

3. 自然语言触发

Claude 会根据 自动判断是否需要调用：

4. 查看可用 Skills

5. 控制谁可以调用

---

四级作用域体系

根据官方规范，Skills 采用四级作用域体系，从高到低分别是：

目录结构规范

每个 Skill 是一个以 为入口的目录（非单个文件）：

优先级覆盖规则

同名 Skill 的覆盖规则（优先级从高到低）：

详细规则：

1. 项目级覆盖个人级： 会覆盖
2. Skills 优先于 Commands： 优先于
3. 企业级强制生效：通过托管设置部署的 Skills 无法被下级覆盖

嵌套目录自动发现

Claude Code 支持从子目录中自动发现 Skills，特别适合 Monorepo 场景：

自动发现规则：

• 当你在 编辑文件时，Claude Code 会加载：
  • （根级）
  • （当前包级）
• 当你在 编辑文件时，Claude Code 会加载：
  • （根级）
  • （当前服务级）

作用域选择指南

---

污染问题分析

在团队协作中，Skills 可能产生以下”污染”问题：

命名空间策略

1. 强制命名空间

2. 命名空间规范

3. 命名冲突检测

在项目中添加冲突检测脚本：

团队协作最佳实践

1. 分层治理模型

2. 权限隔离策略

3. 敏感信息隔离

4. .gitignore 配置

Monorepo 隔离策略

1. 包级隔离

2. 隔离验证脚本

上下文污染控制

1. 精简 description

2. 控制 Skill 数量

3. 使用

冲突解决流程

CI/CD 集成检查

---

⚠️ 重要声明

本部分内容包含官方规范的合理扩展，旨在提供更完整的工程实践指导。

已确认的官方支持字段：

• , ,
• ,
• , , , ,
• ,

本教程扩展的概念（可作为设计参考，实际支持情况请以官方文档为准）：

• 复杂参数类型系统、参数验证规则
• 条件逻辑、多阶段工作流
• 触发器高级配置、上下文感知
• 安全沙箱、模块化继承

这些扩展概念可以通过在 Skill 的 Markdown Body 中用自然语言描述来实现类似效果。

高级参数定义

参数类型系统

参数验证规则

参数依赖关系

条件逻辑与分支

在 Markdown Body 中使用条件标记：

变量与模板

内置变量

自定义变量

模板语法

---

generated_by: {SKILL_VERSION} generated_at: {$NOW} source: {source_url} } tags: {{#each tags}}

• {{this}} {{/each}} }

---

多阶段工作流

在 Body 中定义各阶段：

---

正则表达式模式

多条件触发

上下文感知触发

触发优先级

---

权限粒度claude code 教程控制

Bash 命令白名单详解

工具权限组

运行时权限请求

安全沙箱配置

---

调用其他 Skills

在 Body 中调用：

/file-validator file={input_file} strict=true

/markdown-formatter file={output_file}

Skill 继承

子 Skill 的 Body：

模块化设计

创建可复用的模块：

文件：

在 Skill 中使用模块：

---

语义化版本规范

版本约束

废弃声明

迁移指南

特性标记

---

调试模式

在 Body 中添加调试信息：

测试用例定义

测试夹具

日志规范

[INFO] 2024-01-26 10:30:00 – 开始处理文件: input.txt [DEBUG] 2024-01-26 10:30:01 – 文件大小: 1024 bytes [INFO] 2024-01-26 10:30:02 – 转换完成，生成: output.md [WARN] 2024-01-26 10:30:02 – 发现 2 个无法转换的元素，已跳过

错误追踪

---

如果你还没有创建过 Skill，请先阅读第一部分：入门基础中的快速入门指南。

需求分析

将微信公众号文章抓取并转换为 Markdown 格式，需要处理：

1. 文章内容获取
2. 图片下载和本地化
3. 格式转换
4. 元数据提取

技术难点

⚠️ 注意：微信公众号有以下限制需要处理：

• 图片有防盗链机制
• 部分内容需要登录态
• 存在反爬措施

Skill 实现

目录：

WebFetch: url: {提供的微信文章URL} prompt: 提取文章的完整内容，包括：标题、作者、公众号名称、发布时间、正文内容、所有图片URL

4. 替换 Markdown 中的图片路径为本地相对路径

注意：微信图片有防盗链，必须添加 Referer 头

5. 生成 Markdown 文件

按以下格式生成最终的 Markdown 文件：

6. 保存文件

1. 创建输出目录（如果不存在）
2. 生成文件名：
3. 使用 Write 工具保存文件
4. 输出成功信息，包括：
   • 保存路径
   • 文件大小
   • 图片数量（如果下载了图片）

文件结构

格式要求

• 使用 YAML Front Matter 存储元数据
• 正文使用标准 Markdown 语法
• 图片使用相对路径引用
• 保持原文的段落和格式结构
• 代码块需标注语言类型

质量标准

• 内容完整，无遗漏
• 格式正确，可直接渲染
• 图片可正常显示（如果下载）
• 元数据准确

1. URL 无效：提示用户检查 URL 格式
2. 网络错误：提示重试或检查网络连接
3. 内容获取失败：可能需要登录态，提示用户
4. 图片下载失败：记录失败的图片，继续处理其他内容
5. 写入失败：检查目录权限

基本使用

指定输出目录

不下载图片

1. 版权问题：抓取的内容仅供个人学习使用，请尊重原作者版权
2. 频率限制：避免短时间内大量抓取，可能触发反爬机制
3. 登录态：部分文章可能需要微信登录后才能完整访问
4. 图片时效：微信图片链接可能有时效性，建议及时下载
5. 格式兼容：某些复杂排版可能无法完美转换

• 批量处理多篇文章
• 支持导出为其他格式（HTML、PDF）
• 添加文章分类和标签
• 集成到知识库系统

命名空间

文档要求

生命周期

必需文档

README 模板

示例 1：基本使用

输出：

示例 2：高级用法

Q: 问题1？

A: 答案1

Q: 问题2？

A: 答案2

v1.0.0 (2024-01-26)

• 初始版本

MIT License

{作者名称} <{邮箱}>

分发方式

1. 文件分享

2. Git 仓库

3. 包管理（未来支持）

社区贡献指南

---

编写 Skills 的最佳实践

1. 清晰的任务定义

2. 详细的步骤说明

3. 提供具体示例

输出

常见问题

Q: Skill 不生效怎么办？

1. 检查文件位置是否正确
2. 验证 YAML Front Matter 格式
3. 确认 name 字段无特殊字符
4. 重启 Claude Code

Q: 如何调试 Skill？

1. 使用简化版本测试基本流程
2. 逐步添加复杂逻辑
3. 查看 Claude Code 的错误日志

Q: 如何分享 Skill？

1. 将 .md 文件分享给他人
2. 放入项目的 目录
3. 发布到社区仓库

安全注意事项

1. 敏感信息：不要在 Skill 中硬编码密码、API Key 等
2. 权限控制：合理配置 ，遵循最小权限原则
3. 输入验证：对用户输入进行验证，防止注入攻击
4. 网络请求：谨慎处理外部 URL，避免 SSRF 风险

---

Skills 是 Claude Code 强大的扩展机制，通过本教程你学会了：

基础知识

1. 规范理解：YAML Front Matter + Markdown Body 的结构
2. 创建方法：从简单到复杂的 Skill 编写流程
3. 使用技巧：多种调用方式和参数传递

作用域与协作

4. 四级作用域：企业级 → 项目级 → 个人级 → 插件级的层级体系
5. 优先级规则：覆盖机制、嵌套目录自动发现、Monorepo 支持
6. 团队隔离：命名空间策略、污染防护、CI/CD 集成检查

高级特性

7. 格式扩展：高级参数类型、条件逻辑、变量模板、多阶段工作流
8. 触发器配置：正则匹配、多条件触发、上下文感知
9. 权限控制：工具权限粒度、Bash 白名单、安全沙箱

工程实践

10. 组合继承：Skill 调用、继承扩展、模块化设计
11. 版本控制：语义化版本、兼容性管理、迁移指南
12. 调试测试：调试模式、测试用例、日志规范
13. 发布分发：命名规范、文档要求、社区贡献

实战经验

14. 案例实现：微信公众号转 Markdown 的完整 Skill

现在，你已经掌握了 Skills 的完整知识体系，可以开始创建专业级的 Skills，让 Claude Code 成为更强大的工作助手！

---

---

教程版本: 2.0.0 | 更新日期: 2025-01-26

---

---

---

---

教程版本: 2.0.0 | 更新日期: 2025-01-26