如何从零开发工业级SKILL

Skill 这个词，想必大家都听过，甚至用过。但自己从零动手撸一个 Skill 包，恐怕不少朋友还没试过。这篇文章，我们就从一个空目录开始，一步步做出一个能被验证的 Skill 包。

我们要造的 Skill 叫 Skill Forge。它本身不处理具体的业务任务，而是干一件事：帮助我们创建、改进和检查其他 Skill。

你可以把它理解成一个“Skill 开发助手”。比如，当你想做一个“会议记录转项目周报”的 Skill 时，Skill Forge 会帮你把触发条件、工作流程、参考材料、检查规则和评估方式都整清楚。

工业级 SKILL 是什么

为什么敢管 Skill Forge 叫工业级的？这里有一套标准：

• 触发准确：该它上场时绝不缺席，不该它出场时绝不捣乱。

• 权限收敛：只给它完成任务必须的权限，多一点都不给。

• 模型匹配：什么任务配什么模型，各司其职。

• 渐进披露：材料按需读取，不会一股脑全塞给 Agent。

• 可评测：能跑脚本做验证，给个明确的通过/不通过结论。

• 可迭代：能通过持续改进，让它的质量螺旋上升。

一句话总结，就是把一个好用的提示词，升级成一套可触发、可执行、可检查、可持续修改的工作流包。

实践流程

开始动手前，我们先梳理一下开发一个通用 Skill 的常见套路。流程如下图所示：

分析需求 → 写成可复用 prompt/workflow → 跑起来测试 → 看哪里不稳定 → 修改 → 再测试

说白了，就是先把需求明确下来，然后写成可复用的 prompt 或者 workflow，再放到支持 Skill 功能的 Agent 里跑一遍，看看它能不能满足需求。不行就迭代优化，直到稳定为止。

好，下面开始今天的实操。

具体实践过程

环境准备

你需要准备好以下几样东西：

1. 一台能运行 python3 的电脑。本文用到的环境是：Python 3.14.5。

2. 一个趁手的编辑器，比如 VS Code。

3. 一个能运行 Skill 的 Agent 环境，比如 Claude Code、Codex，或者其它支持 SKILL.md 的 Agent。本文用的是 Codex CLI。

4. 一个专门用来放实验文件的目录。

项目初始化

定义路径变量

这一步是为了统一后面命令中会反复用到的路径，少写长路径，也能减少复制命令时出错的概率。

打开终端，先执行：

export CASE_ROOT="./cases/skill-forge"

• CASE_ROOT 是这次实践的根目录。后面我们创建的 Skill 包、测试结果、评分文件，都会放在这个目录下面。

你可以把它理解成一个“快捷地址”，一个指向我们工作区的变量。只要这个变量配置对了，后面的命令基本就能直接复制执行。

实操参考图：

创建实验目录

接下来，创建本次实践需要用到的目录：

mkdir -p "$CASE_ROOT"cd "$CASE_ROOT"

现在你的目录结构大概是：

cases/skill-forge/

后面我们就会在这个目录下放文章记录、测试结果和真正的 Skill 包。

命令执行参考图：

文件目录参考图：（由于是在本地的根目录下执行的命令，所以在用户目录下见到“cases”文件）

创建 Skill 包目录

现在来创建真正的 Skill 包目录。在 skill-forge 目录下执行下面命令：

mkdir -p skill-forge/{references,assets,scripts,agents}

创建完成后，目录应该长这样：

cases/skill-forge/ # 外层：这次实践的工作区
├── article.md # 可选：文章记录，目前没有这个文件
├── eval/ # 可选：测试结果，目前没有这个目录
└── skill-forge/ # 内层：真正的 Skill 包
├── references/
├── assets/
├── scripts/
└── agents/

注意，里面的 skill-forge/ 才是真正的 Skill 包；外层的 cases/skill-forge/ 是实验工作区，可以放文章、测试记录和其他临时材料。

命令执行参考图：

文件目录参考图：

简单的需求分析

在正式写 SKILL.md 之前，得先把 Skill Forge 的需求拆一下。

这次要做的 Skill Forge，不是处理某个具体业务任务的。它接收的是一个 Skill 需求，比如“帮我做一个会议记录转项目周报的 Skill”；它要产出的，是一个新的、可以复用的 Skill 包。

所以，它至少要回答这么几个问题：

• 用户提出什么请求时，应该触发 Skill Forge？

• 用户只是做普通总结、写作或代码任务时，它不应该出来捣乱。

• 触发之后，先判断任务类型：是创建、更新、验证，还是保持安静？

• 详细的评分规则、测试样例和检查脚本，不一股脑全塞进 SKILL.md，而是拆到 references、assets 和 scripts 里。

