从重复工作到可验证流程：Agent Skills 完整设计方法

Claude Code／Codex 兼容：新手可直接使用的 Skill 创建提示词完整版想尝试制作 Agent Skills。可一打开 Claude 或 Codex，往往第一句话就卡住了。「我不知道该指示什么」「我不知道该在 SKILL.md 写什么」「即使写了很多规则，也担心他们是否真的会遵守」「根本上，我也不知道自己需要考虑到什么程度的规格」这很正常。

Claude Code／Codex 兼容：新手可直接使用的 Skill 创建提示词完整版

想尝试制作 Agent Skills。

可一打开 Claude 或 Codex，往往第一句话就卡住了。

「我不知道该指示什么」
「我不知道该在 SKILL.md 写什么」
「即使写了很多规则，也担心他们是否真的会遵守」
「根本上，我也不知道自己需要考虑到什么程度的规格」

这很正常。

初学者在创建 Skill 时，不需要从一开始就考虑 YAML、评估指标、触发条件、验证脚本、子代理设计等。

先回答四件事就够了。

反复做的事情是什么
成功的标准是什么
想要避免的失败有哪些
有没有接近理想的参考例

其余部分，可以交给 Claude 或 Codex，让它以「技能设计者」的身份补齐。

2026年7月时点，Codex 和 Claude Code 都采用了以 SKILL.md 为中心，根据需要加载脚本、参考资料、模板等的 Agent Skills 机制。在 Codex 中，首先查看 Skill 的名称和说明，只有在判断必要时才阅读正文。Claude Code 也是同样，Skill 的正文在使用时才会被读取。真正重要的不是把提示词越写越长，而是把触发条件、执行流程、验证方法和结束条件设计清楚。

先把下面这份提示词原样跑一遍。

第1章：给初学者的完整 Skill 创建提示词

将以下内容粘贴到Claude Code或Codex的普通聊天中。

在 Codex 中，也可以先调用 $skill-creator 再粘贴。Codex官方的Skill 创建器也会确认「是做什么的技能」「何时触发」「是否包含脚本」，但以下提示是完整版本，还增加了质量评价和循环工程。

你是世界顶级的
「Agent Skills Architect」
「Workflow Engineer」
「Evaluator Designer」。

我是Agent Skills制作的新手。
即使我不了解专业术语和文件结构，也请制作一个可以在Claude Code或Codex中实际使用的完成Skill。

不要只停留在说明，如果有可用的文件操作工具，请实际创建Skill文件夹和所需文件。

如果是在无法创建文件的环境中，请按文件名完整输出内容，不要省略。

■ 我想制作的Skill

想制作的Skill：
【在这里用一句话写】

使用环境：
【Codex／Claude Code／两者／不知道】

使用这个技能想实现的目标：
【写出自己知道的范围。不知道的话写「交给你处理」】

实际可能会请求的示例：
【1〜3个。不知道的话写「交给你处理」】

绝对要避免的失败：
【例如：文章像AI生成、设计模板化、按钮只是外观不能点击、未测试就宣称完成等】

接近理想的参考例、资料、网站、文章、代码：
【有的话写出。没有的话写「无」】

质量水平：
【简易／实务质量／最高质量／不知道】

不清楚的项目：
【全部可以委托补全】

■ 初学者应对规则

如果信息不足，请一次性最多提出7个问题。
对于我回答「不了解」「交给你处理」的项目，请提供3个选项，并在其中推荐最具可复制性的方案。
对于即使我不回答也能继续进行的项目，请采用合理的默认值，并在assumptions.md中记录为假设。
使用专业术语时，请在括号内附上让初学者也能理解的一行说明。
对于收费、公开、部署、数据删除、更改认证信息等不可逆操作，请不要自动执行。
处理容易变动的服务、API、库时，请确认当前的官方文档。不要仅凭过往记忆来决定规范。

■ Skill设计的必备步骤

请务必遵守以下顺序。

步骤 1：意图的汇总

请将我模糊的请求转换为以下内容。

技能的目的
目标用户
输入
输出
成功条件
绝对条件
这次不做的事情
预期的失败
必需的工具
需要人工批准的操作

请创建以下内容。

brief.md
acceptance-criteria.md
assumptions.md

步骤 2：触发条件的设计

请明确技能何时应使用及不应使用。

description中请包含以下内容。

Skill 的功能
用户在什么目的下使用
用户即使不说出 Skill 名称也应该触发的情况
类似但不应触发的请求
重要的目标文件、格式、作业名称

description 要简洁，并将重要用途放在开头。不要只是写「提高质量」「有帮助」。

STEP 3：规则优先顺序

请将所有指示分为以下三个阶段。

A. HARD GATES
绝对不能违反的条件。如违反，将整个成果物判定不合格。

B. 默认值
基本上遵循默认值。
如果在项目上有明确理由，可以更改。

C. 偏好
为了更好而设置的偏好。
在满足HARD GATES和DEFAULTS之后进行优化。

不仅要写「必须」「绝对」「高质量」，
还能将可能的内容转换为测试、命令、JSON判定、检查项目。

步骤 4：技能结构的设计

原则上，请考虑以下内容。

<skill-name>/
├── SKILL.md
├── USAGE.md
├── references/
│ ├── domain-knowledge.md
│ ├── quality-rubric.md
│ └── failure-patterns.md
├── templates/
│ ├── brief-template.md
│ └── scorecard-template.json
├── evals/
│ ├── trigger-evals.json
│ └── output-evals.json
└── scripts/
└── 必要的验证脚本

但是，请不要创建不必要的文件。

在 SKILL.md 中，每次只写必要的核心流程。
详细的知识、长例子、API 规范、风格指南请分到 references。

对于每个 reference，请在 SKILL.md 中明确写出：
「什么时候阅读」
「为了判断什么而阅读」

