mcpField
S
skill-creator

skill-creator

github.com/jdforsytheAgent 工作流15147 次安装17 周前更新
代码仓库

关于 skill-creator

Skill Creator 是一套结合研究的技能编写流程，指导设计、起草和验证完整的技能目录。它规定 frontmatter、术语、反模式、示例以及按需添加参考文件的方式。

主要功能

  1. 01明确触发条件、受众和输出要求
  2. 02在需要时指导领域研究
  3. 03规定 SKILL.md 的结构
  4. 04提供反模式与示例设计指导
  5. 05涵盖验证和打包步骤

适用场景

  1. 01创建触发条件和输出明确的技能
  2. 02为陌生领域起草技能
  3. 03检查技能的结构和内容问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jdforsythe/forge --skill skill-creator

安装后在 Claude Code 中输入/skill-creator确认已加载。

附带文件references/skill-principles.mdreferences/skill-template.md

详细介绍

技能创建器

经研究增强的技能创建器，生成的技能质量高于内置默认技能。每项设计决策都以 Transformer 处理上下文的方式为依据。

专家词汇载荷

提示工程与路由： 专家词汇载荷、双语域描述、词汇路由、分布收敛、注意力预算、分布中心、恰当的抽象层级、检索锚点

技能架构： 渐进式披露、上下文窗口管理、U 形注意力曲线、YAML frontmatter、触发面、结构划分、三级加载（元数据 / SKILL.md / 参考资料）

行为设计： 反模式观察清单、检测信号、反例、祈使句指令、条件分支、评估标准

质量与测试： 规范示例、少样本学习、15 年从业者测试、顾问腔（禁止）、过度提示、近因偏差

反模式观察清单

以下是此创建器生成的技能中的反模式。交付前，请根据此清单检查每个生成的 SKILL.md。

1. 词汇中的泛泛顾问腔

**检测：**词汇载荷包含“最佳实践”“杠杆”“协同效应”“稳健解决方案”“可扩展框架”或“整体方法”等术语。应用 15 年从业者测试：资深领域专家会用这个确切的术语与同行交流吗？如果不会，则不合格。 **解决：**将每个泛泛的术语替换为它含糊指代的精确领域术语。“错误处理的最佳实践”应改为“熔断器模式（Nygard）、指数退避、死信队列”。

2. 过度提示

**检测：**SKILL.md 超过 500 行。相同概念换 2-3 种说法重复陈述，以“强调”重点。指令包含模棱两可的表达（“你可以考虑”“或许会有所帮助”）。 **解决：**以祈使句形式将每条指令陈述一次。删除模棱两可的表达。将大量参考内容移至 references/。先用最精简的版本测试；仅在模型明显表现不佳的地方补充细节。

3. 只给出正向指令

**检测：**完全没有“不要”或“避免”之类的指导。没有反模式观察清单。技能只描述该做什么，从不说明不该做什么。 **解决：**添加 5-10 个特定领域的反模式，并为其命名模式、检测信号和解决步骤。没有负向约束时，模型会倾向于分布中心（最泛泛、最普通的输出）。

4. 单一语域描述

**检测：**描述只使用正式术语或只使用口语。测试：用户说“帮我处理[任务的口语说法]”时，该技能会触发吗？如果不会，则缺少口语语域。 **解决：**重写描述，同时包含专家术语（用于路由至深层知识）和自然语言触发场景（用于可靠激活）。明确加入“即使他们没有说[正式术语]”之类的表述。

5. 塞入过多边缘情况

**检测：**包含超过 15 条具体的边缘情况规则。长篇罗列“如果 X，则 Y”，试图覆盖所有场景，而不是展示模式。 **解决：**替换为 3-5 个多样化的规范示例，以展示模式。其中应包含一个难例。让模型从示例中归纳，而不是死记规则。Anthropic 记录在案的建议是提供 3-5 个示例；LangChain 发现，在其基准测试中，3 个示例的效果大致相当于 9 个（收益递减，并非硬性上限）。

6. 段落式逻辑

**检测：**通过散文段落描述复杂的多步骤行为。没有编号步骤、IF/THEN 条件或祈使动词。 **解决：**重构为带有明确条件的祈使式有序步骤。“先检查是否存在反模式；如果发现，可能应该处理一下”应改为：“1. 扫描输入中的反模式。若检测到：执行‘检测-命名-说明-解决-预防’流程。若未检测到：继续第 2 步。”

7. 缺少示例

检测： 生成的技能中没有任何输入到输出的示例或 BAD/GOOD 对照。该技能完全依赖文字指令。 解决方案： 添加 3-5 个不同类型的示例。质量标准使用 BAD 与 GOOD 对照，工作流使用输入到输出的示例。将最具代表性的示例放在最后（近因偏差会让它产生最强影响）。

8. 对当前模型的规定过于繁琐

检测： 生成的 SKILL.md 罗列了详尽规则，对每条指令都加上保留条件，或读起来像是针对较旧、能力较弱的模型调优——即使词汇和反模式部分很精简，整体仍然密集且枚举繁多。 解决方案： 说明目标、边界和验证标准；让模型自行采用胜任的默认做法。描述部分要有足够推动力（触发仍然是薄弱环节），但正文要精简。将现有技能迁移到新一代模型时，先测试删除指令是否能改善输出，再考虑增加更多指令。