把这些想清楚了再动笔，SKILL.md 才不会写成一大段混在一起的提示词。

编写 Skill 入口：SKILL.md

接下来，我们来创建 SKILL.md 文件。它是 Skill 的入口文件，主要放触发条件、边界和最短工作流；详细规则、样例、评分标准不一定都放这里。

在终端的当前目录（外层的 skill-forge）下继续执行：

touch skill-forge/SKILL.md

现在，用 VS Code 打开上面的 SKILL.md 文件，先写入一个最小版本，并保存：

---
name: skill-forge
description: Use when the user asks to create, improve, validate, or evaluate an agent skill package. Do not use for general writing, generic summarization, ordinary coding tasks, or requests to perform the business task directly.
---
# Skill Forge
Use this skill to help create, improve, validate, or evaluate agent skills.
This skill does not perform the target business task directly. For example, if the user asks for a meeting-notes skill, create or improve the skill package instead of summarizing the meeting notes.
## Task types
Classify the request into one of four types:
- new: the user wants to create a new skill.
- update: the user wants to improve an existing skill.
- validate: the user wants to check whether a skill is usable.
- quiet: the request is a general writing, summarization, coding, or business-task request and should not trigger this skill.
## Minimal workflow
1. Identify the task type.
2. Check whether the request should trigger this skill.
3. If creating or improving a skill, define the skill contract first.
4. Keep SKILL.md short.
5. Put detailed scoring rules in references/rubric.md.
6. Put eval cases in assets/eval-cases.json.
7. Use scripts/skill_quality_gate.py for repeatable checks.
## Output requirements
When creating or improving a skill, produce:
- skill name
- description with positive and negative trigger rules
- minimal workflow
- required references
- required assets
- validation plan

这一步不用追求完美。后面，我们可以慢慢迭代。

先用 Codex 试跑一次

写完 SKILL.md 之后，先别急着补评分规则和测试脚本。我们先让 Codex 跑一次，看看这个入口文件是否能被 Agent 理解。

这里我用 Codex CLI 来做验证工具。

先确认下，终端当前所在的目录是否正确：

pwd
# 如果输出类似结果，说明位置正确；注意，这里的 user 是你当前的电脑用户名
/Users/user/cases/skill-forge

实操参考图：

Codex 在项目里通常从 .agents/skills 目录读取 Skills，所以我们先把刚才写好的 Skill 包复制过去：

mkdir -p .agents/skills
cp -R skill-forge .agents/skills/

然后启动 Codex：

codex

实操图：

进入 Codex 后，可以先显式调用一次：

$skill-forge 帮我创建一个“会议记录转项目周报”的 Skill。

这一步主要看它有没有做到几件事：

• 把任务识别为“创建新 Skill”；

• 先写触发条件和非触发边界；

• 没有自作主张去总结会议记录；

• 知道把规则、样例、脚本拆到不同目录。

如果这一步能跑通，说明这个最小版 SKILL.md 已经可以作为入口文件继续扩展。接下来，再补 rubric.md、eval-cases.json 和质量门禁脚本。

实操截图：（由于过程较长，这里放了 Codex 执行命令后的输出，以及最终跑完的结果图）

优化 Skill

这一步证明 skill-forge 已经能跑起来了。下面我们回到 skill-forge 本身，把它补齐成更完整的版本：依次补上 rubric.md、eval-cases.json 和 skill_quality_gate.py。

创建评分标准文件：rubric.md

这个文件的作用是：当 Agent 需要判断一个 Skill 好不好时，可以按这里的标准来评估。

如果你正处在 Codex 对话窗口，先执行下面命令退出：

# 退出 Codex
/quit

回到 skill-forge 目录下后，继续执行：

# 创建 rubric.md 文件
touch skill-forge/references/rubric.md

现在，用 VS Code 打开上面的 rubric.md 文件，写入一个最小版本并保存：

# Skill Quality Rubric
A good skill should be evaluated on these dimensions:
## 1. Trigger accuracy
The skill should clearly describe when it should be used and when it should not be used.
## 2. Minimal entry file
SKILL.md should stay short. Long rules, examples, templates, and eval cases should be moved into separate files.
## 3. Progressive disclosure
The agent should only read detailed references when needed.
## 4. Permission boundary
The skill should not ask for unnecessary permissions or unsafe actions.
## 5. Testability
The skill should include positive cases, negative cases, boundary cases, and output quality checks.
## 6. Iterability
The evaluation result should help locate what to improve next.

实操参考图（后面操作类似，省略相关截图）：

创建测试用例文件：eval-cases.json

再来整点测试用例。一个 Skill 写得好不好，不只看它什么时候会被用，还要看它什么时候能不乱入。

先创建文件：

touch skill-forge/assets/eval-cases.json

