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）
• 位置：不得以 - 开头或结尾，不得含连续 --
• 一致性：必须与父目录名完全一致

name: pdf-form-filler        # ✅
name: PDF-Filler             # ❌ 大写
name: -pdf-filler            # ❌ 首连字符
name: pdf--filler            # ❌ 连续连字符

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。

TIP

部分平台还会额外禁止 claude、anthropic 等保留词，或禁止 XML 标签。为了跨平台稳妥，命名与描述中应避免这些平台敏感词和 <tag> 形式。

description 字段的五大规则

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

#	规则	关键点
1	说明能力与触发，不写过程	可以写「做什么 / 何时用」，不要写具体步骤、依赖、实现细节
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:*)
---

平台特有扩展

跨平台 spec 之外，部分 Agent 平台增加了额外字段或 sidecar 文件来表达 spec 没覆盖的能力。这些扩展在其他平台上会被静默忽略——所以它们不是"非加不可"，但在目标平台上确实有用。

Claude Code：SKILL.md frontmatter 扩展

字段	作用
disable-model-invocation: true	禁止模型隐式触发，只允许用户手动调起
user-invocable: false	禁止用户手动调起（与 disable-model-invocation 配合可锁死调起方式）

Codex：agents/openai.yaml sidecar 文件

Codex 不把扩展字段塞进 SKILL.md frontmatter，而是在 skill 目录下放一个独立的 agents/openai.yaml：

# my-skill/agents/openai.yaml
interface:
  display_name: 'PDF 表单填写器'
  short_description: '处理 PDF 文件抽取、表单填写、合并'
  icon_small: './assets/small-logo.svg'
  icon_large: './assets/large-logo.png'
  brand_color: '#3B82F6'
  default_prompt: 'Optional prompt prefix when invoked'

policy:
  allow_implicit_invocation: false # 默认 true；false 时只能 $skill 显式触发

dependencies:
  tools:
    - type: 'mcp'
      value: 'openaiDeveloperDocs'
      transport: 'streamable_http'
      url: '...'

字段	对应能力
interface.*	Codex App 里的 UI 元数据（名称、图标、品牌色）
policy.allow_implicit_invocation	等价于 Claude Code 的 disable-model-invocation，作用相反值
dependencies.tools	声明该 skill 依赖的 MCP 工具，便于一键安装

WARNING

跨平台 Skill 想"禁止隐式触发"必须同时设两边的字段——详见反模式 #11。

触发方式：隐式 vs 显式

主流平台都支持两种调起方式：

方式	Claude Code	Codex
隐式触发	description 命中时自动加载	description 命中时自动加载
显式触发	/skill <name> 斜杠命令	$<name> 前缀，或 /skills 列表选择

例如在 Codex 里直接输入 $pdf-form-filler 帮我处理这份合同，会强制激活 pdf-form-filler 这个 Skill，绕过描述匹配——适合「明知道想用某个 Skill，但描述命中率不够稳」的场景。

二、正文：Skill 的执行手册

正文采用 Markdown 编写。它承载触发后的 SOP、示例、边界与输出约束。官方与社区达成共识的两条硬上限：

IMPORTANT

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

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

正文的五段式骨架、六种可复用 Pattern 与拆分规则，详见独立参考页：正文模式。

三、完整示例

将 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 分钟内就能拿出第一个可用版本。