SKILL.md

SKILL.md 采用两段式结构：顶部的 Frontmatter 用于声明 Skill 的元信息，下方的正文则承载具体的执行指令。二者各司其职——Frontmatter 决定 Skill 是否被加载，正文决定 Skill 执行得好不好。

一、Frontmatter：Skill 的元信息声明

Frontmatter 使用 YAML 语法，agentskills.io 定义了 6 个字段，其中两个必需、四个可选：

字段	必需	约束	作用
name	✅	1–64 字符，仅小写字母 / 数字 / 连字符	Skill 唯一标识，必须与父目录名一致
description	✅	1–1024 字符	触发条件描述，AI 据此判断何时加载
license	❌	许可证名或文件引用	说明本 Skill 的许可，如 Apache-2.0
compatibility	❌	1-500 字符	说明运行环境要求，如 Requires Python 3.14+
metadata	❌	字符串键值映射	任意附加信息，常用于 author / version
allowed-tools	❌（实验性）	空格分隔的工具名单	预授权调用的工具白名单

name 字段的硬约束

• 长度：1–64 字符
• 字符集：仅 a-z、0-9、-（kebab-case）
• 位置：不得以 - 开头或结尾，不得含连续 --
• 保留词：不能包含 claude 或 anthropic（防止 prompt injection）
• 一致性：必须与父目录名完全一致

name: pdf-form-filler        # ✅
name: PDF-Filler             # ❌ 大写
name: -pdf-filler            # ❌ 首连字符
name: pdf--filler            # ❌ 连续连字符
name: claude-helper          # ❌ 保留词

NOTE

什么是 kebab-case？ 全小写、单词以连字符 - 连接的命名风格，因形似烤串（kebab）而得名。例如 pdf-form-filler。与之相对的还有 camelCase（pdfFormFiller）、snake_case（pdf_form_filler）和 PascalCase（PdfFormFiller）。Anthropic 内部偏好 verb-ing + noun 形式，如 analyzing-marketing-campaign、generating-practice-questions。

description 字段的五大规则

description 是整个 Frontmatter 中最关键的字段，它直接决定 AI 在何种语境下加载本 Skill。它也是社区公认的「#1 坑」重灾区。请按以下五条规则书写：

#	规则	关键点
1	只说触发，不说过程	描述中讲了「怎么做」，agent 会以为不读正文也能完成，直接跳过加载 Level 2
2	第三人称 + 祈使句	Use when... / Processes...；不要 I can help... / You can use this...
3	包含触发关键词与典型用户表述	含领域术语、常用口语、可能的隐式表述
4	涵盖隐式触发	用户不直接点名领域时也能命中，如「老板发了个 xlsx 文件」
5	要「略带强势」（pushy）	agent 默认懒触发，描述不够明确就不动

三组好坏对比

# ❌ 太泛
name: pdf-helper
description: 帮助处理 PDF。
# 问题：没说干什么、什么时候用、用户会怎么说

# ❌ 讲了过程——导致不读正文
name: pdf-helper
description: >
  读取 PDF，使用 pypdf 提取文本，生成 markdown 报告。
  先检查加密 PDF，再提取表格。

# 问题：agent 以为你告诉他怎么做了，跳过加载 SKILL.md 正文

# ✅ 只说触发，含关键词与隐式场景
name: pdf-form-filler
description: >
  Use when the user needs to extract text or tables from PDF files,
  fill PDF forms, or merge multiple PDFs.
  Trigger phrases include "PDF", "表单", "报告提取", or when the user
  uploads a .pdf file even without naming the format.

IMPORTANT

完整的 description 设计与验证方法（包含 LLM 隔离测试与触发率评估）另见专项：写好 description。

allowed-tools 语法

以空格分隔的工具名，支持括号限定参数模式：

allowed-tools: Read Write Bash(git:*) Bash(jq:*)

上例允许调用 Read、Write、Bash 中仅以 git 或 jq 开头的命令。该字段仍为实验性，不同平台支持度不一。

完整 Frontmatter 示例

---
name: pdf-form-filler
description: >
  Use when the user needs to extract text or tables from PDF files,
  fill PDF forms, or merge multiple PDFs. Triggers on phrases such as
  "PDF", "表单", "报告提取", or whenever the user uploads a .pdf file.
license: Apache-2.0
compatibility: Requires Python 3.10+ and pypdf
metadata:
  author: example-org
  version: '1.0'
allowed-tools: Read Write Bash(python:*)
---

二、正文：Skill 的执行手册

正文采用 Markdown 编写。官方与社区达成共识的两条硬上限：

IMPORTANT

• 行数 < 500 行
• Token < 5,000

超出则请拆分、外包到 references/ 或 assets/，让 SKILL.md 仅保留「每次都需要」的核心指令。

