9.2 编排型 Skill 的核心机制

面向经管学生、研究者与从业者的 AI 智能体设计教材

9.2 配图

一个能稳定工作的编排型 Skill，至少涉及四类元素：任务指令、边界约束、执行入口和支持资产。

第一类：SKILL.md 正文指令。 负责说明任务目标、推荐顺序、判断标准和交付方式。没有任务语义，后面的命令和脚本只是零散动作。

第二类：frontmatter 中的边界字段。 重点不在字段清单本身，而在于它们分别解决什么工程问题。

词条：allowed-tools

• 一句话定义：在 frontmatter 中指定 Skill 执行时可以使用哪些工具。
• 解决的问题：限制智能体的动作范围，防止越界操作。
• 典型例子：allowed-tools: "Read Glob Grep" 表示只允许读取文件，不允许写入或执行命令。

allowed-tools 支持精细的工具和参数过滤。完整语法如下：

allowed-tools: "Bash(python:*) Bash(npm:*) Read Write Glob WebFetch"

这行配置的含义：

写法	含义
Bash(python:*)	只允许执行以 python 开头的 Bash 命令
Bash(npm:*)	只允许执行以 npm 开头的 Bash 命令
Read	允许读取文件
Write	允许写入文件
Glob	允许文件模式匹配
WebFetch	允许网页抓取

未列出的工具一律禁止使用。如果不指定 allowed-tools，Skill 可以使用所有可用工具。

词条：!command

• 一句话定义：在 Skill 正文中用 ! 前缀标记的命令，系统在 Skill 加载时自动执行。
• 解决的问题：让 Skill 在执行前先获取环境事实（目录结构、文件状态等），而不是让模型凭空猜测。
• 典型例子：!ls chapters/chapter-7/ 在 Skill 加载时列出目录内容，供后续步骤参考。

第三类：执行入口。 最常见的是 !command 和本地脚本。它们承接先取证、再推理的结构：先跑命令拿到环境事实，再让模型基于事实做判断。

第四类：支持资产。 常见形式包括 references/、assets/、模板文件、样例输出、检查清单等。它们把高频依赖沉淀下来，避免每次都在正文里重新解释。

引用支持资产时，用明确的路径和用途说明：

执行前，参阅 references/api-patterns.md 了解：
- 接口调用频率限制
- 分页查询的标准写法
- 错误码与处理方式

这种写法让智能体按需加载文档，而不是一次性把所有材料塞进上下文。

下面是一个编排型 Skill 的完整示例：

▶ Skill

---
name: chapter-material-check
description: 当用户需要检查章节素材是否齐全、核对文件清单时使用。
allowed-tools: "Read Glob Grep"
---

!ls chapters/chapter-{N}/
!ls 参考资料及素材/chapter-{N}/

## 执行步骤

1. 读取上面的目录列表，确认已有文件与预期文件的差异。
2. 检查每个必需文件是否存在：outline、index.qmd、各 section 文件、summary.qmd。
3. 如有缺失，列出缺失文件清单和建议补充顺序。
4. 输出结构化核对报告，包括已有文件数、缺失文件数和下一步建议。

## 边界

- 只读取，不创建或修改任何文件。
- 只检查指定章节目录，不扫描其他章节。

这个示例展示了编排型 Skill 的关键特征：先通过 !command 获取真实环境信息，再用 allowed-tools 限制动作范围，最后按步骤组织推理过程。

四类元素合起来形成一个最小编排链路：

阶段	动作	负责角色
1. 接收任务	用户提出需求	用户
2. 匹配 Skill	系统根据 description 选择	系统
3. 取证	执行 !command 获取环境事实	命令/脚本
4. 受控处理	在 allowed-tools 范围内组织推理	模型 + Skill 规则
5. 交付结果	输出结构化结果并交回主流程	模型

安全注意事项

• 不要在 SKILL.md 中硬编码 API 密钥、密码或 token。密钥应通过环境变量传入。
• 安装第三方 Skill 前，先阅读其 SKILL.md 和脚本内容，确认没有恶意命令。
• allowed-tools 配置要遵循最小权限原则：只开放任务必需的工具。