Instructions

Instructions

This skill provides comprehensive instructions for the agent.

Usage

Follow these steps to use the skill effectively.

Notes

Additional context for the agent.

- **`## Instructions` 顶层区块**：正文的入口标题，向 Agent 陈述该技能要传授的核心行为规范；
- **`### Usage` 子节**：给出"如何按步骤使用本技能"的可执行流程，让 LLM 有明确的操作顺序可循；
- **`### Notes` 子节**：补充正文之外、可能影响执行的上文或边界提示，属于"附加上下文"。

从解析器角度看，正文是"Frontmatter 之后的全部剩余内容"。解析规则集中在 [parser.py](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/parser.py?utm_source=gitcode_repo_files)：

- 文件必须**以 `---` 开头**，否则抛 `SkillParseError`；闭合分隔符用正则 `\n---[ \t]*(?:\n|$)` 在 `pos=3` 之后搜索；
- 中间片段经 `yaml.safe_load` 解析，必须得到 YAML 映射（dict），否则解析失败（见 [parse_frontmatter](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/parser.py?utm_source=gitcode_repo_files#L39-L73)）；
- 正文存在 **50,000 字符（`_MAX_BODY_CHARS`）的警戒线**：超过阈值仅记录 warning，提示"过大的正文可能在注入提示词时显著占用上下文窗口"（见 [load_skill_metadata](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/parser.py?utm_source=gitcode_repo_files#L95-L126)）。

因此正文写作应遵循"结构化、分节清晰、言简意赅"的原则——它不仅写给人类读，更会原样注入 Agent 的系统提示词成为其行为依据，正文质量直接决定技能效果。

## 四、目录即元数据：scripts / references / assets 三类资源目录

`valid-skill` 的"完整"还体现在它同时提供了三个可选资源子目录，三者合起来由 `Literal["scripts", "references", "assets"]` 类型（`ResourceDirName`，见 [models.py](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/models.py?utm_source=gitcode_repo_files#L22)）统一定义，并在 [Skill 模型](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/models.py?utm_source=gitcode_repo_files#L136-L149) 中以 `scripts_dir` / `references_dir` / `assets_dir` 三个属性暴露对应路径：

- **`scripts/`** ——可执行脚本。[scripts/setup.sh](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/tests/skills/fixtures/valid-skill/scripts/setup.sh?utm_source=gitcode_repo_files) 是一个输出 `setup` 的最小 Bash 脚本，用于搭建/初始化技能运行所需的本地环境；
- **`references/`** ——供参考的文档。[references/guide.md](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/tests/skills/fixtures/valid-skill/references/guide.md?utm_source=gitcode_repo_files) 是"给 Agent 查阅的深度参考材料"，适合放正文中不便完整展开、按需查阅的长文档；
- **`assets/`** ——静态数据资源。[assets/config.json](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/tests/skills/fixtures/valid-skill/assets/config.json?utm_source=gitcode_repo_files) 是一个简单的 `{"key": "value"}` JSON，可承载模板、配置或示例数据。

这三个目录与正文的分工是"分层披露"的物理基础：正文承担**始终注入**的高频指令，资源目录承担**按需加载**的低频重资产。加载器对资源的"编目"逻辑位于 [load_skill_resources](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/parser.py?utm_source=gitcode_repo_files#L159-L193)：用 `rglob("*")` 递归扫描目录内所有文件，按 `relative_to(resource_dir)` 转成相对路径并 `sorted()` 排序，最终形成 `{"scripts": [...], "references": [...], "assets": [...]}` 的资源清单。

## 五、三级渐进式披露：METADATA → INSTRUCTIONS → RESOURCES

`valid-skill` 之所以能被"先发现、后激活、再加载资源"，靠的是模型层定义的三个披露等级常量（[models.py](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/models.py?utm_source=gitcode_repo_files#L25-L40)）：

| 常量 | 值 | 含义 |
| --- | --- | --- |
| `METADATA` | 1 | 仅读取 Frontmatter 元数据（`name`、`description`） |
| `INSTRUCTIONS` | 2 | 进一步载入完整 `SKILL.md` 正文 |
| `RESOURCES` | 3 | 在指令级基础上，编目三类资源目录中的文件 |

三者呈单调递进关系（`METADATA < INSTRUCTIONS < RESOURCES`，由 [test_models.py 的 TestDisclosureLevel](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/tests/skills/test_models.py?utm_source=gitcode_repo_files#L16-L26) 断言验证），每次升级通过 [Skill.with_disclosure_level](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/models.py?utm_source=gitcode_repo_files#L151-L177) 返回一个**携带新等级的新 Skill 对象**，原对象保持不变——这是一种不可变的、随取随用的"披露视图"设计。

与之对应的加载管线分为三步：

1. **发现与元数据加载**：[discover_skills](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/loader.py?utm_source=gitcode_repo_files#L44-L117) 扫描搜索路径下的**直接子目录**，凡包含 `SKILL.md` 者即调用 `load_skill_metadata` 读入元数据，达到 METADATA 级；单个子目录加载失败只记录 warning 并跳过，不会中断整批发现，同时会向事件总线发出 `SkillDiscoveryStarted` / `SkillLoaded` / `SkillLoadFailed` / `SkillDiscoveryCompleted` 事件；
2. **指令级激活**：[activate_skill](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/loader.py?utm_source=gitcode_repo_files#L120-L151) 将技能提升到 INSTRUCTIONS 级，读入完整正文并发射 `SkillActivatedEvent`；激活是**幂等**的——已处于指令级及以上的技能会原样返回；
3. **资源级加载**：`load_skill_resources`（在 loader 中再导出为 [load_resources](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/loader.py?utm_source=gitcode_repo_files#L281-L290)）提升到 RESOURCES 级并编目资源清单。

为什么要分级？**节省上下文窗口**。并非每个技能、每次执行都需要完整正文与资源清单。集成测试 [test_integration.py](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/tests/skills/test_integration.py?utm_source=gitcode_repo_files#L87-L107) 验证了关键行为：Agent 拿到的"发现级"技能停留在 METADATA，正文 `instructions` 为 `None`，注入系统提示词时**绝不泄露完整指令**（断言 `"Use this skill for travel planning." not in system`）。只有当技能确实被激活，正文才会进入上下文。

## 六、提示词中的呈现：`<skill>` XML 封装

技能最终如何呈现给 Agent？答案是统一封装为 XML 风格的 `<skill name="...">` 块，见 [format_skill_context](https://gitcode.com/GitHub_Trending/cr/crewAI/blob/b608a3595c95085225e9dd47432d74989f1a1d78/lib/crewai/src/crewai/skills/loader.py?utm_source=gitcode_repo_files#L293-L326)：

- **METADATA 级**：只输出技能名与描述——

A complete test skill with all optional directories. ``` - **INSTRUCTIONS 级及以上**：输出完整正文，格式为 `` + 描述 + 空行 + 指令正文 + ``； - **RESOURCES 级**：额外追加 `### Available Resources` 小节，逐目录列出已编目的资源文件： ``` ### Available Resources - **assets/**: config.json - **references/**: guide.md - **scripts/**: setup.sh ```

封装成统一的 XML 块（而不是裸文本）有一个工程上的好处：它能作为稳定的缓存锚点，让以技能内容为键的系统提示词缓存更可靠——这是代码注释中明确写明的设计动机。

load_skill 还支持多种输入形态（loader.py）：已加载的 Skill 对象原样透传；Path 与普通字符串视为搜索路径做发现+激活；以 ---\n 开头的字符串视为内联 SKILL.md（跳过文件系统直接解析，integration 测试中有 inline-review 实例）；@org/name 形式则走技能注册中心解析。批量入口 load_skills 还会按技能名去重（注册中心技能按 org/name 去重）。若多个来源出现了同名的 METADATA 级技能，build_skill_catalog 会用"父目录名/技能名"生成限定标签以避免混淆。

七、从 valid-skill 反推：一份可复用的一线技能模板

综合夹具写法与源码约束，编写一份可直接放进技能搜索目录的 SKILL.md 建议按如下模板组织：

---
name: my-skill          # 1-64 字符；小写字母/数字/单连字符；与所在目录名一致
description: 一句话说清本技能的价值（1-1024 字符），它是元数据级唯一的展示信息
license: MIT            # 可选：SPDX 标识
compatibility: crewai>=0.1.0   # 可选：版本/平台约束，最长 500 字符
metadata:               # 可选：自定义键值对
  author: your-name
  version: "1.0"        # 约定俗成的版本键
allowed-tools: web-search file-read   # 可选：空格分隔的预批准工具白名单
---

## Instructions

用简明指令说明本技能赋予 Agent 的职责与核心行为规范。

### Usage

1. 第一步：……
2. 第二步：……
3. 第三步：……

### Notes

补充影响 Agent 判断的边界条件与注意点。

将模板保存为 <技能名>/SKILL.md，并把可执行脚本放入 scripts/、长文档放入 references/、静态数据放入 assets/，即构成一个与 valid-skill 同等完整的技能包。若在正文第 6 小节展示的 prompt 注入需求之外还需要"始终只公开摘要"，则完全合法——minimal-skill 证明仅含两行必填字段的 SKILL.md 就能被正常发现与呈现。

八、如何验证：跑通仓库自带的技能测试

如果你希望在自己的环境中复现上述所有机制，可以直接运行 crewAI 仓库内与技能相关的测试套件（fixtures 目录 lib/crewai/tests/skills/fixtures/ 就是这些测试的输入）：

cd lib/crewai
uv run pytest tests/skills -q