推荐遵循以下五段式结构（适合入门）：

段落	作用
1. 概述	用一句话说明 Skill 的核心职责
2. 前置检查	在执行前验证运行环境与依赖条件
3. 执行步骤	以编号 SOP 的形式给出可逐步执行的操作流程
4. 示例	覆盖正常、边界与错误三类场景
5. 约束	明确声明「什么不做」，划定能力边界

进阶：六种可复用 Pattern

上面的五段式是「整体骨架」，Anthropic 官方 best-practices 另归纳了六种可叠加使用的「能力级 Pattern」，在执行步骤内部使用：

Pattern	适用场景	要点
Template	需要统一输出格式	提供占位符模板；短模板内嵌在 SKILL.md，长模板进 assets/
Examples	限定输入输出格式	覆盖「正常 / 边界 / 错误」三类具体例子
Conditional Workflow	多分支流程	用决策树取代长篇 prose，减少 agent 迟疑
Script Automation	需确定性计算 / 多步命令	封装为 scripts/ 下的 CLI 小脚本，跳过提示词推理
Read-Process-Write	文件转换 / 数据清洗	读 → 转换 → 写三步，最适合 LLM 处理的模式
Gotchas section	领域限定的反直觉坑	集中列举「agent 不被告知就会犯错」的事实

三、完整示例

将 Frontmatter 与正文组合后，一个完整的 SKILL.md 示例如下：

---
name: create-npc-skill
description: >
  根据用户的自然语言描述，一键生成最小可用的 CNB NPC Agent 项目。
  零代码架构，仅需配置文件（Dockerfile + .cnb.yml + .cnb/settings.yml）即可部署。
  当用户要求「创建一个新的 NPC」、「搭建 NPC 项目」、「做一个 CNB 平台的 AI Agent」时触发。
allowed-tools: Read, Write, Bash
---

# Create NPC Skill

一键创建最小可用的 CNB NPC Agent 项目。零代码架构，纯配置驱动。

> 详细架构说明见 `references/npc-architecture.md`

## 工作流程

### 第 1 步：需求分析

从用户输入中提取：

|信息项|说明|默认值 / 示例|
|-|-|-|
|**项目名称**|kebab-case，用作仓库名|`my-npc`|
|**NPC 角色名**|中文名，用于 settings.yml|`小助手`|
|**NPC 人设描述**|角色定位和行为描述|`专业的代码审查员，擅长...`|
|**NPC 标语**|一句话功能描述（可选）|`让开发更轻松`|
|**按钮配置**|Issue 界面上的按钮名称和描述|名称: "召唤 NPC"|
|**触发方式**|Issue / PR / 两者|默认两者都触发|

信息不完整时，做出合理推断并说明。

### 第 2 步：生成项目骨架

**全新项目**时，直接运行 scaffold 脚本：

```bash
bash "${SKILL_DIR}/scripts/scaffold.sh" \
  --name "my-npc" \
  --dir "/path/to/target"
```

**已有项目**（目标目录已有 `.cnb.yml` 等文件）时，不要运行 scaffold 脚本，改为手动处理：

- **`.cnb.yml` 已存在**：读取现有内容，仅追加 NPC 配置（`.npc_task` 锚点 + `$` 触发事件），保留原有流水线不动。如果已有 `npc:go` 则跳过。如果缺少 Docker 构建步骤，需要补充。
- **`Dockerfile` 已存在**：读取现有内容，在末尾追加 NPC 所需依赖（cnb-cli、skills、cnb-skill），不覆盖已有内容。
- **`.cnb/settings.yml` 已存在**：读取后合并 NPC 角色配置，不覆盖已有角色。
- **不存在的文件**：参考 `templates/` 目录下的模板创建。

### 第 3 步：定制化

用用户信息替换模板占位符：

- **`.cnb/settings.yml`**：编写角色 prompt（定位、行为风格、安全约束）
- **`.cnb.yml`**：按需调整 `$` 部分的事件绑定
- **`Dockerfile`**：仅在用户有额外需求时扩展

### 第 4 步：交付

向用户汇报：

1. ✅ 创建/修改的文件列表及作用
2. 📝 NPC 角色概述（名称、人设、触发方式）
3. 🚀 下一步操作提示

## 注意事项

1. **零代码优先** — 不写自定义代码，能力通过 Skills 提供
2. **按需安装** — 初始化只含基础依赖，不要预装不需要的东西
3. **安全红线** — prompt 中必须包含敏感信息保护规则
4. **头像可选** — 用户提供头像时，取消 settings.yml 中 avatar 注释

下一步

读完结构与字段，快速编写一个 Skill 提供了三步法实操路径，5 分钟内就能拿出第一个可用版本。