make-skill — 以已验证的方式创建、改造和发布技能
从工作仓库（通常是 ~/DATA/<name>）复制：ssheleg/super-ux（多技能套件，Cursor 规则）或 ssheleg/task-pipeline（单技能编排器，发布自动化）。make-skill 本身即按此规范构建。
参考资料 — 按需加载
| 阅读 | 时机 |
|---|---|
references/agent-skills-spec.md | 编写或审计任何 SKILL.md — 来自两个权威机构的硬性限制、可选字段、预算、谁拒绝什么 |
references/authoring.md | 编写或调整正文/描述 — 命名、第三人称、自由度、脚本规则、评估循环 |
references/surfaces.md | 在 Claude Code 之外的任何地方发布 — Skills API 上传/版本/每次 8 个请求、claude.ai 压缩包、无网络限制 |
references/enterprise.md | 安装他人的技能，或管理企业技能群 — 风险等级、审查清单、审批关卡、生命周期 |
references/retrofit.md | 审计现有技能/仓库 — 14 项检查清单、证据规则、个人技能简表 |
references/host-capabilities.md | 发布钩子、子代理、命令、脚本或 MCP 依赖 — 各自的收益和成本、钩子事件和退出码、降级条款 |
references/claude-code-plugin.md | 任何以 Claude Code 插件/市场形式发布的内容 — 清单模式、组件布局、路径变量、validate 失败 |
references/distribution.md | 仓库布局、发布以及全部五个渠道 — 插件、skills CLI、npx、Cursor、统一家族仓库 |
references/mcp.md、references/mcp-ship.md | 技能与 MCP 服务器的对比、包装一个 MCP 服务器 — 然后发布：挂载、其 404、server.json、注册表 |
references/a2a.md | 技能跨越两个自主代理（A2A）：代理卡片、任务生命周期、委托 |
此副本缺失？原始回退：
raw.githubusercontent.com/ssheleg/make-skill/main/plugins/make-skill/skills/make-skill/references/<file>
选择工作流
从请求和 $ARGUMENTS 中的任何路径检测；宣布选择。
| 情况 | 工作流 |
|---|---|
| 新技能，仅用于此用户的代理 | 创建（个人） |
| 新技能，可被其他人/其他代理安装 | 创建（可分发） |
| 现有技能或未达此标准的仓库，“是否符合规范？” | 改造 |
| 个人技能应变为可安装 | 升级 |
无参数时，检测而非询问：当前目录中存在 SKILL.md、.claude-plugin/ 或 plugins/*/skills/*/ → 运行改造审计并报告差距表以及一个下一步操作。未检测到任何内容 → 用一行询问要创建什么。
可分发工作是真正的项目：先有规范（docs/superpowers/specs/）再有代码，并且规范首先锁定目标项目的文件契约——技能是针对该契约编写的，而非临时拼凑。
编写规则（每个工作流）
规范优先——开放标准和 Anthropic 的平台规则都是不可协商的；此规范仅在此基础上添加。 字段表、差异和检查清单：references/agent-skills-spec.md。
name：references/agent-skills-spec.md中的字符规则；等于目录名。陷阱：绝不能包含anthropic或claude——Claude Code 会愉快加载这些保留子字符串，但 Skills API 会在上传时拒绝，因此失败会在别人的机器上暴露。description：≤1024 字符（此限制仅针对此字段，而非整个前置数据块），无尖括号，第三人称——它被注入系统提示，在那里“我可以帮助您…”会降低选择概率。说明其功能和使用时机。- 可移植的可选集合是
license、compatibility、metadata和allowed-tools——限制和类型见references/agent-skills-spec.md。 license是可选的——无论如何都声明它，在前置数据和marketplace.json插件条目中同时声明：根目录的LICENSE文件既不会到达插件列表，也不会到达已安装的技能，并且不会报错，因此差距保持开放（此处所有六个仓库，2026-07-30）。- 主机扩展是合法的，但绝不能是关键依赖。 Claude Code 会读取进一步的主机专用集合（
references/claude-code-plugin.md）；其他代理会忽略它，因此一个依赖它的技能在所有其他地方都是损坏的。规范外 ∪ 主机外 = 拼写错误。 - 正文 < 500 行且 < 5000 个 token，并保留 5% 的余量——一个正文达到 99% 预算意味着下一次更正将与验证器发生冲突。较重的内容放在
references/、scripts/、assets/中，位于技能目录内，深度一级，每个都从正文中链接，并附带明确的加载触发条件（“当……时阅读 X”）——绝不要只是一个“见 references/”。超过 100 行的参考文件以## 目录列表开头：代理获取的是head的部分读取。 - 陷阱保留在
SKILL.md中：代理无法知道打开一个关于它不存在的陷阱的文件。 - 为你声明的最弱表面编写（
references/surfaces.md）：Claude API 容器没有网络和软件包安装，claude.ai 各不相同，只有 Claude Code 两者兼备。一个执行pip install或 curl 的脚本是 Claude Code 技能——在compatibility中说明或以其他方式舍弃。表面之间不会同步任何内容；git 是真相来源。
在规范之上的补充规则：
- 散文是英文；字面量保持其输入时的语言。 西里尔字母仅出现在四个地方，其中字符串本身是关键：触发短语、拒绝短语（操作员输入两者——翻译后，它们不再匹配所说的内容）、专有名词、语言示例（
«вы»/«ты»）。预算规则优先于风格规则：俄语以 1.9–2.3 字符/token 编码，而英语为 5.0（cl100k），将八个 ssheleg 路由器重写为英文后，它们从 3408 个 token 减少到 1885 个 token，且没有损失任何含义。 description以“使用时”开头，并列出具体的触发短语——英文和俄文（用户两者都使用）。无人触发的技能是死重。此处也保留 5% 的余量（≤970/1024）：一个接近极限的邻居强制要求一个“不用于……”子句，而一个已达 98% 上限的描述则没有容纳它的空间。- 一个命名模式，最好是动名词（
processing-pdfs）；绝不要使用helper、utils、tools、data——模糊的名称会输掉每一次选择。 - 一个技能 = 一项工作。多个关注点 → 多个技能 + 一个共享的契约文件。将契约放在技能目录内（
references/…）：skills CLI 仅发布技能自己的目录，因此兄弟目录skills/references/作为 Claude Code 插件可以工作，但在所有其他代理上到达时是损坏的。跨技能共享 → 在每个技能目录中复制，通过验证器检查是否相同。 - 正文：命令式、过程式、优先使用检查清单而非散文；将不可协商的内容作为不可协商的内容陈述。将规定性与脆弱性相匹配——对于破坏性或顺序依赖的工作使用精确命令，对于上下文决定的地方仅提供方向（
references/authoring.md）。 - 评估优先于散文： 在没有技能的情况下运行目标任务，记录失败，针对这些失败编写 ≥3 个评估，然后编写通过的最小内容；没有基线构建的技能记录了想象中的问题。添加到现有技能家族 → 针对已安装的集合测量共存性，不要猜测它：你命名的邻居通常不是最近的邻居。
- 提供一个单命令入口点：幂等——检查状态 → 修复缺失部分 → 状态报告 → 恰好一个建议的下一步操作。检测模式，绝不询问。技能就是那个命令；调用方式因渠道而异（从技能目录调用使用
/<skill>，作为插件调用使用/<plugin>:<skill>）——在 README 中编写两者，而非只承诺一个。 - 绝不覆盖用户数据：仅在不存在时播种；仅在
--force后覆盖。
降级契约（每个涉及主机能力的技能）
钩子、子代理、/commands、插件路径变量和 MCP 服务器仅存在于 Claude Code 内部——这是技能运行环境的少数。每个都是带有书面回退的加速器；技能仍能在没有它的情况下完成工作，但速度更慢。 在正文中编写三种情况，使用代理自己的语言，在需要它们的点上（模式：references/host-capabilities.md）：
- 非 Claude Code（Cursor、Codex、skills CLI、API）：没有钩子、没有子代理、没有
/command。命名内联过程；捆绑的scripts/仍然可以传输，因此给出每个渠道的路径。 - 推荐的插件/技能缺失：说明一次什么被降级，继续使用手动路径。因为可选伴侣缺失而拒绝开始的阶段是损坏的，而非严格的。
- 工具、解释器或 MCP 服务器缺失：说明一次，回退到手动过程，绝不在循环中重试。交互式认证是一个人工步骤。
你知道但未编写的回退不是回退。
此技能附带的实际示例——复制这些，而非你的记忆
scripts/audit_skill.py 审计任何技能目录（标准库；改造的机械部分），作为 bin/make-skill-audit 包装用于 Claude Code。此外：hooks/（PostToolUse，除非编写了 SKILL.md 否则静默）、commands/skill-audit.md（特意不使用技能的名称）、agents/skill-auditor.md，以及六个骨架：assets/SKILL.template.md、assets/plugin.template.json、assets/marketplace.template.json、assets/hooks.template.json、assets/agent.template.md、assets/command.template.md。
创建（个人）
~/.claude/skills/<name>/SKILL.md 按照编写规则——完成。无仓库、无版本管理；下次会话加载。提到升级作为升级路径。
需要钩子、代理或 MCP 服务器，但仍然没有仓库？将 .claude-plugin/plugin.json 添加到同一文件夹——Claude Code 下次会话将其作为 <name>@skills-dir 加载。
创建（可分发）
仓库树、公共仓库基础、claude plugin validate ... --strict 两次运行以及自定义验证器规范都在 references/distribution.md → 可分发仓库布局 中。在创建第一个文件之前阅读它。 无论如何都适用：
.claude-plugin/marketplace.json位于仓库根目录；插件位于plugins/<name>/，带有自己的.claude-plugin/plugin.json；技能位于plugins/<name>/skills/<skill>/，内部包含references/、scripts/、assets/。只有清单位于.claude-plugin/中——埋在那里的组件加载为空，而插件看起来仍然正常工作。- 版本同步（硬规则）： marketplace.json、plugin.json、package.json 和顶部 CHANGELOG 条目携带相同的 semver，一起更新（如果
SKILL.md携带metadata.version，则还有第五个点）。 - 两次
--strict运行均为绿色，在 CI 中作为独立作业运行——它们仅读取清单，因此前置数据规则位于你自己的test/validate.py中，这需要一个负向自测：一个不能失败的验证器是装饰品。在plugin.json和市场条目中同时提供$schema和displayName（市场根目录不接受两者）。 - 公共仓库应向读者提供一个英语优先的 README、
CONTRIBUTING.md（包含验证更改的离线命令）以及SECURITY.md（命名私人渠道和安装程序接触的内容）。
首次发布——端到端，同一会话
一次性完成全部工作，没有半成品交接。只有首次发布需要人工（npm 2FA）；武装 CI 发布是发布过程的一部分，因此第二次不需要。11 步序列位于 references/distribution.md → 首次发布。 完成 = 五个已验证的事实：仓库 + CI 绿色、npm 可通过 npx 解析、插件已安装、skills-CLI 发现正常工作、下次标签发布无需人工。
改造（使现有技能/仓库达到标准）
先审计，后修复，在同一会话中完成。每个项目的判定：通过 / 差距 / 未运行，附带证据——一个 file:line 或你实际运行的命令的输出。“看起来没问题”不是判定，同样，对一个仅经过推理而未执行的检查的“通过”也不是判定；缺少工具的检查是带原因的“未运行”，绝不是“通过”。
首先运行捆绑的审计器——它确定性地完成机械部分，且绝不依赖于未设置的变量：
make-skill-audit <skill-dir> --house # Claude Code：插件的 bin/ 在 PATH 中
任何其他地方，从你刚读取此内容的 make-skill 目录运行 scripts/audit_skill.py。然后处理 references/retrofit.md 中的 14 项检查清单——规范基础、插件基础、表面、单一职责、入口点、布局和版本同步、验证器和 CI、评估、README、发布、仓库元数据、陷阱、协议、主机能力。对于个人技能，仅适用三项；该文件说明了哪些。
然后： 报告差距表，修复当前可修复的所有内容，更新次/补丁版本，运行发布检查清单。
升级（个人 → 可分发）
按布局创建仓库，将技能移动到 plugins/<name>/skills/<skill>/，将契约提取到 references/，然后端到端运行首次发布。仅在插件安装已验证后删除旧的 ~/.claude/skills/<skill> 副本。
安装他人的技能
技能是代理执行的指令加上代理运行时无需阅读的代码——安装一个技能就是安装软件。任何你未编写的内容首先获得 references/enterprise.md 中的审查检查清单。最高风险形式：从 URL 获取其指令的技能——该内容可能会在批准其审查后发生改变。
协议连接的技能（MCP / A2A）
技能是指令；它不能授予能力。教代理如何做是技能。针对实时系统的新能力是一个 MCP 服务器（先读 mcp.md，然后读 mcp-ship.md 以挂载和发布）。将结果委托给另一个自主代理是 A2A（a2a.md）。两个参考文件都包含线级规则——每个主机的工具名称发现、代理卡片以及交互式认证作为一个人工步骤。