agent-skills-creator

Agent Skills Creator

以 Agent Skills 开放格式创建和改进技能：涵盖从选择模式到验证和更新 README 的完整生命周期。

• **适用范围：**创建新的 Agent 技能，以及审查或重写现有技能：SKILL.md、参考资料、规则目录、脚本、评估。
• **不适用范围：**AGENTS.md/CLAUDE.md 指令文件（请使用 agents-md）或一般文档质量（请使用 ghostwriter）。

选择模式

• 新建技能 → 参见下文的创建工作流。
• 审查、改进或重写现有技能 → 参见 references/improving-existing-skills.md，该文件会对 11 个审查维度评分，按顺序执行重写，然后重新使用步骤 5–8 进行验证和发布。
• 简化技能或更新技能集合 → 同样参见该参考文件，并使用 references/capability-delta.md 做出保留决策和维护集合台账。
• 技能从不触发、在错误的提示词上触发，或其描述在拥挤的列表中被截短 → 参见 references/evaluation-and-iteration.md 的路由评估部分，然后修改描述。修改正文无法修复路由问题。
• 技能在初稿完成后就停止并交回审核，而用户并未要求这样做 → 参见 references/authoring-tips.md 中的“明确工作何时结束”；应修正完成范围和审核检查点，而不是修改步骤。

参考文件

文件	何时阅读
references/capability-delta.md	移除通用指导、评估模型升级，或审查整个技能集合时
references/authoring-tips.md	默认在编写或删减正文内容时阅读：注重判断而非规则、校准约束、权限与完成范围、自由度、内容模式、描述
references/skill-patterns.md	选择结构模式时
references/format-specification.md	目录布局、规范与仅适用于 Claude Code 的 frontmatter、正文替换、加载语义、各宿主从何处读取技能及其功能、命名
references/rules-folder-structure.md	构建基于规则的审查／lint 技能时
references/improving-existing-skills.md	审查、评分、简化或重写现有技能；审查技能集合时参见 Module Lens 规则
references/executable-code.md	技能包含脚本、使用 ! 注入实时上下文、依赖软件包或调用 MCP 工具时
references/evaluation-and-iteration.md	编写 evals/evals.json、跨模型测试保留决策、路由测试、消融约束、针对既定目标迭代优化技能，或审查技能修订时
references/adopt-adapt-author.md	编写或采用技能之前：检查工作归属、选择公开范围，或决定引入、改编还是替换第三方技能时

验证器是本地机械门槛的唯一说明。从仓库根目录运行：

skills/agent-skills-creator/scripts/validate.sh skills/<name>   # one skill
skills/agent-skills-creator/scripts/validate.sh --all           # every skill in the repo

创建工作流

复制此检查清单以跟踪进度：

Skill creation progress:
- [ ] Step 1: Choose a pattern
- [ ] Step 2: Create directory and frontmatter
- [ ] Step 3: Write SKILL.md body
- [ ] Step 4: Add reference or rule files
- [ ] Step 5: Validate
- [ ] Step 6: Update README.md (and docs/skills.mdx where the repo has one)
- [ ] Step 7: Smoke-test installation
- [ ] Step 8: Evaluate and iterate

步骤 1：选择模式

创建技能之前，先检查是否已有现有方案负责该项工作；references/adopt-adapt-author.md 可指导复用和范围选择。

简单型／中心型、工作流型、基于规则型或混合型。references/skill-patterns.md 介绍了各类结构、仓库内对应示例，以及问题与模式的适配表。

步骤 2：创建目录和 frontmatter

创建 skills/<name>/SKILL.md，包含 name 和 description，并将 --- 放在第 1 行。将描述写成模型触发条件，而不是面向人的摘要：说明它的作用、涵盖的内容，然后加上“Use when...”以及用户实际会说的短语；关键用例要放在最前面，因为描述超出预算时，列表会从尾部截断。尽可能简短，但仍要说明适用场景：每个已安装描述都会出现在每个会话中，而夸大描述会加载一个帮不上忙的技能。validate.sh 会强制执行限制，因此请围绕路由编写，让脚本检查约束。

在添加其他任何字段之前，先决定技能要在哪些环境中运行。此集合请使用可移植字段；将真正的运行时先决条件放入 compatibility。特定宿主的字段需要查阅当前宿主文档，并用于刻意针对该宿主的软件包。当工作流会部署、发送或花费时，请在正文中说明授权边界；也要同样明确地授予安全操作循环的权限。正文需涵盖这两方面。格式参考文档会区分这些约定。

步骤 3：编写 SKILL.md 正文

先阅读 references/authoring-tips.md：其中说明了应包含什么、如何明确表述、权限与完成范围、自由度、内容模式以及渐进式披露。根据实际观察到的失败编写 Gotchas 部分；这是任何技能中信号最强的内容。

步骤 4：添加参考文件或规则文件

• 工作流/混合型：使用 references/ 文件夹；每个文件都要在 SKILL.md 中通过“Read when”条件链接
• 基于规则型：使用 rules/ 文件夹；references/rules-folder-structure.md 介绍 _sections.md、_template.md 和文件命名
• 简单型/枢纽型：将文件与 SKILL.md 放在一起，并通过 tracks 表格链接

