Skill 开发综合指南

Overview

Skill 是被 Agent 调用的可复用执行能力。本文综合 Anthropic 官方最佳实践、agentskills.io 开放规范、OpenClaw Skill 写作/创建指南和实战经验，提炼出 Skill 开发的核心框架。

为什么重要

Skill 是 Agent 时代的”可复用最小单元”——一份写得好的 SKILL.md 让多个 Agent 共享同一套执行流程、质量标准与边界，而不是每个 Agent 各自硬编码。掌握 Skill 开发框架，是从”调几个 prompt”升级为”搭一个系统”的关键分水岭。本指南把 Anthropic 官方规范、agentskills.io 开放标准、OpenClaw 实战经验整合成一份可落地的写作 + 评审 + 发布全流程。

定位

一句话：Skill = 通用执行流程 + 质量标准 + 边界。IO 由 Agent 定义。

关键属性：

• 不直接面对用户，由 Agent 通过 read skills/xxx/SKILL.md 加载
• 可跨 Agent 复用
• 不定义固定文件输入/输出——IO 契约由 Agent 声明
• 与其他 Skill 不直接通信，通过文件系统协同

标准文件结构

skills/your-skill/
├── SKILL.md              [*] 核心 — <500 行
├── scripts/              可选 — 可执行脚本
├── references/           可选 — 详细文档/模板
└── assets/               可选 — 静态资源

目录名必须与 frontmatter name 字段完全一致。

两条顶层铁律

1. 简洁是关键 — SKILL.md < 500 行，单段不超过 10 行
2. 泛化的度是关键 — 通用在机制，具体在配置

泛化判定

维度	问自己	合格标准
业务中立	换个业务系统还能用吗？	不写死业务名词，用 {domain}/{entity} 占位
配置驱动	改变行为要改源码吗？	关键参数从配置文件读
场景闭合	只做一件事还是”顺便”做了 3 件？	一个 Skill 一类问题

口诀：通用在机制，具体在配置。Skill 本身提供执行框架，具体参数从配置文件和用户输入注入。

Frontmatter 规范

必填字段

---
name: your-skill          # 必须与文件夹同名，≤64 字符，仅小写+数字+连字符
description: |            # ≤1024 字符，第三人称
  Does X, Y, and Z.
  Use when {场景描述}.
---

name 命名规范

推荐：动名词 (-ing) 或动宾结构 — processing-pdfs、analyzing-spreadsheets

避免：模糊通用词 (helper/utils/tools)、禁用保留词 (anthropic/claude)

description 写法三要素

1. 动作关键词：做什么（analyze / generate / extract）
2. 触发关键词：用户可能说什么（含同义词覆盖）— 如用户可能说”设计知识库 / 初始化知识 / 知识架构”
3. 第三人称陈述：绝不能写 “I” / “you”

好案例（Anthropic 官方）：

name: managing-databases
description: |
  Runs SQL queries, manages database migrations, and inspects schemas
  for PostgreSQL and MySQL. Use when the user mentions SQL, databases,
  migrations, schemas, or specific DB products like Postgres.

亮点：覆盖品牌名 + 通用词 + 操作词三类触发。

坏案例：description: Helps with documents. — 太模糊，无触发词

可选 Frontmatter 字段

字段	默认值	用途
user-invocable	true	是否暴露为用户斜杠命令
disable-model-invocation	false	不注入 system prompt（仍可 /skill 调用）
command-dispatch	—	设为 tool 直接路由到工具
command-tool	—	command-dispatch: tool 时调用的工具
command-arg-mode	raw	参数传递模式
homepage	—	macOS Skills UI 中的 Website URL

条件激活（Gating）

Skill 可设门控，仅当依赖满足时加载：

门控选项	条件
requires.bins	所有列出的二进制必须存在于 PATH
requires.anyBins	至少一个二进制在 PATH
requires.env	每个指定环境变量必须存在
requires.config	openclaw.json 路径求值为真
os	平台过滤：["darwin"]/["linux"]/["win32"]
always	true 跳过所有门控

API keys 可通过 openclaw.json 的 skills.entries 绑定到特定 Skill，仅在对应 agent turn 注入。

渐进式披露（三层）