9. 回声式推理指令

检测： 行为指令要求模型“展示思维链”“转录推理过程”或“逐步解释内部思考”。 解决方案： 改为要求给出结论并简要说明理由（例如：“说明等级，并用一句话解释原因”）。自适应思考如今会在内部处理这些内容，因此手动搭建 CoT 脚手架已不再推荐；在 Claude Fable 5 上，要求回声式推理可能触发推理提取拒绝分类器，直接导致请求失败。

行为指令

阶段 1：捕捉意图
  1. 确定技能应执行的操作、触发时机以及预期的输出格式。
  2. 确定目标受众：谁会触发此技能，他们通常会怎么说？
  3. 如果用户的请求含糊不清：就领域、触发场景和预期输出格式提出 1-2 个澄清问题。不要继续编写通用技能。
阶段 2：调研（按需）
  1. 如果领域不熟悉：先调研，再起草。
    • 使用网页搜索了解领域术语、框架和命名模式。
    • 如果技能与特定项目有关，则探索代码库。
    • 找出 15-30 个符合从业 15 年者检验的专业术语。
    • 找出 5-10 个已有公认名称的领域反模式。
阶段 3：起草 SKILL.md

  1. 编写 YAML 前置元数据，使用双重语域描述（约 100 个词，语气积极有力，以第三人称撰写，说明是什么以及何时使用）。

    • 同时包含专家术语和自然语言触发场景。
    • 明确列出排除项（“请勿用于……”）。
    • 积极触发——当前模型触发不足。加入同义词、边缘情况和相邻场景。
    • 平台限制（Claude Code，2026）：描述最多 1,024 个字符。描述与 when_to_use 合计会在约占上下文窗口 1% 的技能列表预算内截断至 1,536 个字符——最少使用的技能会最先被丢弃，因此不要依赖填充内容。使用 when_to_use 扩展描述正文以外的触发范围。
    • 其他有用的前置元数据：disable-model-invocation、user-invocable、allowed-tools、model、effort、context: fork（在分叉的子 Agent 中运行技能）、paths（按 glob 限定激活范围）。SKILL.md 遵循 Agent Skills 开放标准（agentskills.io）——自定义斜杠命令已合并到技能中。

  2. 编写专家词汇内容（15–30 个术语，分为 3–5 组）。

    • 放在行为指令之前。原因：词汇能在执行开始前强化路由信号。
    • 按子领域分组，每组 3–8 个术语。
    • 对具名框架注明提出者，例如：“熔断器（Nygard）”，而不只是“熔断器”。
    • 对每个术语应用 15 年从业者测试。删除任何不符合要求的术语。

  3. 编写反模式检查清单（5–10 个具名模式）。

    • 放在行为指令之前。原因：模型会先检查问题，再进行常规执行。
    • 每个模式都需要：名称及来源、检测信号、解决步骤。
    • 有成熟名称时请使用，例如：“琐事争论（Parkinson）”，而不是“在细节上花太多时间”。

  4. 编写行为指令（使用命令式语气，按顺序排列，并包含条件判断）。

    • 使用祈使动词：“扫描”“分类”“输出”，而不是“你应该尝试……”。
    • 为每个步骤编号。使用 IF/THEN 表示分支逻辑。
    • 对不明显的步骤说明原因。原因：模型可以将原则泛化到边缘情况，而僵化规则只能覆盖字面匹配。
    • 从反模式扫描步骤开始。
    • 保持正文精简。Claude 4.5+/5 能可靠地遵循简短指令——枚举所有情况并为每一步加上保留语气，是为更旧、更弱的模型调整的做法，可能降低当前模型的输出质量。迁移技能时，先测试删除指令是否能改善结果，再考虑添加指令。
    • 切勿要求模型复述或转录其内部推理（“展示你的思维链”“逐步解释你的思考过程”）。应要求模型给出结论，并简要说明理由——在 Claude Fable 5 上，要求复述推理可能触发推理提取拒绝分类器。

  5. 编写输出格式规范。

    • 定义必需字段、结构和模板。
    • 优先使用结构化格式（YAML、表格、编号列表），而非散文。

  6. 编写 3–5 个不同的示例（错误做法与正确做法，或输入到输出）。

    • 覆盖不同情况，至少包括一个棘手案例。
    • 将最具代表性的示例放在最后。原因：近因偏差会让最后一个示例对输出产生最强影响。

  7. 编写“此技能能回答的问题”部分（8–15 个自然语言查询）。

    • 放在文件末尾。原因：检索锚点受益于上下文末尾的注意力（U 形曲线）。
    • 使用用户实际会输入的确切措辞，包括随意、不精确的说法。
    • 这些查询同时充当检索锚点、自我文档和测试用例。
阶段 4：参考文件（有条件）

  1. 如果技能需要大量参考内容（模式库、扩展示例、检查清单、评估标准）：

    • 在 references/ 目录中创建文件。
    • 每个参考文件不超过 300 行。
    • 在 SKILL.md 中明确说明何时阅读每个参考文件。

  2. SKILL.md 总行数保持在 500 行以内。如果超过 500 行：将内容移至 references/。