如果同样的决定性处理每次都由 AI 重写，请移到 scripts。

步骤 5：创建 SKILL.md

SKILL.md 请以以下结构为基础。

任务
何时使用
何时不使用
输入
所需上下文
指令优先级
工作流程
硬性门槛
质量标准
验证
修复循环
停止条件
完成报告
支持文件

技能名请仅使用小写字母、数字和连字符。
请确保文件夹名与 name 一致。

请不要让主要的 SKILL.md 变得过于庞大，
原则上保持在500行以下，约5,000个令牌以下为宜。

STEP 6：循环工程

不要将 Skill 设定为一次生成就结束的流程。

请加入以下循环。

计划
构建
运行
观察
评分
修理
重测
停止或继续

但是，请不要在简单的作业中使用过多的循环。

作为初始值，请迭代最多3次。
在以下情况下请结束。

通过了所有HARD GATES
超过了合格分数
最近 2 轮没有显著改善
同样的错误重复了两次
达到了成本或时间上限
需要人工判断

请采用评价最高的检查点，而非最后的版本。

STEP 7：生成角色与评价角色的分离

对于复杂或主观的成果物，请将生成角色与评价角色分开。

生成角色：
制作成果物。

评价角色：
从干净的上下文中检查成果物，不要宽容评分，并附上具体证据。

评价结果应包括以下内容：

criterion_id
expected
observed
passed
evidence
severity
likely_cause
minimal_fix
retest_method

评估人员在可能的情况下，
请不仅运行源代码，还要运行实际成果物。

对于网页，请操作浏览器，
对于应用，请检查UI、API和保存状态，
对于游戏，请进行实际操作，
对于视频，请检查时间轴和渲染，
对于文章，请确认事实、声音和情感曲线。

步骤 8：验证脚本

可以机械判定的内容，
请用脚本验证，而非依靠LLM的感想。

例：

文件的存在
JSON 的有效性
禁止字符串
虚拟实现
类型错误
测试结果
链接失效
图片尺寸
对比度
文本溢出
输出格式
必填项

在创建脚本时请遵守以下事项。

不要求对话输入
提供 –help
显示错误原因及修改方法
如可能，将 JSON 输出到 stdout
诊断信息输出到 stderr
即使重新执行也不会损坏
对破坏性操作提供 –dry-run
返回有意义的退出代码

STEP 9：触发评估

请至少在 trigger-evals.json 中创建以下内容。

应触发的例子：8〜10 件
不应触发的相近例子：8〜10 件

请改变表达方式。

礼貌的请求
口语
短句
长句
包含错字的请求
未提及技能名的请求
隐藏在多个步骤中的请求

不仅要包含明显无关的例子，
还要包含关键词相似但应使用其他技能的例子。

步骤 10：输出评价

请在 output-evals.json 中至少创建 3 条记录。

通常情况
模糊情况
边界或失败情况

每种情况请包含以下内容。

prompt
expected_output
input_files
assertions
hard_gates
human_review_points

如果可能，请在干净的上下文中比较有 Skill 和无 Skill，或者旧版与新版。

主观质量请进行盲测比较，隐藏哪个是新版。

步骤 11：改进

请根据评估结果对 Skill 最多改进三轮。

在改进时，请不要只为失败案例追加特别规则。
请将失败的根本原因归类到以下某一项。

触发
情境
流程
工具
验证
评估者
停止条件
内存

不仅要增加指示，也请考虑删除不必要的指示。

步骤 12：完成报告

最后请面向初学者报告以下内容。

创建的Skill名称
保存位置
文件夹结构
该Skill可以做的事情
触发的请求示例
不触发的请求示例
手动调用的方法
初次测试方法
验证结果
仍然存在的限制
下一次改进时要查看的文件

不要只说「完成了」，请展示您执行的验证命令和证据。

关于在此提示中写什么

真的只写一句话也可以。

例如，如果想制作具有有人味道的日语写作技能，可以这样写。

想制作的技能：
能够在日语的note文章或X帖子中，保留人类书写的波动与情感的写作技能

使用环境：
Codex

想通过这个技能实现的目标：
想要内容易读，但又不显得过于AI化整齐的文章

实际可能会请求的例子：
「把这个体验谈写成note文章」
「把这段文字改成符合我风格的语言」

绝对想要避免的错误：
相同结尾的连续出现、过度的项目符号、抽象理论、虚假的经历

接近理想的参考例：
之后提供自己过去的文章

品质水平：
最高品质

如果其他不清楚，可以在末尾这样写。

除此之外不清楚。
请选择最适合初学者的、最安全且可重复的构成。

到这个程度，就可以开始Skill设计了。

第2章实际保存和调用Skill的方法

Claude Code和Codex的保存位置略有不同。

Codex

如果是项目专用，请放在以下位置。

项目/
└── .agents/
└── skills/
└── 技能名称/
└── SKILL.md

如果要在自己的所有项目中使用，放到以下位置。

~/.agents/skills/技能名称/SKILL.md

在Codex中，可以在提示中明确指定技能，或者在CLI和IDE中从$选择技能。自动触发由description匹配决定。

Claude 编码

如果是项目专用，请放到以下位置。

项目/
└── .claude/
└── skills/
└── skill-name/
└── SKILL.md

如果要在自己所有的项目中使用，请放到以下位置。

~/.claude/skills/skill-name/SKILL.md

在 Claude Code 中，除了可以通过 /skill-name 手动执行外，如果 description 和请求内容匹配，也会自动加载。

例如，如果技能名是 human-japanese-writer，则在 Claude Code 中可以这样调用。

/human-japanese-writer

请将以下备忘录制作成note文章。
…

在Codex中明确说明如下。

使用 $human-japanese-writer，
请将以下备忘录制作成note文章。
…

最初阶段不要只依赖自动触发，明确调用会更容易确认其运行情况。

