add-skill 是 paldom/skillskit 提供的一项 Agent Skill 编写工作流，目标是在你当前所在的任意仓库中，以“评估优先（eval-first）”的方式构建一个生产质量的技能，产物位于 skills/<name>/ 目录。开始前应每个会话阅读一次 references/skill-authoring.md 与 references/evals.md，它们是该工作流执行的规则手册；由 create-skill-repo 脚手架生成的仓库也会把它们作为 docs/ 携带。若以 /add-skill <args> 调用，则把 $ARGUMENTS 视为第 1 步中要界定的技能名称或想法。
用途与不适用场景
该工作流用于编写或改进单个 Agent Skill。它明确列出不应使用的情况：创建新的技能仓库应使用 create-skill-repo；把一个研究包转成一个或多个技能应使用 skill-from-research（它在提炼研究包后按技能驱动本工作流）；基础设施工作（钩子、CI、验证器）应走普通编辑与 PR 级审查；如果所谓“技能”只是重述模型已经做得好的事情，则不应构建——技能必须修复一个具体观察到的失败。
工作流
第 1 步是界定范围并选择调用模式。用一句话说明技能做什么以及它修复的具体失败；如果这句话需要“和”，就拆成多个技能，一次做一个。检查仓库现有技能目录是否重叠——相邻描述会互相抢触发词，需规划不重叠的措辞。然后决定由谁调用，因为这会影响名称、描述和评估集：模型调用（默认，路由器根据用户措辞选择）或用户调用（disable-model-invocation: true，用户输入 /name；适用于有副作用的技能以及价值在于可记忆命令的技能）。当一种能力同时需要两者时，使用 references/skill-authoring.md 中的 alias-over-engine 拆分，而不是牺牲其中一方。
第 2 步是收集资料。若存在 .local/ 则递归阅读（研究、示例、约束——但绝不在技能中引用 .local/ 路径）。在此之外继续研究：用网络搜索获取当前事实、官方文档和先前技术；对任何承重事实用一手来源核实。技能依赖的已验证事实应作为清理并提交的文件放入 skills/<name>/references/。
第 3 步是评估优先。按 references/evals.md 创建 skills/<name>/evals/evals.json：至少 8 条 should_trigger（变化正式程度、错别字、简洁度），至少 8 条 should_not_trigger（共享关键词的近似项），以及 3–5 条带平实语言 expected_behavior 断言的质量用例。如果写不出这些，说明范围不清晰，回到第 1 步。对于用户调用技能，两个触发计数都免除——没有路由器权衡其描述——因此只写质量用例。
第 4 步是起草 SKILL.md。Frontmatter 要求：name 等于文件夹名；description 单行、第三人称。模型调用技能：描述为 [做什么] + [何时使用……] + [不用于……]，150–400 字符，触发关键词放在前约 120 字符内。用户调用技能：一行动词开头的句子，在 / 菜单中读起来自然——触发措辞和排除项在那里是累赘。正文按 references/skill-authoring.md：目的 → 何时/何时不 → 编号工作流 → 输出规范 → 注意事项 → 指针。控制在 500 行以内；确定性步骤作为 scripts/（失败时非零退出）；长材料作为带目录的 references/。通过 ${CLAUDE_SKILL_DIR} 引用捆绑文件，以便安装后的副本可用。
第 5 步是验证。如果仓库有验证器（make check / scripts/validate_skills.py），它必须以 0 退出——修复每个错误，分类每个警告。如果没有验证器，则按编写参考中的 frontmatter 规则自检（单行描述、name==文件夹、长度边界）。若存在 scripts/run_evals.py（make evals），它也必须通过：它针对每个同级描述给每条触发提示打分，并在无重叠提示、同级排名高于本技能或描述近似重复时失败。修复它指向的描述——绝不修改评估。
第 6 步是触发自测。对至少 3 条应触发和至少 2 条不应触发提示，明确推理：仅凭描述，在所有其他已安装技能中，这条提示会被路由到这里吗？修复描述，而不是评估。（用户调用技能跳过此步——没有东西路由它们。）
第 7 步是测量。在可用技能列表中扫描 Anthropic 官方 skill-creator（通常是 skill-creator:skill-creator；插件限定名因市场而异——按名称/描述匹配，不要硬编码）。如果存在，通过 Skill 工具将其作为子技能调用，范围限定为仅测量：它把每个质量用例作为 with-skill 与 baseline 子代理运行，给断言评分，并基准测试通过率/时间/token。把 evals/evals.json 中的用例按 references/evals.md 的“Automated harness”翻译后交给它，并遵循该节的护栏（仅工作区写入、用例运行检查、描述接受门）。如果不存在，则改为运行手动协议并说明——它只认证触发，不认证质量提升；绝不能让跳过的测量静默地当作“已测量”。
第 8 步是注册。当存在时更新仓库的 README 目录、CHANGELOG.md 和 skills.sh.json 分组（schema 形状："groupings": [{"title": ..., "description": ..., "skills": [...]}]——不是 groups/name；skills.sh 会静默忽略不符合规范的文件）。重新检查同级描述是否有新的重叠。
输出规范（完成定义）
skills/<name>/ 包含 SKILL.md + evals/evals.json（按需加 scripts/references）；仓库验证器通过（或在无验证器时记录自检）；已测量：安装官方 skill-creator 时用其基准，否则用 references/evals.md 的手动协议——说明运行了哪一个（回退只认证触发）；在存在时更新目录/CHANGELOG/分组；一份 3 行摘要：目的、触发短语示例、已知限制。
注意事项
description 必须保持在一个物理行——多行值在某些运行时加载失败；绝不要绕过仓库验证器。不要把失败的评估提示逐字粘贴到描述中（过拟合）；而是泛化缺失的动词/名词。过度触发的修复 = 从实际假阳性重叠中添加有针对性的“不用于……”名词短语；不要删除正向触发词。模型升级会改变路由——注意在下一次模型发布后应重新运行评估。
文件
references/skill-authoring.md——结构、frontmatter 规则、描述公式、正文结构、注意事项、反模式。references/evals.md——evals.json 格式以及触发/质量协议。