**Skill** 是一个包含 `SKILL.md` 文件（指令 + 元数据）及可选支撑脚本/资源的文件夹。Claude 动态加载 Skills，并遵循其中的指令，以一致、可重复的方式完成专项任务。
Skills 是 Claude 原生的能力系统 —— Anthropic 官方 Skills 库和开放的 [Agent Skills](https://agentskills.io) 生态都使用相同格式。
## Skill 的结构
```
skills/
└── frontend-design/
└── SKILL.md ← 指令 + frontmatter 元数据
```
`SKILL.md` 由 YAML frontmatter 头部和 Markdown 正文组成：
```markdown
---
name: frontend-design
description: 创建独具风格的生产级前端界面。
---
本 Skill 指导创建具有独特美学的前端界面...
## 设计思维
编码之前，先理解上下文并确定大胆的美学方向...
```
当 Claude 看到与某个 Skill 描述匹配的任务时，它会读取 `SKILL.md` 并遵循其指令，从而获得针对该任务的专项知识和一致行为。
## Skills 如何进入容器
若助手目录下存在 `skills/` 文件夹，框架在 `Runner.Prepare` 期间会自动将其复制进容器 —— 在 Create Hook 运行之前完成。无需在 `sandbox.yao` 中添加任何 `prepare` 步骤。
```
assistants/my-agent/
├── sandbox.yao
├── skills/ ← 框架自动检测并复制
│ ├── my-skill/
│ │ └── SKILL.md
│ └── another-skill/
└── src/
└── index.ts
```
在容器内，Skills 的目标路径为：
```
{work_dir}/.yao/assistants/{assistant_id}/skills/
```
环境变量 `CTX_SKILLS_DIR` 自动指向该路径，Skill 脚本可通过它引用自身位置，无需硬编码路径。
## 使用社区 Skills
[skills](https://github.com/anthropics/skills) 仓库（Anthropic 官方）和 [Agent Skills](https://agentskills.io) 生态提供了大量现成 Skill。
将社区 Skill 复制到你的 `skills/` 目录即可使用：
```bash
# 克隆 skills 仓库
git clone https://github.com/anthropics/skills
# 将 Skill 复制到你的助手中
cp -r skills/skills/frontend-design assistants/my-agent/skills/
```
目录结构变为：
```
assistants/my-agent/
└── skills/
└── frontend-design/
└── SKILL.md
```
下次请求时，框架会自动将其复制进容器。
## 创建自己的 Skill
在助手目录下创建 `skills/` 目录，每个子文件夹对应一个 Skill。
**最简 Skill：**
```
skills/
└── code-review/
└── SKILL.md
```
```markdown
---
name: code-review
description: 审查代码中的 Bug、安全问题和风格问题。当用户要求 review、审计或检查代码时使用。
---
仔细审查所提供的代码。
## 检查内容
- **正确性**：逻辑错误、边界问题、null 处理
- **安全性**：注入、越权、数据泄露
- **风格**：命名、结构、可读性
## 输出格式
提供结构化报告，包含以下部分：摘要、问题（含严重级别）、改进建议。
```
**带支撑脚本的 Skill：**
```
skills/
└── typescript-test/
├── SKILL.md
└── scripts/
└── run-tests.sh
```
在 `SKILL.md` 中使用 `$CTX_SKILLS_DIR` 引用脚本：
```markdown
---
name: typescript-test
description: 运行 TypeScript 测试并报告结果。
---
使用提供的脚本运行测试：
```bash
$CTX_SKILLS_DIR/typescript-test/scripts/run-tests.sh
```
```
## 自动复制的工作原理
当框架检测到助手目录下存在 `skills/` 时，会解析其绝对路径并作为 `SkillsDir` 传给 `Runner.Prepare`。Runner 随后调用 `workspace.Copy` 完成复制，这一步发生在用户定义的 `prepare` 步骤**之前**。
容器内的目标路径：
- **有 assistant ID**（正常情况）：`{work_dir}/.yao/assistants/{id}/skills/`
- **无 assistant ID**：`{work_dir}/.claude/skills/`
无需在 `sandbox.yao` 中添加任何配置。只需将 Skills 放在 `assistants/my-agent/skills/` 下即可。
## 下一步
Skills 给 Claude 带来知识。Workspace API 让 Hook 掌控 Claude 的读写行为。
→ **[Workspace API](./workspace)**