第3章 Skill是什么，它不是长提示

强Skill和弱Skill的区别不在于文章数量。

弱Skill是这样写的。

请制作高质量的网站。
请使用现代且精致的设计。
请实现响应式设计。
务必进行测试。

否则，「高质量」「现代」「精致」「测试」这些词看起来都对，真正执行时却没有判断标准。

另一方面，强大的技能是这样认为的。

定义网站会给谁带来怎样的感情
决定视觉识别（Visual Identity）
比较2至3个不同的设计方向
记录选择理由
制作静态完成布局
在浏览器中实际操作
检查 375px、768px、1440px三种宽度
分别评估设计质量、独创性、精度、功能性
仅修复失败项目
采用评价最高的版本

Skill的本质不是「下达正确答案」。

而是让模型无法省略接近正确答案的过程。

第4章在海外前线使用的八层设计

1．触发路由器——何时使用

Skill如果不在内容之前先触发，就没有意义。

Agent Skills 启动时，不会把所有 Skill 正文一次读完。最初主要查看name和description，只加载必要的Skill。这一机制称为Progressive Disclosure，即「仅在需要时才打开详细信息的设计」。

所以，接下来的描述很弱。

description: 支持网站制作。

不知道会做什么、什么时候使用、界限在哪里。

改进示例如下。

description: >
在创建或重新设计需要原创视觉指导、响应式实现、浏览器验证、可访问性检查以及迭代设计审核的生产质量网站时使用此技能。适用于着陆页、品牌网站、产品网站、作品集和注重视觉质量的网络应用。不适用于仅后台工作、微小文本编辑或孤立的实用功能。

description中至少要包含「做什么」和「什么时候使用」。根据Agent Skills的规格，description的最大长度为1,024个字符，Skill名称由小写字母、数字和连字符组成，并与上级文件夹名称一致。

此外，还要制作触发测试。

在官方的Skill创建指南中，建议分别制作8〜10个左右的应触发请求和不应触发请求，并混合使用口语、错别字、隐含表达、短句和长句的方法。不只是简单地将无关请求作为否定例，更重要的是「近似例」，即关键词相似但属于不同工作的情况。

2．Intent编译器——将模糊的请求转化为合同

假设非工程师是这样请求的。

做一个时尚的预约应用。
要好用，还要加入AI。

如果就这样开始实现，几乎肯定会出现偏差。

先将其转化为以下内容。

目标用户：
小型沙龙的店主和顾客

最重要的流程：
顾客查找空闲时间、预约，并收到确认邮件

AI的角色：
根据希望条件提出候选时间

成功条件：
预约被保存，重新加载后仍存在，并能在管理员界面确认

此次不做的内容：
支付、多个门店、高级CRM

绝对条件：
不允许预约重复

把这个转换过程视为Intent Compiler。

优秀的Skill不会直接将用户的一句话转换为代码。

会先转换为brief.md或acceptance-criteria.md。

仅有这个中间成果物，就不容易在过程中模型的理解发生变化。

3．Context Loader——只读取必要的知识

不要把各种信息都塞进Skill正文。

在Agent Skills的标准规范中，建议主SKILL.md少于500行，约5,000个令牌以下，并且建议将详细资料分离到references/中。

错误的写法是这样的。

请根据需要阅读references。

不知道什么时候应该阅读什么内容。

改进示例如下。

仅在创建或修改日文副本时，
阅读references/japanese-voice.md。
用于判断句末、节奏、情感表达和禁止表达。

只有在更改认证或权限处理时，
才阅读 references/security.md。
判断认证边界、权限检查和机密信息的处理。

只有在制作多场景视频时，
才阅读 references/transitions.md。
判断场景转换的方式和时机。

明确条件时，模型只会读取所需的上下文。

在 Codex 中，引入大量 Skill 会使初始 Skill 列表占用上下文空间，因此 description 可能会被缩短，或者部分 Skill 会从初始列表中省略。因此，重要用途应放在 description 的开头。

4．规则编译器――将请求变更为检查

以下规则很弱。

禁止虚拟实现。

模型可能会将仅外观的按钮判断为「完成」。

在强Skill中，将会转换为如下。

HARD GATE: DISPLAY_ONLY_FEATURES

如果符合以下任一项，则判定不合格。

点击也不会改变状态的主要按钮
API调用返回硬编码的成功值
保存后不会反映到数据库或持久存储中
TODO、FIXME、mock、placeholder仍保留在主要功能中
UI存在，但无法完成使用流程

验证：

使用自动脚本搜索 TODO、FIXME、mock、placeholder
在真实浏览器中操作主要按钮
检查 API 响应
保存后重新加载
确认持久状态

规则分为三阶段。

HARD GATES

违反即不合格。

例：

构建失败
主要功能无法运行
内容与事实不符
泄露个人信息
不符合对比度标准
未经批准发布

DEFAULTS

通常遵守。

例：

维持现有技术栈
不增加新的依赖
移动优先
一个功能一个功能完成

PREFERENCES

如果有余力则进行改进。

例：

独特动画
更有印象的文案
高级微交互

如果每条规则都写成「绝对」，真正关键的那几条反而会被淹没。

5．Maker——制作角色

Maker制作成果物。

不过，不要让Maker从头到尾一次性制作大型应用。

先将其拆分为有意义的单元。

功能1：会员注册
功能2：登录
功能3：创建预约
功能4：预约列表
功能5：管理员界面

针对每个功能，确认完成条件。

预约创建功能的完成条件：

可以选择日期和时间
不能选择过去的日期和时间
不能与已有预约重复
保存后显示确认页面
即使重新加载预约仍然存在
可以在API和数据库中确认状态

在Anthropic的长时间应用开发实验中，将Planner、Generator、Evaluator区分开来，并在实现前就「制作什么」和「测试什么」进行确认。Evaluator使用Playwright实际操作UI，并确认API和数据库状态。这样做，是为了避免只凭查看源码就通过外观优秀、但内部无法运行的实现。