层级	内容	体量	加载时机
Metadata	name + description	~100 tokens	Agent 启动时预加载
Instructions	SKILL.md body	< 5000 tokens	Skill 被激活时
Resources	references/scripts/assets	按需	Claude 实际需要时

文件引用保持一层深度，避免 SKILL.md → a.md → b.md → c.md 链式引用。

官方案例：PDF Skill 三层组织

pdf/
├── SKILL.md          # 第 2 层：高层指引 + 决策分支，<500 行
├── FORMS.md          # 第 3 层：按需加载 - 填表专题
├── reference.md      # 第 3 层：按需加载 - API 参考
├── examples.md       # 第 3 层：按需加载 - 示例代码
└── scripts/          # 第 3 层：可执行脚本，不占 token

如果全部塞进 SKILL.md → 激活一次烧掉 2 万 tokens。拆开后只读到需要的那一份，脚本走执行层而非上下文层。

推荐 Skill 大小

复杂度	行数	示例
轻量查询型	150~300 行	kb-context
标准执行型	400~700 行	req-clarify、kb-collect
复杂协调型	800~1500 行	kb-architect、kb-compile
超过 1500 行	拆分	拆成多个子 Skill + 主 Skill 编排

工作流与反馈循环

复杂任务用工作流

把多步操作拆成顺序步骤，给 Claude 一个可复制的 checklist，让它边做边勾选。

“Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses.” — Anthropic

模式 1：纯文本流程（适合分析/综合/评审类任务）

Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations

模式 2：脚本工作流（适合数据处理/文件构建等机械化任务）

Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)

为什么 checklist 有效：Claude 复制到回复中后每完成一步就勾掉 → 可见的进度追踪；防止跳过关键步骤（特别是 validation）；对话中断时未勾选项即为断点。

反馈循环

通用三步：执行 → 验证 → 修复 → 再验证（直到通过）。

“Run validator → fix errors → repeat. This pattern greatly improves output quality.” — Anthropic

模式 1：纯文档校验 — 用参考文档作为 validator

1. Draft content following STYLE_GUIDE.md
2. Review against checklist (terminology / examples / required sections)
3. Issues found → note + revise → review again
4. Only proceed when all requirements met

模式 2：脚本校验 — 适合结构化可机器校验的产物

1. Make edits to word/document.xml
2. Validate: python ooxml/scripts/validate.py unpacked_dir/
3. If fails → fix → validate again
4. Only proceed when validation passes
5. Rebuild: python ooxml/scripts/pack.py unpacked_dir/ output.docx

为什么反馈循环有效：错误越早发现成本越低；从 revise → re-check 形成自闭合，不会死循环；配合 checklist 使用，验证步骤本身就是其中一项。

子 Skill 调用

大 Skill 可根据条件调用子 Skill：

在 Step 3 中，根据条件选择子 Skill：
- 目标文档不存在 → read skills/extracting-business-knowledge/SKILL.md
- 目标文档已存在 → read skills/updating-business-knowledge/SKILL.md

子 Skill 本身是独立 SKILL.md，只是不直接被 Agent 加载，而是被主 Skill 加载。

写作语气三原则

1. 祈使句 > 被动句 — “验证输入参数” > “输入应该被验证”
2. 关键约束附理由 — Claude 理解”为什么”后更不容易绕过约束
3. 正反例驱动 — 每条规则给 [NO]/[OK] 对比 + 推理说明

技能分类

分类	描述	示例
general	通用技能	任务规划、问题解决
development	软件开发	代码审查、重构、调试
data	数据处理与分析	数据清洗、可视化、SQL
automation	任务自动化	工作流自动化、脚本编写
communication	沟通协作	邮件编写、文档
security	安全与隐私	安全审计、漏洞扫描
devops	DevOps 与基础设施	部署、监控、CI/CD
testing	测试与质量保证	单元测试、集成测试
documentation	文档与写作	API 文档、用户指南

Skill 测试

1. 安装到测试实例
2. 用真实任务测试
3. 验证代理理解：是否遵循指令？是否应用最佳实践？输出与示例是否一致？边缘情况处理如何？
4. 基于结果迭代
5. 记录限制（能力边界声明）

Skill 验证清单

写完后逐条对照。命中任意一行 → 必须修。

