# Skill Creator

> 创建、编辑、改进或审查 AgentSkills。适用于从零创建新 skill，或改进、审查、审计、整理现有 skill 或 SKILL.md 文件；也适用于调整 skill 目录结构（例如把文件移动到 references/ 或 scripts/、删除过时内容、按 AgentSkills 规范校验）。当用户表达“创建一个 skill”“编写 skill”“整理 skill”“改进这个 skill”“审查 skill”“清理 skill”“审计 skill”等意图时触发。

- Skill: `zxbdzh/skill-creator` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add zxbdzh/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zxbdzh/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zxbdzh (https://skillmd.com/u/zxbdzh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zxbdzh/skill-creator

---


# 技能创建器

本技能用于指导如何创建高质量技能。

## 关于技能

技能是模块化、可自包含的包，它通过提供专门知识、工作流和工具来扩展 agent 的能力。可以把它理解成特定领域或任务的“上手指南”。

它能把 agent 从通用代理，转变为拥有程序性知识的专用代理，而这些知识并不是任何模型都能完整掌握的。

### 技能提供什么

1. 专门工作流 - 面向特定领域的多步骤流程
2. 工具集成 - 针对特定文件格式或 API 的操作说明
3. 领域知识 - 公司特有知识、模式定义、业务逻辑
4. 打包资源 - 用于复杂和重复任务的脚本、参考资料与素材

## 核心原则

### 简洁优先

上下文窗口是公共资源。技能需要与 agent 还要使用的其他内容共享上下文窗口，包括系统提示、对话历史、其他技能的元数据以及用户的真实请求。

**默认前提：agent 已经足够聪明。** 只补充 agent 原本不知道的上下文。对每一段信息都要追问：“agent 真的需要这段解释吗？”以及“这段话是否值得它消耗的 token 成本？”

优先使用简洁示例，而不是冗长说明。

### 设定合适的自由度

技能说明的具体程度，应与任务的脆弱性和变化性相匹配：

**高自由度（文本说明）**：适用于存在多种可行方案、需要结合上下文决策、或主要依赖启发式方法的场景。

**中等自由度（伪代码或带参数脚本）**：适用于已有推荐模式、允许一定变化、或行为会受配置影响的场景。

**低自由度（固定脚本、少量参数）**：适用于操作脆弱且容易出错、必须保持一致性、或必须严格遵循特定顺序的场景。

可以把 agent 想象成在探索一条路径：如果是两侧都是悬崖的窄桥，就需要清晰护栏（低自由度）；如果是开阔平地，就允许多种路线（高自由度）。

### 技能的结构

每个技能都由一个必需的 `SKILL.md` 文件，以及可选的打包资源组成：

```text
skill-name/
├── SKILL.md（必需）
│   ├── YAML frontmatter 元数据（必需）
│   │   ├── name:（必需）
│   │   └── description:（必需）
│   └── Markdown 说明（必需）
└── 打包资源（可选）
    ├── scripts/          - 可执行代码（Python/Bash 等）
    ├── references/       - 按需加载进上下文的文档
    └── assets/           - 输出时会用到的文件（模板、图标、字体等）
```

#### `SKILL.md`（必需）

每个 `SKILL.md` 由以下两部分组成：

- **Frontmatter**（YAML）：包含 `name` 和 `description` 字段。agent 只会读取这两个字段来判断技能何时触发，因此必须清晰且完整地描述这个技能是什么，以及应在什么场景下使用。
- **正文**（Markdown）：技能触发后才会加载的使用说明与指导。

#### 打包资源（可选）

##### 脚本（`scripts/`）

用于执行需要确定性可靠性、或经常被重复改写任务的可执行代码（Python/Bash 等）。

- **适用时机**：同一段代码会被反复重写，或任务需要确定性可靠性
- **示例**：用于 PDF 旋转的 `scripts/rotate_pdf.py`
- **优势**：节省 token、行为确定，而且可以在不加载进上下文的情况下直接执行
- **注意**：agent 仍可能需要读取脚本内容，以便打补丁或适配具体环境

##### 参考资料（`references/`）

按需加载到上下文中的文档和参考材料，用于帮助 agent 完成推理和执行。

- **适用时机**：存在 agent 在工作过程中应查阅的文档
- **示例**：`references/finance.md`（财务模式说明）、`references/mnda.md`（公司 NDA 模板）、`references/policies.md`（公司政策）、`references/api_docs.md`（API 规范）
- **用途**：数据库模式、API 文档、领域知识、公司政策、详细工作流指南
- **优势**：让 `SKILL.md` 保持精简，只在 agent 判断有需要时才加载
- **最佳实践**：如果文件很大（超过 10k 词），请在 `SKILL.md` 中提供 grep 搜索模式
- **避免重复**：同一信息应只存在于 `SKILL.md` 或 `references` 文件之一，不要两边重复。除非信息确实是技能的核心内容，否则优先放在 `references` 中，这样既能保持 `SKILL.md` 精简，也能在不占满上下文窗口的前提下让信息可发现。`SKILL.md` 只保留必要的流程说明和工作流指导；详细参考材料、模式定义和示例应移动到参考文件。

##### 资源文件（`assets/`）

这类文件不是用来加载进上下文的，而是让 agent 在生成最终输出时直接使用。

- **适用时机**：技能需要在最终产出中使用某些文件
- **示例**：`assets/logo.png`（品牌资源）、`assets/slides.pptx`（PowerPoint 模板）、`assets/frontend-template/`（HTML/React 样板）、`assets/font.ttf`（字体）
- **用途**：模板、图片、图标、样板代码、字体、可复制或可修改的示例文档
- **优势**：将输出资源与说明文档分离，让 agent 可以使用这些文件而无需把它们加载进上下文

#### 不要在技能里放什么

技能应只包含直接支撑其功能的必要文件。不要创建多余文档或辅助文件，包括但不限于：

- `README.md`
- `INSTALLATION_GUIDE.md`
- `QUICK_REFERENCE.md`
- `CHANGELOG.md`
- 等等

技能应只保留 AI 代理完成任务所需的信息。不应包含技能制作过程说明、安装与测试步骤、面向用户的额外文档等辅助背景。额外文档只会增加杂乱度并造成理解负担。

### 渐进式披露设计原则

技能通过三级加载系统来高效管理上下文：

1. **元数据（name + description）** - 始终在上下文中（约 100 词）
2. **`SKILL.md` 正文** - 技能触发时加载（少于 5k 词）
3. **打包资源** - 按需由 agent 加载（理论上不限，因为脚本可以不读入上下文而直接执行）

#### 渐进式披露模式

应让 `SKILL.md` 只保留必要内容，并控制在 500 行以内，避免上下文膨胀。接近这个限制时，应把内容拆到其他文件中。拆分后一定要在 `SKILL.md` 里明确引用这些文件，并说明何时应读取它们，这样技能的使用者才能知道这些资源存在且知道何时使用。

**关键原则：** 如果一个技能支持多种变体、框架或选项，那么 `SKILL.md` 里只保留核心工作流和选择指导；变体相关的细节（模式、示例、配置）应放到独立参考文件中。

**模式 1：带参考资料的高层指南**

```markdown
# PDF 处理

## 快速开始

使用 pdfplumber 提取文本：
[代码示例]

## 高级功能

- **表单填写**：完整指南见 [FORMS.md](FORMS.md)
- **API 参考**：完整方法列表见 [REFERENCE.md](REFERENCE.md)
- **示例**：常见模式见 [EXAMPLES.md](EXAMPLES.md)
```

只有在需要时，agent 才会去加载 `FORMS.md`、`REFERENCE.md` 或 `EXAMPLES.md`。

**模式 2：按领域组织**

当一个技能覆盖多个领域时，应按领域组织内容，以免加载无关上下文：

```text
bigquery-skill/
├── SKILL.md（总览和导航）
└── reference/
    ├── finance.md（收入、计费指标）
    ├── sales.md（机会、销售漏斗）
    ├── product.md（API 用法、功能）
    └── marketing.md（活动、归因）
```

当用户询问销售指标时，agent 只需读取 `sales.md`。

同样地，如果技能支持多个框架或变体，也应按变体组织：

```text
cloud-deploy/
├── SKILL.md（工作流 + 提供商选择）
└── references/
    ├── aws.md（AWS 部署模式）
    ├── gcp.md（GCP 部署模式）
    └── azure.md（Azure 部署模式）
```

当用户选择 AWS 时，agent 只需读取 `aws.md`。

**模式 3：条件化细节**

先展示基础内容，再链接高级内容：

```markdown
# DOCX 处理

## 创建文档

新建文档时使用 docx-js。参见 [DOCX-JS.md](DOCX-JS.md)。

## 编辑文档

简单编辑可直接修改 XML。

**如需修订模式**：参见 [REDLINING.md](REDLINING.md)
**如需 OOXML 细节**：参见 [OOXML.md](OOXML.md)
```

只有当用户真的需要这些能力时，agent 才去读取 `REDLINING.md` 或 `OOXML.md`。

**重要指导：**

- **避免层层嵌套引用** - 让引用文件与 `SKILL.md` 保持一层关系，所有参考文件都应直接从 `SKILL.md` 链接到
- **为较长参考文件补目录** - 对超过 100 行的文件，在顶部加目录，方便 agent 预览时迅速理解内容范围

## 技能创建流程

创建技能通常包含以下步骤：

1. 通过具体示例理解技能
2. 规划可复用的技能内容（脚本、参考资料、素材）
3. 初始化技能（运行 `init_skill.py`）
4. 编辑技能（实现资源并编写 `SKILL.md`）
5. 打包技能（运行 `package_skill.py`）
6. 基于真实使用情况迭代

应按顺序执行这些步骤，除非有明确理由说明某一步不适用。

### 技能命名

- 只使用小写字母、数字和连字符；将用户给出的标题规范化为连字符格式，例如 `Plan Mode` -> `plan-mode`
- 生成的技能名长度应小于 64 个字符（仅计字母、数字和连字符）
- 优先使用简短、动词导向、能描述动作的短语
- 当按工具命名空间能提高清晰度或触发效果时，可按工具命名，例如 `gh-address-comments`、`linear-address-issue`
- 技能目录名必须与技能名完全一致

### 第 1 步：通过具体示例理解技能

只有当技能的使用模式已经非常清晰时，才可以跳过此步骤。即便你是在修改已有技能，这一步通常依然有价值。

要创建高质量技能，必须清楚了解技能会如何被实际使用。这种理解可以来自用户直接给出的示例，也可以来自你生成后再由用户确认的示例。

例如，在构建图像编辑技能时，可以问：

- “这个 image-editor skill 需要支持哪些功能？编辑、旋转，还有别的吗？”
- “你能举几个它的使用例子吗？”
- “我能想到一些用户请求，比如‘帮我去掉这张图的红眼’或‘把这张图旋转一下’，还有别的常见说法吗？”
- “用户会说什么来触发这个技能？”

为避免一次性提太多问题而压垮用户，应先问最重要的问题，再按需要继续追问。

当你已经清楚技能应支持哪些功能时，这一步就可以结束。

### 第 2 步：规划可复用的技能内容

要把具体示例转化为高质量技能，请针对每个示例做以下分析：

1. 思考如果从零开始，应该如何完成这个示例
2. 找出在重复执行这些工作流时，哪些脚本、参考资料和素材会有帮助

例如：构建一个 `pdf-editor` 技能来处理“帮我旋转这个 PDF”这类请求时，分析结果可能是：

1. 旋转 PDF 需要每次都重写同样的代码
2. 把这段逻辑沉淀成 `scripts/rotate_pdf.py` 会更有帮助

例如：设计一个 `frontend-webapp-builder` 技能来处理“帮我做一个待办应用”或“帮我做一个记录步数的仪表盘”时，分析结果可能是：

1. 构建前端应用每次都需要重复写 HTML/React 样板
2. 在 `assets/hello-world/` 中保存一套样板工程会更有帮助

例如：构建一个 `big-query` 技能来处理“今天有多少用户登录过？”这类请求时，分析结果可能是：

1. 每次查询 BigQuery 都要重新摸清表结构和关系
2. 在 `references/schema.md` 中记录这些表结构会更有帮助

要确定技能内容，应对每个具体示例做分析，并整理出应纳入技能的可复用资源清单：脚本、参考资料和素材。

### 第 3 步：初始化技能

到这里，就该真正开始创建技能了。

只有在你要开发的技能已经存在，而且当前只是要迭代或打包时，才跳过这一步；此时直接进入下一步即可。

当你从零创建一个新技能时，始终要运行 `init_skill.py`。这个脚本会自动生成一个模板技能目录，把技能必需的基础结构一次性搭好，从而让创建过程更高效、更可靠。

用法：

```bash
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" init <skill-name> [--path <dir>] [--resources scripts,references,assets] [--examples]
```

`--path` 默认使用当前工作目录（`WORKSPACE_DIR`），新创建的 skill 写入 workspace，当前会话立即可用。

示例：

```bash
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" init my-skill
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" init my-skill --resources scripts,references
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" init my-skill --path /custom/location --resources scripts --examples
```

这个脚本会：

- 在指定路径创建技能目录
- 生成带有正确 frontmatter 和 TODO 占位内容的 `SKILL.md` 模板
- 根据 `--resources` 可选地创建资源目录
- 在设置了 `--examples` 时可选地生成示例文件

初始化完成后，请按需完善 `SKILL.md` 并补充资源。如果你使用了 `--examples`，应把占位文件替换成真实内容，或删除它们。

### 第 4 步：编辑技能

无论你编辑的是新生成的技能还是已有技能，都要记住：这个技能是给另一个 agent 实例使用的。应包含那些对 agent 有帮助、且并非显而易见的信息。思考哪些程序性知识、领域细节或可复用资源，能帮助另一个 agent 实例更有效地完成这些任务。

#### 学习已验证的设计模式

根据技能的需要，查阅以下有帮助的指南：

- **多步骤流程**：参见(如果有) `references/workflows.md`，了解顺序工作流与条件逻辑的组织方式
- **特定输出格式或质量标准**：参见(如果有) `references/output-patterns.md`，了解模板和示例模式

这些文件总结了构建高质量技能的成熟最佳实践。

#### 从可复用内容开始

开始实现时，应先落地前面识别出的可复用资源：`scripts/`、`references/` 和 `assets/`。注意，这一步可能需要用户输入。例如，在实现 `brand-guidelines` 技能时，用户可能需要提供品牌素材或模板放入 `assets/`，或提供文档放入 `references/`。

新增脚本后，必须通过实际运行来测试，确认没有 bug，且输出符合预期。如果存在很多相似脚本，可以只测试具有代表性的一部分，以在完成时间和可靠性之间取得平衡。

如果你使用了 `--examples`，请删除技能不需要的占位文件。只创建真正需要的资源目录。

#### 更新 `SKILL.md`

**写作原则：** 始终使用祈使式 / 不定式风格。

##### Frontmatter

使用 YAML frontmatter 编写 `name` 和 `description`：

- `name`：技能名称
- `description`：这是技能最主要的触发机制，用来帮助 agent 理解何时应使用该技能
  - 既要说明技能做什么，也要说明具体的触发场景 / 上下文
  - 所有“何时使用”的信息都应写在这里，而不是正文里。正文只有在技能触发后才会加载，所以正文中的“何时使用本技能”章节对 agent 没有帮助
  - `docx` 技能的描述示例：“全面支持文档创建、编辑和分析，支持修订、评论、格式保留与文本提取。适用于 agent 需要处理专业文档（`.docx` 文件）时，包括：(1) 创建新文档，(2) 修改或编辑内容，(3) 处理修订模式，(4) 添加评论，或其他文档相关任务”

不要在 YAML frontmatter 中加入其他字段。

##### 正文

在正文中编写技能使用说明，以及如何使用它附带的资源。

### 第 5 步：打包技能

技能开发完成后，必须把它打包成可分发的 `.skill` 文件，供用户共享或分发。打包流程会先自动校验技能是否满足要求：

```bash
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" package <path/to/skill-folder>
```

也可以指定输出目录：

```bash
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" package <path/to/skill-folder> --output ./dist
```

打包脚本会：

1. **自动校验** 技能，包括：
   - YAML frontmatter 格式与必填字段
   - 技能命名规范与目录结构
   - 描述的完整性与质量
   - 文件组织与资源引用

2. **在校验通过后打包**，生成以技能名命名的 `.skill` 文件（例如 `my-skill.skill`），其中包含技能的全部文件，并保留正确的目录结构以便分发。`.skill` 文件本质上是扩展名为 `.skill` 的 zip 文件。

   安全限制：打包时不会跟随符号链接；检测到符号链接会跳过该项，避免把技能目录外的内容错误打进包里。

如果校验失败，脚本会报告错误并直接退出，不会生成打包文件。修复校验问题后，再次运行打包命令即可。

#### 安装技能

打包校验通过后，默认调用 `skill(action="install", path="...")` 将技能安装到系统中，使其立即可用。无需询问用户。`install` 会自动做安全审查，不必先调用 `inspect`。

若用户提供新技能并要求更新已有技能：先 `skill(action="inspect", path="新技能目录")` 审查这份新技能（不要审查旧技能）。审查不通过（CAUTION / DO_NOT_INSTALL）则向用户说明风险，先不更新原技能；审查通过后再把新内容写入原技能目录。

自行改写已安装技能目录、且不会再走 `install` 时：改完后对该目录调用 `inspect`。审查不通过则向用户说明，先不视为更新完成。

若用户只要风险报告、不安装也不更新，再使用 `skill(action="inspect", path="...")`。

**例外情况**：当用户明确提及技能用于分发、发送给他人、存放到指定位置等非自用目的时，跳过安装步骤，仅保留打包文件供后续处理。

### 第 6 步：迭代

在技能经过真实使用后，用户可能会提出改进需求，而且往往会在刚用完技能、仍保留鲜活上下文时提出。

**迭代工作流：**

1. 在真实任务中使用该技能
2. 观察它在哪些地方吃力或低效
3. 判断应如何更新 `SKILL.md` 或打包资源
4. 实施修改并重新测试。若改的是已安装技能目录（不走 install），改完后 `skill(action="inspect", path="该技能目录")`；审查不通过则向用户说明，先不视为更新完成。