6．Checker——从不同的视角评分

仅仅让生成的模型自己评分是不够的。

刚创建的模型了解自己的意图。

「实际上应该能运行」
「不是大问题」
「用户应该不会介意」

因此很容易做出宽松的判断。

Checker在可能的情况下，在干净的上下文中启动。

评估结果应包含证据，而非感想。

{
"criterion_id": "BOOKING-004",
"expected": "保存预订后，即使重新加载，预订也会显示",
"observed": "保存后立即显示，但重新加载后消失",
"passed": false,
"evidence": "重新加载后，GET /api/bookings 返回 []",
"severity": "高",
"likely_cause": "数据仅保存在前端的 state 中",
"minimal_fix": "将 POST 处理连接到数据库保存，然后通过 GET 重新获取",
"retest_method": "创建预订后，重新加载页面，检查 UI、API 和数据库"
}

可以由脚本处理的部分交给机械判定。

只有主观的部分才交给LLM。

即使在Agent Skills官方的评价指南中，也建议对JSON有效性、文件数量、行数、图片尺寸等使用验证脚本，而文章或设计的「感觉」则使用人工审核或盲测比较。

7．Repair Loop——只修复失败的部分

不能因为评价低就重新制作全部内容。

例如，假设网站的评价如下。

设计质量：88
独特性：74
精度：91
功能性：95

所需的并不是整个页面的重新实现。

找出独特性低的原因。

关键视觉居中规范的结构
紫色渐变和白色卡片
使用默认图标且未加工
没有品牌专属的摄影方针

仅修正那一部分。

如果同样的问题重复了两次，就停止细节修正并转变方向。

现在停止当前方向的微调。
更改布局结构、图片方针、排版逻辑。

然后，保留的不是最终版本，而是评价最高的版本。

设计并不是重复次数越多就一定越好。后期的设计可能装饰更多，有时中期的版本反而更优秀。

8．耐久记忆——将状态保持在对话之外

不要仅依赖模型的记忆来完成长时间的工作。

state.json
feature-ledger.json
decisions.md
scorecard.json
failures.json
CHANGELOG.md

将状态保存在这些文件中。

{
"current_phase": "维修",
"best_checkpoint": "迭代-2",
"best_score": 88,
"failed_criteria": [
"设计-原创性-02"
],
"attempts": {
"设计-原创性-02": 1
},
"next_action": "替换通用英雄构图"
}

Codex 的 Subagent 功能也说明了，通过不向主对话大量发送探索日志或测试日志，而仅从专业代理返回摘要，可以抑制上下文污染的设计。但是，由于每个 Subagent 都使用各自的模型和工具，因此与单独运行相比，令牌消耗会增加。

因此，并不需要将所有 Skill 都多代理化。

第5章循环的强度可以三档选择

适合的工作级别构成 Level 1 轻微修改、短句子、简单转换执行 + 自查 Level 2 实务文章、网页、单一功能的实现 Maker + Checker + 1〜3轮修改 Level 3 高价值应用、游戏、影像、复杂的 MCP 联动 Planner + Maker + Evaluator + 实际环境验证

复杂化并不一定会变得更好。

在Anthropic的实验中，虽然Planner・Generator・Evaluator的结构有助于提高质量，但相比单独运行成本大幅增加。此外，也确认到当模型自身能力提升时，以前必要的细分冲刺结构有时就不需要了。Evaluator 不是每次都要启用；只有任务超出模型能够独立稳定处理的范围时，它才真正有价值。

初学者的初始值Level 2就足够了。

第6章可直接使用的通用SKILL.md模板

以下内容可以转用于各种领域。

name: your-skill-name
description: >
当用户希望实现[目的]且任务需要[専門工程・検証・対象形式]时使用此技能。用于[代表的使用例]。
即使用户没有直接点名 Skill，只要描述了[隐含目标]也可以使用。不要用于[相近但不在范围内的工作]。
compatibility: 设计用于与Codex和Claude Code兼容的Agent Skills客户端。
metadata:
version: "1.0.0"

任务

将用户的请求转换为一个经过验证、可用的结果，用于：

主要用户：[対象]
主要成果：[成果]
质量水平：[品質]
主要需防止的风险：[失敗]

当工件可以运行、呈现、打开、播放或以其他方式测试时，不要仅凭源检查就声称已完成。

何时使用

在以下情况下使用此技能：

[触发条件1]
[触发条件2]
[隐含的触发条件]
[目标作业包含在多个步骤中时]

何时不使用

在以下情况下不要使用此技能：

[不适用1]
[不适用2]
[相邻技能更合适的情况]

输入

收集或推导：

目标
受众
参考资料
所需输出
约束条件
质量标准
截止日期或执行预算
不可逆操作

如果缺失的细节不会阻碍安全进展，请选择一个合理的默认值，并将其记录在 assumptions.md 中。

只有在缺失的信息会实质性改变结果、造成安全风险、花费金钱、发布内容、删除数据或做出不可逆转的决定时，才要求澄清。

指令优先级

按以下顺序遵循指令：

硬性关卡
特定任务的验收标准
项目惯例和源材料
默认值
偏好

切勿为了更高的主观评分而放弃硬性关卡。

必要的背景

请先阅读项目说明和现有文件。

仅在符合条件时加载支持参考资料：

当[条件]时阅读references/domain-knowledge.md。
在主观评估前阅读references/quality-rubric.md。
在进行维修或出现已知故障时阅读references/failure-patterns.md。

默认不要加载每个引用。

工作流程

阶段 0：编译意图

创建或更新：

brief.md
acceptance-criteria.md
assumptions.md

在生成最终成果之前定义成功的标准。

阶段 1：检查

检查当前项目、现有产出、工具、约束条件以及相关的源材料。