优先选择代码形式的参考内容。现有实现或测试套件比描述契约的文字更能固定契约（“Reference-as-Spec”）。按加载条件拆分，而不是按行数拆分：在不同时间阅读的两个主题应放在两个文件中。

高级功能详见 references/executable-code.md 和 references/format-specification.md：scripts/ 用于存放 Agent 编写的可执行文件，其路径相对于已安装的 SKILL.md 解析；Claude Code 可以替换 ${CLAUDE_SKILL_DIR}；!`command` 注入用于技能在调用时始终需要的数据（差异、PR 评论）；hooks frontmatter 用于设置仅在技能激活期间存在的 PreToolUse 门控；config.json 用于存放设置上下文，避免每个会话都重新询问。

步骤 5：验证

skills/agent-skills-creator/scripts/validate.sh skills/<name>

输出会区分 格式 要求和 项目规范，其中包括作为本地门槛采纳的建议。修复所有 FAIL。运行 skills-ref validate <dir>，独立检查元数据和命名。两种检查都无法验证行为质量，也无法保证与所有宿主兼容。

步骤 6：更新 README.md

在匹配的分类标题下添加该技能的项目符号，并增加计数；validate.sh 会检查这两项，并指出缺少的内容。如果仓库也包含 docs/skills.mdx，请在其中添加相同的项目符号。

步骤 7：冒烟测试

如果安装行为发生了变化，请使用安装程序文档中说明的本地源选项，将编辑后的本地源安装到一次性目标中。对照工作副本验证已加载的 SKILL.md 以及打包的参考文件或脚本。请勿为了冒烟测试编辑而覆盖全局安装，也不要以安装远程默认分支来证明尚未推送的更改。

第 8 步：评估与迭代

references/evaluation-and-iteration.md。在 evals/evals.json 中编写 2–3 个场景，首次运行后添加断言，并在全新会话中比较启用与未启用技能的表现。这项比较是保留测试：技能带来的改进必须足以抵消其成本。使用应触发和近似误触发提示，单独测试路由。在每个目标模型上测试，并对你怀疑是多余的规则进行消融：删除规则，重新运行场景，只有在某项测试退步时才保留。若要在一轮以上持续追求目标，请使用该参考文档中的 The Hillclimb Loop，并通过 agent-evals CLI 运行。

易踩的坑

• ~/.agents/skills/<name>/ 下安装的副本是一个副本，并非指向仓库的链接。编辑仓库不会影响正在运行的会话，而旧副本会静默加载，因此技能可能落后好几个提交，却看似正常。请确认评估加载的是已编辑的本地源文件。
• 引用链故障时，应将加载条件移入 SKILL.md，而不是换种措辞掩饰相同的依赖。
• skills add 中的 --agent 参数是可变参数，以空格分隔（--agent codex cursor）；它会一直读取参数，直到遇到下一个以 - 开头的参数。以逗号分隔的列表会逐项验证，并作为一个无效名称整体被拒绝。不要因 ~/.codex/skills 为空就断定安装失败：任何 skillsDir 为 .agents/skills 的 Agent 都被视为通用 Agent，安装位置是 ~/.agents/skills/，这些 Agent 会直接读取该目录。
• toc-over-100-lines 要求任何超过 100 行的参考文件在前 20 行内包含 ## Contents。更靠后的 Contents 标题不算，因此文件看起来没问题，实际却会验证失败。
• 描述中未包含 “Use when” 会直接导致 description-triggers 验证失败；但如果描述包含该短语，却缺少正确的触发词，则不会触发任何验证错误，只会永远不被路由到。验证器无法发现这一点，只有路由评估才能发现。
• description-length 允许任何少于 1024 个字符的内容；即使每条描述都通过验证，所有描述加起来仍可能超出宿主的列表预算。此时宿主会缩短每条描述，而 “Use when” 条款最先被删掉。评估描述时，应将其与同组的其他描述放在列表中一起判断，而不是孤立地看。
• “在此停止，并提交结果供审查”这样的步骤，即使用户要求完成整个任务且并未关注进度，也会让当前前沿模型结束任务。这一步听起来像安全规则，因此在删减约束时很少有人质疑，结果技能发布时会少完成一个实现步骤。

反模式

• 将完整规范全部塞进 SKILL.md 正文，而不是放入参考文件
• 使用有时效性的内容（“2025 年 8 月前，使用……”），包括将模型名称作为规则存在的理由
• context: fork 技能的正文是指导方针，而非任务；子 Agent 得到约定却没有提示词，因此不会返回任何内容
• 使用含糊的名称（helper、utils、tools、documents、data），让模型无法据此进行路由

相关技能

• agents-md：审查 AGENTS.md/CLAUDE.md 指令文件
• ghostwriter：提升文档质量

仅用于维护：evals/evals.json 保存了任何修改此技能的人都可使用的行为场景和路由提示词。它在用户任务期间绝不会加载；这正是 references/improving-existing-skills.md 要求的基线 Phase A。