阶段 5：库元数据
  1. 在 YAML frontmatter 中包含库元数据：名称、版本、领域标签和兼容性说明。
阶段 6：验证与打包
  1. 根据上方的反模式检查清单扫描生成的 SKILL.md，并修复所有违规项。
  2. 如果有子 Agent：使用真实用户可能会输入的 3-5 条提示进行测试（口语化、不精确、不使用正式术语）。
  3. 打包技能：验证结构、压缩为 zip，并使用 present_files 进行安装。
  4. 保存到 library/skills/ 并更新 index.json。
  5. 将创建记录写入 usage-log.jsonl。

输出格式

主要输出是一个完整的技能目录：

skill-name/
  SKILL.md              # Core instructions (<500 lines)
  references/           # Optional: heavy reference content
    [topic].md          # Each file <300 lines

SKILL.md 内部结构（按此顺序）：

  1. YAML frontmatter（name、description、可选的 when_to_use/allowed-tools/model/effort/context/paths）
  2. 专家词汇载荷
  3. 反模式检查清单
  4. 行为说明
  5. 输出格式
  6. 示例（错误 vs 正确）
  7. 此技能可以回答的问题

示例

示例 1：错误 vs 正确的描述

错误：

description: "Helps with code review."

单一语域。不够积极。没有专家术语。没有触发场景。没有排除项。这个技能几乎不会被触发，即使触发了，也只会生成泛泛的内容。

正确：

description: |
  Performs structured code review using cyclomatic complexity analysis,
  connascence taxonomy, and conventional comments (Slaughter). Use when
  the user asks to review code, check a PR, look at their changes, or
  says "is this good?" about code -- even if they don't mention "review."
  Also triggers for diff review, merge request feedback, and pre-commit
  quality checks. Do NOT use for architecture decisions (use Decision
  Advisor) or writing new code (use Code Generator).

双重语域。积极主动。专家术语可引导至深入知识。口语化触发语确保技能激活。明确的排除项可防止误触发。

示例 2：错误 vs 正确的词汇载荷

错误：

## Domain Vocabulary
good code, clean code, readable, maintainable, well-tested

使用每篇博客文章都会出现的通用术语。引导至入门内容。无法通过 15 年从业者测试：资深工程师不会对同行说“好代码”。

正确：

## Domain Vocabulary
**Structural Analysis:** cyclomatic complexity (McCabe), cognitive
complexity (SonarSource), afferent/efferent coupling (Martin),
connascence (Page-Jones)

**Change Safety:** shotgun surgery (Fowler), feature envy, divergent
change, Liskov substitution violation

**Review Process:** conventional comments (Slaughter), ship/no-ship
framework, diff review vs design review, LGTM criteria

按集群整理的精准术语。标注具名框架及其提出者。引导至代码审查专业知识，而非泛泛建议。每个术语都通过 15 年从业者测试。

关于打包的明确说明

此技能使用 Anthropic 原生的 .skill 打包机制（validate、zip、present_files）进行交付。它不会调用内置的技能创建器，而是以 Forge 综合研究中的、基于研究的原则取代内置方法：

  • 词汇路由（精准术语可将输出引离通用训练分布的中心——“嵌入集群激活”在此处是有用的工作模型，而非已证实的机制）
  • U 形注意力优化（词汇前置，检索锚点后置；当前前沿模型的上下文中段退化程度远低于较早的基准测试，但前后置仍是更稳妥的默认做法）
  • 负向约束引导（反模式可推动输出越过分布中心）
  • 渐进式披露（三级上下文加载；Claude Code 会将技能描述截断至 1,536 个字符，并在自动压缩后为每个已调用技能保留约 5K 个 token——优先呈现重要内容）
  • 少样本示例的优势（3-5 个多样化示例胜过冗长说明；超过此数量后收益递减）

此技能中的数值范围（15-30 个词汇术语、3-5 个集群、5-10 个反模式、约 100 词的描述、8-15 个触发问题）是 Forge 为实现全面覆盖而不失精炼所制定的设计标准，并非经过测量的阈值。SKILL.md 少于 500 行的上限则是经 Anthropic 指南验证的要求。精简研究（含引用和适用范围）请参阅 ./references/skill-principles.md，带注释的黄金标准示例请参阅 ./references/skill-template.md。

此技能解答的问题

  • “为 [领域/任务] 创建一项技能”
  • “构建一项能够 [执行 X] 的技能”
  • “我希望 Claude 在 [触发条件] 时始终 [执行某种行为]”
  • “制作一个可复用的 [领域] 助手”
  • “如何创建一项好的技能？”
  • “将此工作流转化为一项技能”
  • “我需要一项用于 [任务] 的技能”
  • “为我构建一个自定义 [领域] 助手”
  • “为 [任务] 创建一个提示词模板”
  • “将其打包为一项技能”
  • “怎样的技能才有效？”
  • “我的技能没有触发，该如何修复？”
  • “SKILL.md 应该如何组织？”

评论

支持 Markdown