没有明确理由，不要替换现有约定。

阶段 2：计划

制定能够产生完整、可测试结果的最小计划。

对于主观性工作，当方向的选择对质量有实质性影响时，产生 2–3 个真正不同的方向。选择其中一个并记录原因。

阶段 3：构建

一次处理一个有意义的、可测试的单元。

在当前单元之外保持工作行为。

在可用版本控制时，在进行大规模或高风险更改之前创建检查点。

阶段 4：运行

尽可能在其实际介质中使用工件。

示例：

网络：在浏览器中启动和浏览
应用：测试用户界面、API 和持久化状态
游戏：玩核心循环
视频：检查时间线和渲染的帧
写作：与来源和语音参考进行比较

阶段 5：验证

先运行确定性检查。

然后使用 references/quality-rubric.md 进行主观评审。

每个通过项必须包括可观察到的证据。

阶段 6：修复

仅修复失败或退回的标准。

不要重写无关的工作部分。

在同一标准失败两次之后，停止重复相同的方法，并改变基本策略。

阶段 7：重新测试

重新运行失败的检查和所有相关的回归检查。

更新 scorecard.json。

阶段 8：停止

当出现以下任何情况时停止：

所有困难关卡通关且达到了目标分数
提升在两轮内停滞不前
达到最大迭代次数
达到成本或时间预算
需要人工批准

使用分数最高的有效检查点，而不是自动使用最新的。

困难关卡

如果以下任何一项成立，则结果失败：

[绝对条件1]
[绝对条件2]
[绝对条件3]
未经必要验证即声称已完成
失败的验证被隐藏或描述为通过
执行未经授权的不可逆操作

质量标准

对每个类别的评分从 0 到 100:

正确性: [定义]
完整性: [定义]
可用性: [定义]
独创性或风格: [定义]
技巧: [定义]

最低整体分数: 85

硬性门槛失败不能通过高平均分抵消。

评估结果格式

{
  "overall_score": 0,
  "hard_gates_passed": false,
  "criteria": [
    {
      "criterion_id": "",
      "score": 0,
      "passed": false,
      "expected": "",
      "observed": "",
      "evidence": "",
      "severity": "",
      "likely_cause": "",
      "minimal_fix": "",
      "retest_method": ""
    }
  ],
  "best_checkpoint": "",
  "next_action": ""
}

配角剧本

使用方式：可用脚本：

Sliptz/验证。* — 去电矿验证
脚本/检查。* — 工件检测
脚本/学术。* — 分数汇总

运行脚本 ਵਿਦ 非交互式参数。

除非脚本文档明确定义了其他含义，否则将非零退出码视为失败。

完成报告

报告：

1。创建或更改了什么

1。输出的位置

1。所做的假设

1。运行的验证命令

结果和证据
剩余限制
选择的最佳检查点

这是不易破坏标准规格的通用形态。

Claude Code特有的context: fork、allowed-tools、动态图景注入等，仅在Claude专用Skill需要时才添加。在Codex中，可以使用agents/openai.yaml来设置UI信息、隐式触发策略、依赖工具等。在通用Skill的最初几个中，不要过度堆砌平台特有功能，这样更易于操作。:contentReference[oaicite:13]{index=13}

第7章　从成功的对话中创建Skill的提示

实际上，有比从零开始思考技能更强的方法。

先让Claude或Codex实际完成一次工作。

这次对话包括以下内容。

最初模糊的请求
中途添加的条件
AI 错误的地方
人类修正的内容
最终成功的方法
本人的偏好
现场特有的注意事项

将这次对话转换为技能。

この会話で行った作業を分析し、
再利用可能なAgent Skillへ変換してください。

単に会話を要約するのではなく、
次のものを抽出してください。

1. 最初の依頼には含まれていなかったが、
   成功に必要だった追加情報

2. 私が途中で修正した内容

3. AIが合理的に推測すると間違える、
   この分野またはプロジェクト固有のGotcha

4. 毎回再利用できる工程

5. 自動化できる検証

6. 参考資料へ分離すべき知識

7. 良い出力例と悪い出力例

8. Skillが発火すべき依頼と、
   発火してはいけない近接依頼

9. 成功条件、HARD GATES、終了条件

10. 今回の一例だけに過剰適合しないために、
    一般化すべき原則

一般的すぎる助言は除外してください。

例：
「高品質にする」
「適切にエラー処理する」
「ベストプラクティスに従う」
だけでは不十分です。

現実の作業で得られた、
具体的な手順、判断基準、失敗条件、検証方法を優先してください。

現在の会話だけでは足りない部分は、
推測と事実を分けてassumptions.mdへ記録してください。

完成後は、SkillありとSkillなしで評価できる
trigger evalsとoutput evalsも作ってください。

在Agent Skills官方指南中，也强调不仅仅从一般知识编写技能，而应从实际操作、API规格、审查评论、过去的修改、失败案例等中提取专业性。

第8章按用途分类・添加至技能创建提示的指示

以下内容请添加到最初展示的完整提示末尾。

A．有人性日本语写作技能

附加条件：日语写作

在此技能中，请不要将「人性」理解为错字或随机表达。

请将人性设计为以下要素。

观察的具体性
句子的长短变化
句末的分布
汉字与平假名的平衡
根据情感的节奏
断言与保留
与读者的距离
不过度解释的留白
强调句的简短
个体特有的词汇

请将文章创作分为以下几个步骤。

事实与主张的整理
读者的情绪曲线
构成
转换为声音
消除AI式的统一性
事实保全
假定朗读的节奏确认

请加入检查以下内容的机制。

相同句末的连续出现
相同长度句子的连续
连接词的过度使用
抽象词语过多
没有依据的情感
捏造的经历
不自然的项目符号
试图解释一切的文章
标题的过度使用
公式化的AI表达