反模式	问题	正解
Windows 反斜杠路径	跨平台失败	统一正斜杠 scripts/helper.py
提供 5 种并列方案	Claude 选择困难	1 个默认 + 1 个逃生出口
时间敏感信息	过期即误导	只写当前正确做法；废弃内容用 <details> 折叠
术语混用	LLM 把不同词当不同概念	一个概念只用一个词，全文不切换
跨 Skill 术语不统一	跨 Skill 引用失效	同一概念全项目用同一个词
深层嵌套引用	Claude 可能只读前 100 行	引用只准一层，>100 行参考文件顶部加 TOC
脚本不处理错误	脚本应自包含	脚本自己 catch + 给明确错误提示
魔法常量无注释	连作者都不记得	常量必有注释说明来源
假设工具已装	环境不一致导致失败	明确写出 pip install xxx
MCP 工具不带前缀	Agent 找不到工具	必须 ServerName:tool_name
Description 第一/第二人称	注入 system prompt 后语义错乱	必须第三人称
产出路径用绝对路径	换用户目录就崩	全部相对项目根目录
Step 之间嵌套太深	LLM 读完忘了	扁平化、编号、用表格
不画流程图	LLM 靠文字理解容易出错	DOT 流程图 + 文字步骤双份
被动语态写指令	LLM 当成建议而非命令	祈使句：“验证输入参数”
约束只写规则不写原因	LLM 在边缘情况下自作主张绕过	每条关键约束后附 原因：xxx
只列文字规则不给正反例	LLM 理解偏差大	每条规则配 [NO]/[OK] 对比示例
不声明环境依赖	换机器 Skill 静默失败	SKILL.md 开头列出所需 OS、二进制、配置项
不声明能力边界	Agent 误触发	末尾加 ## Limitations
Skill 拼接用户输入到 exec	prompt 注入导致任意命令执行	用户输入必须过滤/转义

Skill 模板

新建 Skill 时复制此模板，按注释填写：

---
name: your-skill-name
description: |
  Does X, Y, and Z.
  Use when the user mentions "关键词A" / "关键词B",
  or when any task requires {场景描述}.
---

# your-skill-name — 中文名称

一句话描述做什么。

> [!] 路径基点：本 Skill 中所有路径均相对于项目根目录。

## Purpose

解决什么问题 / 何时使用 / 预期产出。

## Prerequisites

- 必读文件：`workspace/{project_id}/wiki/README.md`
- 环境依赖（如有）：`python 3.10+`、`pip install xxx`
- 上游 Skill（如有）：`kb-collect` 已完成数据采集

## Instructions

用 DOT 流程图给出全局骨架：

```dot
digraph skill_flow {
    rankdir=TB;
    node [shape=box];
    step0 [label="0. 加载配置"];
    step1 [label="1. {步骤名}"];
    step2 [label="2. {步骤名}"];
    output [label="3. 输出产物"];
    step0 -> step1 -> step2 -> output;
}
```

### Step 0: 环境探测（静默）

读取前置依赖文件，确认配置就绪。

### Step 1: {步骤名}

**做什么**：{祈使句描述}
**读什么**：`workspace/xxx`

## Examples

### 典型场景

**用户说**："{触发话术}"
**Skill 做**：{简述执行路径和产出}

### 边界场景

**用户说**："{边界输入}"
**Skill 做**：{如何优雅处理}

## Best Practices

- {关键约束} — 原因：{为什么}

## Common Mistakes

| 反模式 | 问题 | 正解 |
|:---|:---|:---|
| {反模式} | {后果} | {正确做法} |

## Permissions

| 项目 | 内容 |
|:---|:---|
| 可写 | `workspace/{你的工作区}/` |
| 禁止 | {明确列出不可写的目录} |

## Limitations

- 本 Skill 仅适用于 {场景范围}
- 不处理 {超出范围的情况}
- 最适输入规模：{例如 ≤50 个文件}

模板章节说明

章节	必填	来源	说明
Frontmatter	✅	Anthropic + agentskills.io	触发入口
Purpose	✅	OpenClaw skill-writing-guide	解决什么问题
Prerequisites	✅	OpenClaw creating-skills	环境/文件/上游依赖
Instructions (DOT + Step)	✅	Anthropic	执行流程
Examples	推荐	OpenClaw skill-writing-guide	典型 + 边界场景
Best Practices	推荐	OpenClaw skill-writing-guide	关键约束 + 原因
Common Mistakes	✅	Anthropic	反模式三列表
Permissions	✅	claw-flow 约定	目录权限隔离
Limitations	推荐	OpenClaw skill-writing-guide	能力边界声明