用 VS Code 打开文件，写入最小版本并保存：

{
"positive_cases": [
{"id": "positive-001", "input": "帮我做一个会议记录转项目周报的 Skill", "expected": "should_trigger"},
{"id": "positive-002", "input": "检查一下这个 Skill 的 description 有没有触发边界问题", "expected": "should_trigger"}
],
"negative_cases": [
{"id": "negative-001", "input": "帮我把这段会议记录总结一下", "expected": "should_not_trigger"},
{"id": "negative-002", "input": "帮我写一篇项目周报", "expected": "should_not_trigger"}
],
"eval_cases": [
{
"id": "eval-001",
"input": "帮我创建一个处理客服工单的 Skill",
"checks": ["includes positive trigger rules", "includes negative trigger rules", "keeps SKILL.md short", "separates references and assets", "includes validation plan"]
}
]
}

这里要特别强调：负例很重要。

创建质量门禁脚本

这个脚本先做最基础的检查：

• SKILL.md 是否存在；

• 是否有元信息区；

• name 是否正确；

• description 是否写了触发条件；

• 是否写了非触发边界；

• 入口文件是否太长；

• 评分标准和测试用例是否存在。

创建文件：

touch skill-forge/scripts/skill_quality_gate.py

现在，用 VS Code 打开文件，写入一个最小版本并保存：

#!/usr/bin/env python3
import json
import sys
from pathlib import Path

def fail(message):
print(f"FAIL: {message}")
sys.exit(1)

def ok(message):
print(f"OK: {message}")

def main():
if len(sys.argv) < 2:
fail("Usage: skill_quality_gate.py ")
skill_dir = Path(sys.argv[1])
skill_file = skill_dir / "SKILL.md"
rubric_file = skill_dir / "references" / "rubric.md"
eval_file = skill_dir / "assets" / "eval-cases.json"

if not skill_file.exists():
fail("SKILL.md is missing")
ok("SKILL.md exists")

content = skill_file.read_text(encoding="utf-8")
if not content.startswith("---"):
fail("SKILL.md must start with frontmatter")
ok("SKILL.md has frontmatter")

if "name: skill-forge" not in content:
fail("name must be skill-forge")
ok("name is valid")

if "description: Use when" not in content:
fail("description should start with Use when")
ok("description starts with Use when")

if "Do not use" not in content:
fail("description should include Do not use boundary")
ok("description includes negative trigger boundary")

if "TODO" in content:
fail("SKILL.md still contains TODO")
ok("SKILL.md has no TODO")

line_count = len(content.splitlines())
if line_count > 120:
fail(f"SKILL.md is too long: {line_count} lines")
ok(f"SKILL.md length is acceptable: {line_count} lines")

if not rubric_file.exists():
fail("references/rubric.md is missing")
ok("references/rubric.md exists")

if not eval_file.exists():
fail("assets/eval-cases.json is missing")
ok("assets/eval-cases.json exists")

data = json.loads(eval_file.read_text(encoding="utf-8"))
for key in ["positive_cases", "negative_cases", "eval_cases"]:
if key not in data or not data[key]:
fail(f"{key} is missing or empty")
ok(f"{key} exists")

print("PASS: skill quality gate passed")

if __name__ == "__main__":
main()

运行第一次质量检查

回到外层实验目录：

cd "$CASE_ROOT"

然后执行：

python3 skill-forge/scripts/skill_quality_gate.py skill-forge

如果一切顺利，你应该看到类似结果：

OK: SKILL.md exists
OK: SKILL.md has frontmatter
OK: name is valid
OK: description starts with Use when
OK: description includes negative trigger boundary
OK: SKILL.md has no TODO
OK: SKILL.md length is acceptable
OK: references/rubric.md exists
OK: assets/eval-cases.json exists
OK: positive_cases exists
OK: negative_cases exists
OK: eval_cases exists
PASS: skill quality gate passed

看到 PASS，就说明这个最小 Skill 包已经能通过结构检查了。

实操参考图：

后续优化

到这里，我们只是做出了一个最小可运行版本。

接下来要接着补三件事：

1. 完善 SKILL.md，让它能更准确地区分 new、update、validate、quiet 这四类任务；

2. 扩充 eval-cases.json，加入更多正例、负例和边界样例；

3. 增加 A/B 测试记录，对比普通 prompt 和启用 Skill 之后的效果差异。

可以先拿三个问题来检视它：

• 用户怎么说时，这个 Skill 应该出现？

• 用户怎么说时，这个 Skill 应该保持安静？

• 它是否能通过脚本检查，而不只是看起来写得不错？

如果这三点都能回答清楚，这个 Skill 就已经从一个长长的提示词，开始蜕变成一个可维护的工作流包了。

一图解本文