如果有本人文章样本，请制作 voice-profile.md。

但不要直接大量复制本人原话，请抽象化其特点。

在最终评估中，请分别对真实性、声音、节奏、具体性、情感变化、与读者的距离进行评分。

B．面向非工程师的振动编码技能

附加条件：面向非工程师的振动编码

不要仅仅根据用户模糊的请求就立刻开始编写代码。

请首先创建以下内容。

product-brief.md
user-journeys.md
acceptance-criteria.md
out-of-scope.md
feature-ledger.json

不要使用专业术语，要根据用户实际能够实现的功能来编写规格。

例如：

不好的规格：
「实现 CRUD API」

好的规格：
「管理员可以添加商品，
即使页面重新加载商品也会保留，
并显示在普通用户的商品列表中」

请一次完成一个功能。

请检查各功能的UI、API、保存状态和错误状态。

请将以下设为HARD GATE。

主要按钮只是外观
数据仅保存在state中
API返回固定值
认证和权限只有界面显示
错误状态未实现
没有测试就说完成
TODO、FIXME、mock、placeholder残留在主要功能中

最终报告请用非工程师也能理解的语言，说明：
「能做什么」
「如何测试」
「还不能做什么」

C．1000万级目标的网页制作技能

「1000万日元订购的品质」无法仅靠技能来保证。

高额的网页制作包括业务理解、客户调查、品牌战略、拍摄、文案、设计、实现、验证以及项目管理。

但是，可以接近那个制作流程。

附加条件：高级网页设计

在编写HTML或组件之前，
务必通过Visual Identity Gate。

请将以下内容定义到DESIGN.md。

品牌的目的
目标客户
情感
品牌承诺
与竞争对手的差异
颜色的作用
排版
照片或插图方针
留白
布局原则
动作原则
不使用的表达方式

不要没有根据地自动跳到下一步。

紫色渐变
白色卡片排列
居中英雄区
通用SaaS布局
未加工的UI库默认值
无意义的光晕
过度圆角
无目的使用的库存照片

在实施前，请制作 2〜3 个不同的艺术指导（Art Direction）。

不仅仅是颜色不同，
请改变构图、密度、排版、图像和运动的逻辑。

评估指标：

设计质量：整体是否作为一个世界成立
独创性：是否有独特的判断
工艺：文字编排、留白、颜色、精度
功能性：能否毫不迷茫地实现目的

请重点评价设计质量和独创性。

请在浏览器中确认以下内容。

375px
768像素
1440像素
长文章
短文章
空状态
错误状态
键盘操作
焦点显示
菜单
表单
主要CTA
链接失效
对比度
横向滚动
溢出

不要仅凭静态图片判定合格，请实际操作页面。

在Anthropic的前端实验中，也将设计质量、独创性、精度和功能性进行区分，并使用Evaluator在Playwright上操作实际页面的循环进行评估。特别是，不仅评估模型擅长的基本精度，还高度评价设计质量和独创性，从而尝试脱离通用AI设计。

D．应用制作技能

附加条件：应用制作

请以用户状态迁移为中心进行设计，而不是以页面数量为中心。

请定义以下内容。

用户类型
权限
输入
保存状态
异步处理
失败
重试
空状态
加载中
审计
通知
会话

请从以下四个方面验证各主要功能。

UI
API
数据库或持久状态
日志或错误

不要以「页面显示」为完成条件。

例子：

设置更改功能的完成条件：

拥有权限的用户可以进行更改
没有权限的用户无法更改
保存后重新加载值仍然存在
API 响应正确
数据库值被更新
失败时显示恢复方法

如果要添加 AI 功能，
请考虑是否可以通过工具操作应用自身的功能，而不仅仅是制作一个看起来像聊天框的界面。

E．游戏制作技能

追加条件：游戏制作

请先完成最小的「可玩的纵向切割」作品，而不是先积累内容量。

请首先定义以下内容。

游戏的支柱
30 秒的核心循环
玩家目标
失败
奖励
学习
紧张与释放
重试
1 玩的时长

请将评估分为三类。

技术检查器：

崩溃
帧率
输入
碰撞检测
存档
再现性

系统检查器：

难度
经济
攻略单调化
死局
奖励平衡

感受检查器：

输入延迟
击中感
音效
摄像机
预兆
重试速度
是否想再玩一次

请使用固定 seed 或固定输入序列，制作可以比较修改前后的测试。

不要仅凭截图美观就通过，请实际游玩核心循环。

F．HyperFrames 视频编辑技能

附加条件：HyperFrames 视频制作

在编写 HTML 之前，请务必先制作 DESIGN.md 或 visual-style.md。

请按以下顺序进行工程。

What
让观众体验什么
Structure
场景、构成、轨道、素材
Timing
尺寸、节奏、转折点、情绪高峰
Layout
静态完成每个场景的 Hero Frame
Animate
以完成的位置为基准，添加入口和动作

在静态布局完成之前，
不要通过动画来掩盖位置。

请将以下内容设置为HARD GATE。

不要在没有视觉识别的情况下编写HTML
不要使用Math.random或依赖时间的内容
不要使用无限重复
不要忘记注册时间轴
不要让同一元素的同一属性发生冲突
不要在多个场景中使用没有过渡的跳切
不要忽略文本溢出
不要忽略对比度警告
未确认最终渲染前不要说完成

制作完成后请执行以下操作。

npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect
动画地图
草稿渲染
最终渲染

请将评估角色分成三类。

故事检查员：
故事、信息密度、开头的承诺、情感高峰、余韵

视觉检查员：
排版、构图、视线、颜色、动作层次

技术检查员：
时间轴、媒体、溢出、对比度、
确定性、渲染

只修改失败的场景。

即使是在HyperFrames的核心技能中，制作流程也按照What、Structure、Timing、Layout、Animate的顺序进行整理，先确定视觉识别，再静态地制作出元素最显眼的Hero Frame，然后再添加动画。