Skill Workshop 与发布

提案工作流

• openclaw skills workshop propose-create — 提议新 Skill
• openclaw skills workshop propose-update — 提议修改现有 Skill
• --proposal-dir — 支持文件（须含 PROPOSAL.md）
• 审核后：inspect 和 apply 使用 proposal ID

发布到 ClawHub

1. 确保 SKILL.md 完整（name、description、gating 字段、可选 homepage URL）
2. 安装 ClawHub skill：openclaw skills install clawhub-publish
3. 运行 clawhub publish

使用 {baseDir}

{baseDir} 占位符引用 Skill 目录内的文件，避免硬编码路径。示例：{baseDir}/scripts/run.sh

控制粒度校准

Sources: agentskills.io, Skil Creator Best Practices, 2026-06-15

并非 Skill 的每个部分都需要相同的指令性。将指令的具体程度与任务的脆弱性匹配。

具体程度与脆弱性匹配

策略	适用场景	示例
给予自由度	多种方法可行、任务容忍变化	Code review：描述检查什么，不规定精确步骤
保持指令性	操作脆弱、一致性关键、特定序列	数据库迁移：严谨序列 migrate.py --verify --backup

大多数 Skill 是混合的。解释了为什么的指令更可靠——理解了目的的 Agent 在边缘情况下更不容易绕过约束。

提供默认值，而非菜单

当多种工具/方法可用时，选一个默认方案并简要提及替代——而非平等呈现所有选项。

[NO] 你可以用 pypdf、pdfplumber、PyMuPDF 或 pdf2image...
[OK] 使用 pdfplumber 做文本提取。需要 OCR → pdf2image + pytesseract。

优先流程而非声明

Skill 应教 Agent 如何着手处理一类问题，非对具体实例产出什么。

有效指令模式

Sources: agentskills.io

Gotchas 章节

最高价值内容之一：环境特定事实，纠正 Agent 默认会犯的错误。不是通用建议，是具体纠正。

## Gotchas

- `users` 表使用软删除。查询必须包含 `WHERE deleted_at IS NULL`
- 用户 ID 在 DB 是 `user_id`，auth 服务是 `uid`，计费API是 `accountId`——三者同一值。
- `/health` 返回 200 时 Web 服务正常，但数据库可能已断开。用 `/ready` 检查完整健康。

维护策略：Agent 一旦犯错需要纠正 → 添加到 Gotchas。

输出格式模板

用模板替代散文描述格式——Agent 对具体结构的模式匹配更好。短模板内联，长模板放 assets/。

Plan-Validate-Execute（计划-校验-执行）

用于批量或破坏性操作：

1. 提取/制定结构化计划（如 field_values.json）
2. 校验计划：对照事实来源（如 form_fields.json），错误消息需包含足够信息让 Agent 自纠
3. 校验通过后才执行

校验循环

执行 → 运行校验器（脚本/checklist/参考文档对照）→ 修复 → 重复直到通过。

打包可复用脚本

对比各测试用例的 execution trace。发现 Agent 每次都独立重写相同逻辑（图表、解析器、校验器）→ 写一次测试过的脚本，打包到 scripts/。

从真实专业知识出发

Sources: agentskills.io

避免让 LLM 在无领域上下文的情况下生成 Skill（结果模糊泛化）。有效 Skill 根植于：

• 实操任务提炼：在 Agent 对话中完成真实任务，记录奏效步骤、纠正、I/O 格式、提供的上下文
• 项目产物综合：从内部 Runbook、API spec、Code review 评论、版本历史（补丁/修复）、真实故障案例中综合

See Also

• 高质量 Skill 方法论 — 5 步方法论：边界、骨架、标准、干货、产品化
• Agent Skills 开放规范 — agentskills.io 完整格式规范
• Skill 评估与迭代 — Eval 驱动的品质改进
• 优化 Skill Description — 提升 Skill 触发准确率
• Agent 开发综合指南 — Agent 开发完整框架
• 高效表达指南 — 精简表达体系