第三部分：目录结构详解
本节目的：深入理解Skill的标准目录结构，为创建复杂Skill打基础。
3.1 标准目录结构
Skills采用约定优于配置的目录结构，每个Skill都是 .claude/skills/ 下的一个独立目录：
.claude/skills/[skill-name]/
├── SKILL.md # [必需] Skill核心定义文件（身份证+说明书）
├── scripts/ # [可选] 工具脚本目录（功能模块）
│ ├── processor.py # Python处理脚本
│ ├── validator.js # JavaScript验证脚本
│ └── utils/ # 工具函数
├── templates/ # [可选] 模板文件目录
│ ├── output-template.md # 输出模板
│ └── report-template.md # 报告模板
├── config/ # [可选] 配置文件目录
│ └── settings.json # 运行时配置
├── docs/ # [可选] 内部文档
│ └── design.md # 设计文档
└── data/ # [可选] 数据文件
└── knowledge-base.json # 知识库数据各目录用途说明
| 目录/文件 | 是否必需 | 用途 | 生活类比 |
|---|---|---|---|
SKILL.md | ✅ 必需 | 定义Skill元信息(YAML)+详细指令(Markdown) | APP的安装包信息+完整说明书 |
scripts/ | 可选 | 可执行的工具脚本 | APP的功能代码 |
templates/ | 可选 | 输出内容的模板 | 文档模板 |
config/ | 可选 | 运行时配置参数 | APP的设置选项 |
docs/ | 可选 | 开发者内部文档 | 开发手册 |
data/ | 可选 | 静态数据文件 | 离线数据包 |
🎯 重要说明：当前版本不再使用skill.yaml和prompts/文件夹，所有内容统一到SKILL.md文件中！
3.2 SKILL.md配置详解
SKILL.md 是Skill的核心定义文件，由两部分组成：YAML Frontmatter（元数据）和Markdown Body（详细指令）。
YAML Frontmatter字段表
| 字段名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
name | string | 推荐 | 目录名 | Skill名称，同时作为/斜杠命令（小写、连字符分隔，最多64字符） |
description | string | 推荐 | - | 简短描述（最多1024字符），Claude用此判断是否自动激活 |
context | string | 可选 | - | 设为fork时在独立子代理上下文中运行（Forked Context） |
model | string | 可选 | 继承 | 指定运行模型（如opus、sonnet、haiku） |
agent | string | 可选 | - | 指定代理类型（如Explore） |
allowed-tools | string | 可选 | 全部 | 限制可用工具列表（逗号分隔，如Read, Grep, Glob） |
user-invocable | boolean | 可选 | true | 是否允许用户通过/命令手动调用 |
disable-model-invocation | boolean | 可选 | false | 设为true时禁止Claude自动激活，只能手动/调用 |
argument-hint | string | 可选 | - | 参数提示（如[filename] [format]） |
最小配置示例
yaml
---
# 最简单的SKILL.md（只有2个必填字段）
name: code-commenter
description: 当用户要求"添加注释"或"代码注释"时自动为代码添加清晰的中文注释
---
# 这里开始是Markdown Body部分
(详细指令内容...)完整配置示例（公众号写作助手）
yaml
---
name: gongzhonghao-writer
description: 当用户提到"公众号"、"写文章"、"老金风格"等关键词时，自动激活AI写作助手系统
---
# 公众号写作助手 Skill
## 技能概述
本Skill提供数据驱动的AI公众号写作能力，包括：
- 爆款标题生成（5大公式）
- 老金风格文章创作
- 9维度质量检测
- 选题自动过滤
## 角色定义
你是一位经验丰富的公众号写作专家，擅长创作高质量、高传播性的内容。
## 核心能力
1. **爆款公式生成**：基于5大公式生成高转化标题
2. **9维度质量检测**：AI腔、自然度、真诚度等全面检测
3. **智能选题过滤**：三层架构判断是否值得写作
## 工作流程
(详细工作流程说明...)
## 输出规范
(输出格式要求...)💡 关键变化：
- YAML Frontmatter：
name和description为核心字段，还支持context、model、allowed-tools等可选字段 - Markdown Body：所有详细指令、规则、流程都在这里编写
- 不再需要：
version、author、triggers、prompt_files等旧版配置
3.3 Markdown Body编写规范
Markdown Body是SKILL.md的核心部分，包含所有详细指令。推荐遵循以下结构：
推荐结构模板
markdown
# [Skill名称]
## 一、角色定义
[AI的角色定位和专业背景]
## 二、核心能力
[列出3-5个核心能力]
## 三、工作流程
### 步骤1：[步骤名称]
[详细说明]
### 步骤2：[步骤名称]
[详细说明]
## 四、规则约束
[必须遵守的规则]
## 五、输出格式
[定义输出结构和格式]
## 六、示例展示
[好/坏示例对比]编写原则
- 层次清晰：使用多级标题组织内容
- 简洁明确：每段只讲一个要点
- 可操作性强：提供具体步骤而非抽象概念
- 示例驱动：用具体例子说明抽象规则
3.4 三种复杂度级别对比
根据你的需求，Skill可以从简单到复杂：
| 维度 | 简单Skill | 中等Skill | 复杂Skill |
|---|---|---|---|
| 文件数 | 1个（SKILL.md） | 3-5个 | 10+个 |
| 总大小 | <5KB | 5-50KB | >50KB |
| SKILL.md | <100行 | 100-500行 | 500+行 |
| scripts | 0个 | 1-2个 | 5+个 |
| config | 无 | 1个JSON | 多个配置文件 |
| 适用场景 | 单一任务 | 多步骤流程 | 企业级系统 |
| 示例 | 代码注释器 | API文档生成器 | 公众号写作助手 |
| 维护难度 | 低 | 中 | 高 |
建议：
- 新手从简单Skill开始
- 随着需求增长逐步扩展
- 不要过度设计
3.5 核心特性详解
🎯 掌握这些特性能让你的Skill开发事半功倍！
Hot Reloading（热重载）
功能说明：修改SKILL.md后，无需重启Claude Code，下次对话时修改会自动生效。
工作原理：
用户修改SKILL.md
↓
Claude Code检测到文件变化
↓
自动重新加载Skill定义
↓
下次对话时应用新规则使用体验：
bash
# 传统方式（2.10之前）
1. 修改skill.yaml或prompts/*.md
2. 退出Claude Code
3. 重新启动claude
4. 测试修改
# Hot Reloading方式
1. 修改SKILL.md
2. 直接测试，立即生效 ✨注意事项：
- YAML Frontmatter的修改会立即生效
- Markdown Body的修改会在下次对话时生效
- 如果修改未生效，可以尝试开始新对话或使用
/compact压缩上下文后重试
Sandbox安全机制
功能说明：Claude Code提供OS级别的沙箱隔离，限制文件系统写入和网络访问。
重要：Sandbox是Claude Code的全局安全功能（通过
/sandbox命令启用），不是SKILL.md的frontmatter字段。它对所有Bash工具调用生效，包括Skill中的脚本执行。
启用方式：
bash
# 在Claude Code会话中启用沙箱
/sandbox隔离能力：
| 维度 | 说明 |
|---|---|
| 文件系统 | 只能写入启动目录及子目录，读取不受限 |
| 网络 | 只能连接已批准的服务器，阻止未授权的外部连接 |
| OS级执行 | 基于Linux bubblewrap / macOS seatbelt的内核级隔离 |
对Skill脚本的影响：
- 当Sandbox启用时，Skill中
scripts/目录的脚本也受沙箱限制 - 脚本无法写入项目目录之外的路径
- 脚本无法访问未批准的网络地址
渐进式披露机制（详解）
三层披露结构：
第一层：元数据常驻
├─ YAML Frontmatter的name和description
├─ 始终在内存中，用于自动激活判断
└─ 极小的内存占用（<100字节）
第二层：指令按需加载
├─ Markdown Body在Skill激活时才加载
├─ 可以包含数千行的详细指令
└─ 用完即释放，不占用常驻内存
第三层：资源按需调用
├─ scripts/中的脚本只在调用时执行
├─ templates/中的模板只在渲染时读取
└─ config/中的配置只在需要时加载性能优势对比：
| 方式 | 旧版本（skill.yaml+prompts/） | 新版本（SKILL.md） |
|---|---|---|
| 内存占用 | 所有prompts常驻 | 只加载元数据 |
| 激活速度 | 需要读取多个文件 | 读取单个文件 |
| 修改生效 | 需要重启 | Hot Reloading |
| 维护成本 | 多文件同步 | 单文件管理 |