此外，决策性、有限重复、时间线注册、场景切换、溢出、对比度、动画地图等被定义为验证项目。

G. 视频生成MCP·剧本制作技能

附加条件：视频生成MCP和剧本制作

请不要将用户的一句话直接发送到视频生成模型。

请进行以下转换。

目的
→ 对观众的承诺
→ 情感的变化
→ 节奏表
→ 场景目标
→ 镜头规格
→ 提供者适配器
→ MCP 工具调用

请将视频模型的特定规格与故事和镜头设计分开。

通用的镜头规格应包括以下内容。

shot_id
story_purpose
duration
subject
action
environment
camera
composition
lighting
palette
motion
continuity_in
continuity_out
negative_constraints
acceptance_criteria
reference_assets
seed或用于重现的ID

请为每个视频提供商创建一个将通用Shot Spec转换的适配器。

请将易变的信息，如模型名称、时长、分辨率、参考图片、API规格等，分离到references或MCP Resources中。

请先用便宜的关键帧、低分辨率、短时长确认构图。

Continuity Checker请确认以下内容。

脸部
服装
道具
画面方向
光线
时间段
相机速度
角色的目的
镜头在故事中的作用

只重新生成失败的镜头。

不要每次都重做整个影像。

请不要仅仅通过在提示中添加cinematic、masterpiece、8K等形容词就认为质量提高了。

请对主体的动词、相机、构图、光线、连贯性、禁止条件进行结构化。

第9章改进现有技能的提示

技能不是一次创建就结束的。

请使用以下内容，从执行结果中进行改进。

请根据实际评估结果改进以下Agent技能。

输入：

当前的SKILL.md
参考资料
脚本
触发器评估结果
输出评价结果
执行日志
失败断言
人工审查
令牌和执行时间
与旧版的比较结果

改进流程：

将失败分类到下一步

触发器
上下文
程序
工具
验证
评估者
停止条件
内存

确定根本原因，而不是症状
判断以下哪项是必要的

修改description
明确步骤
添加参考资料
删除参考资料
制作脚本
修改测试
严格Evaluator
修改结束条件
将技能拆分为两个
删除指示

仅将失败测试的具体单词添加到description中，避免过度拟合
不仅考虑增加指示，也要考虑删除
保存旧版
在一个不同的干净上下文中评估新版
在未用于学习的Held-out测试中也进行确认
不使用最后的版本，
采用在验证集上得分最高的版本

输出：

failure-analysis.md
proposed-changes.md
更新后的Skill
changelog.md
regression-evals.json
旧版与新版的比较

即使在官方的评估指南中，也推荐执行每个测试时分为有Skill和无Skill，或旧版和新版，使用干净的上下文，并比较具体的Assertion、证据、token和执行时间的方法。

第10章修复不触发的Skill的提示

Skill的内容很优秀，但不会被调用。

这个问题非常普遍。

请从触发精度的角度改进该Skill的描述。

请创建以下内容。

应触发的任务10件
不应触发的相近任务10件
各自的分类理由
现有描述的不足
现有描述过于宽泛的部分
改进描述方案3个
各方案的预期优点与误触发风险

在测试中请混合以下内容。

明确说明技能名称的请求
不说技能名称的请求
口语
错字
单句请求
冗长的背景说明
隐藏在多个步骤中的请求
使用相同关键词的其他工作

如果可能，请每个请求执行3次，并记录触发率。

请将测试分为训练 60% 和验证 40%。

改进描述只使用训练结果，最终方案请通过验证结果选择。

不要自动采用最终方案，请采用在验证中得分最高的方案。

在Agent Skills的官方指南中，也介绍了尝试同一请求多次、测量触发率、将Train和Validation分开、以及选择Validation成绩较好的解释而不是最后的方案的方法。

第11章让模型创建验证脚本的提示

如果希望遵守规则，应尽可能将可实现的部分转化为代码。

请分析此Skill的规则，
并提取那些不依赖LLM主观、可以通过机器验证的内容。

请将各个规则分类如下。

A. 完全可以机器判定
B. 部分可以机器判定
C. 需要人类或LLM评估

对于A和B，
请制作最小必要的验证脚本。

脚本要求：

无对话输入
有 –help
参数不足时显示使用示例
具体显示错误原因
将 JSON 输出到 stdout
诊断日志输出到 stderr
0 表示成功
非0表示失败
可再次执行
如果可能，使用 –dry-run
避免大量输出
可定位失败位置
明确依赖关系
固定版本
附加测试

在 SKILL.md 中，请注明每个脚本何时执行，以及失败时需要修正的内容。

在Agent Skills的脚本设计指南中，也推荐使用非交互式、明确的–help、具体的错误信息、结构化输出、幂等性、Dry Run、安全的默认值、有意义的退出代码。

第12章　初学者在最初30分钟内要做的事

1. 只选择一项工作

不要从一开始就制作万能的Skill。

不好的例子：

将文章、网页、应用、游戏、视频全部制作到最高质量的Skill

好的例子：

从自己的语音备忘录制作note文章的Skill

在制作LP时进行品牌设计和浏览器验证的Skill

验证HyperFrames字幕和布局的Skill

一个Skill应具备一个核心职责。

2．粘贴最初的完整提示

不懂的部分，都可以「交给处理」。

3．确认已创建的文件夹

至少有以下内容即可运行。

skill-name/
└── SKILL.md

在Agent Skills规范中，最基本必需的是SKILL.md，scripts/、references/、assets/是可选的。没有必要一开始就创建大量文件。

4．手动调用

最初不等待自动触发。

Claude Code的话：

/技能名称

如果是 Codex：

$skill-name

5．通过三个任务进行测试

普通任务

模糊任务

可能失败的任务

例如如果是写作技能：

普通：
把这条备忘录做成 note 文章

模糊：
让它有种会被阅读的感觉

边界：
缺少事实的地方适当编写经验故事

在第三个任务中，观察是否能够在不捏造的情况下进行确认或明确假设。

6．只修正一个错误

一开始不要追求满分。

文章很好，但句尾过于一致

那就只改善句尾检查。

网页很漂亮，但移动端会横向滚动

那就只改善响应式检查。

一次性加入大量规则时，就会不知道哪项更改起了作用。

第13章常见错误

错误1．只写抽象词

高质量地
自然地
美丽地
易用地
专业地

这些不是目标，而是感想。

把它们转化为可观测的状态。

错误2．只增加禁止事项

绝对不要～
一定要～

仅有禁止，不知道应该如何判断。

要避免的东西
代替使用的原则
检测方法
例外条件

都要写。

错误3．把所有内容放入SKILL.md

把大量参考资料放入正文时，每次都会全部进入上下文。

只保留核心流程，将细节分到references/。

错误4．只放好例子

仅有好例的话，不知道从哪里算作失败。

examples/good/
examples/bad/

准备这些，并写出失败的原因。

失败5. 只看源代码就认为完成

能运行的就运行。

能打开的就打开。

能玩玩的就玩。

能渲染的就渲染。

失败6. 每次全部重做

只修正失败的条件。

限定修正范围。

失败7. 无限循环

决定最大次数、合格分数、改进幅度、费用上限。

循环并不是跑得越久就越厉害。

失败8. 制作万能Skill

万能Skill，触发条件和评估方法都会变得模糊。

文章、Web、应用程序、游戏、视频，在保持共同的Loop Core的同时，按领域划分Skill。

第14章发布前检查清单

Skill本体

name是否仅由小写字母、数字、连字符组成
文件夹名与name是否一致
description中是否包含做什么和何时使用的信息
不该触发的边界是否明确
主Skill是否膨胀过大
详细资料是否只在需要时阅读
是否包含具体判断或注意事项，而非一般性说法

工程

制作前是否定义了成功条件
是否区分HARD GATES、DEFAULTS、PREFERENCES
创建后是否确认了实物
是否根据需要区分生成角色和评估角色
失败条件是否有证据
是否仅修正失败部分
是否有结束条件
是否保存了最佳版本

评估

是否有常规情况
是否有模糊情况
是否有边界情况
是否有应触发的例子
是否有不应触发的接近例子
是否无Skill时，或与旧版进行比较
是否将可以机器判定的内容脚本化
是否进行了主观质量的盲测比较
是否保留了人工评审
是否符合Token和时间的增加

结论 Skill创建中最初应指示的事项

初学者不必从一开始就写出完美的SKILL.md。

只需要向 AI 传达以下内容即可。

我在重复什么。
如果能做到什么就算成功。
想避免哪种失败。
接近理想的是什么。

将这些信息通过 Skill 制作提示转换为下一个。

含糊的请求
↓
目的
↓
触发条件
↓
成功契约
↓
流程
↓
HARD GATES
↓
验证
↓
评价
↓
修改
↓
重新验证
↓
结束
↓
学习

真正好用的 Skill，不会只命令模型「更努力」。

不能草率开始
不经验证不能结束
不能隐藏失败
不能无休止地重复同样的修改
下次不会忘记相同的失败

构建这样的环境。

Skill 不是聪明的提示。

它更像一个小型工作系统，让 AI 能够稳定复现高质量结果。

把这套长模板真正变成自己的 Skill

读到这里，最容易出现的反应是把整份模板复制进项目。

先等等。

模板的价值，是帮助你看见一套完整系统可能有哪些零件。它不是要求每个 Skill 都拥有同样复杂的组织结构。

一个更稳妥的起点，是从重复失败开始。

找一件你已经做过多次的工作。把最近一次成功结果和一次失败结果放在一起，写清输入是什么、什么样算完成、哪类错误绝对不能出现、用什么命令或证据可以验证。

然后只写能够让这件事稳定重现的规则。

描述负责让代理在正确时机发现它。正文负责规定工作顺序和硬门禁。参考文件保存领域知识。脚本负责那些适合确定性执行的检查。样例负责告诉维护者，什么请求应该触发，什么请求虽然关键词相似却不属于它。

回到前面的八层结构，就能更容易判断哪些层需要保留，哪些应该拆到参考文件、模板或检查脚本里。

任务含糊，就需要意图编译。

资料很多，就需要按需加载上下文。

输出容易看起来完整却实际不可用，就需要 Maker 与 Checker 分离。

失败能够局部修复，就设计修复循环。

过程跨越多次会话，就把状态写到会话外。

没有这些问题，不必为了架构看起来高级而硬加。

Codex 的 AGENTS.md 与 Skill 也不要混为一谈。AGENTS.md 用来告诉 Codex 怎样理解仓库、运行测试并遵守项目惯例。 Skill 更像一项可重复调用的专门工作流。两者可以配合，但承担的责任不同。

检查一个 Skill 是否真的有用，可以做一组近邻测试。

给它一个明确应该触发的请求。

给它一个显然不相关的请求。

再给它一个包含相同关键词、但实际属于另一项工作的请求。

真正容易出问题的是第三种。

只靠关键词触发的 Skill，常常会在这里露馅。

运行以后别只看最终文案漂不漂亮。保留代理读取了什么、调用了什么、测试是否通过、修复了几轮、为什么停止。Codex 会通过终端日志和测试结果提供可核查证据。这类证据比一句已经完成可靠得多。

收尾时，任何能写文件、执行命令或触碰外部系统的 Skill，都要把权限和停止条件写在前面。生成代码以后仍需人工审查和验证，不能把代理的完成声明当成交付证明。

一个好 Skill 不会让提示词显得更宏大。

它会让失败变得更早、更清楚，也更容易修。