SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场skill-creator

skill-creator

智能体与模型

查看项目

更新于 10-15 14:59

技能介绍

用途

skill-creator 用于指导智能体技能（agent skill）的编写、审查与校验，面向 Capgo skills 仓库及类似仓库。其目标是写出能在正确时机被加载、只教授模型尚不了解的知识、并能证明自身结果的技能。

何时使用

触发条件：

  • 用户创建技能目录，或要求改进、审查、拆分现有技能。
  • 某个技能触发过频、过少，或与同类技能冲突。
  • bun run lint-skills 失败，或技能需要注册到插件或市场。
  • 用户想为某个技能添加 skillgrade 评估。

不适用场景：

  • 用户编写应用文档、README、变更日志或营销文案。
  • 用户编辑的不是技能，而是库或插件源码。

参考索引

仅在相关主题出现时才加载对应参考文件：

  • references/repo-layout.md：在本仓库中添加、重命名或注册技能，镜像到 plugins/，或阅读 lint 错误时加载。
  • references/authoring-patterns.md：编写正文时加载，涉及触发设计、参考索引、陷阱、验证、版本标签、子智能体技能、内联快照。

操作流程

  1. 界定技能范围：用一句话写清“当……时加载此技能，以便智能体能够……”。列出可能同样匹配的同类技能，每个都成为负向触发条件。若技能覆盖两个不相关的工作流则拆分；若会变成一段式存根则合并。在真正的判断点（范围、受众、优先哪个产品）询问用户，不要询问可从仓库读到的东西。

  2. 编写 frontmatter：name 为小写、连字符、与文件夹名一致；description 说明做什么，并用“Use when”列出症状、API、文件名、错误字符串，用“Do not use for”列出排除场景并点名同类技能。description 是路由器唯一看到的文本，需放入具体触发词，保持一行且不超过 1024 字符（lint 会强制这两点）。可选的 when_to_use 会追加到 Claude Code 的技能列表中，合并文本在 1536 字符处截断，因此关键用例要放前面；其他智能体会忽略它，所以核心触发词绝不能移出 description。allowed-tools 仅在技能运行内联命令时使用，保持最小且只读。

  3. 编写精简正文：目标少于约 250 行，按以下顺序组织——一行目的加版本行；## When to Use（TRIGGER 要点与 Do not use when 列表，按名称指向同类技能，lint 要求此标题）；## Reference Index（每个文件及何时加载的表格，注明“仅在相关主题出现时才加载参考文件”）；## Procedure（编号步骤，先检查再编辑，侵入性改动前先报告发现）；## Traps（非显而易见的失败，跳过模型已知的基础）；## Verification（证明成功的精确命令或检查）；## Error Handling（精确错误字符串映射到修复方法）。密集表格、长代码和按主题的深度内容移入 references/<topic>.md，只一层深；脆弱或重复的逻辑放入 scripts/。

  4. 核实一切：对照源码或官方文档验证每个命令、标志、配置键和 API，优先使用包的 --help、类型定义或仓库而非记忆。为时效性事实标注版本（如“Capacitor 8.5+”“Xcode 27”“CLI 8.77”）。目标可能较旧时用特性检测来门控可选行为。无法核实的事实写“check current docs”，不要猜测。列出不存在但常被幻觉出的命令。

  5. 匹配命令上下文：技能正文使用标准 npm / npx 示例；Capacitor 和 Capgo CLI 示例使用 npx ...@latest；bun / bunx 仅用于本仓库自身的开发和 CI 命令，或 Bun 专属技能。当技能编辑其他仓库时，告知智能体阅读该仓库的说明并遵循其包管理器策略。

  6. 保留密钥：当技能编辑用户文件时，告知智能体除非被要求，否则绝不用占位符替换用户提供的令牌、密钥、证书或密码。占位符仅用于新的通用示例。除非用户要求，不要建议轮换密钥。

  7. 注册与校验（本仓库）：遵循 references/repo-layout.md——在 skills/ 中建立规范文件夹、metadata.json、在 package.json 的 skills 中登记条目、通过插件文件夹加 .claude-plugin/marketplace.json 暴露，然后运行 bun run sync-skills 和 bun run lint-skills。

  8. 行为不得回退时添加评估：使用 skillgrade（eval.yaml + graders/）。结构优先用确定性 grader，定性判断才用 LLM rubric。用 bun run lint-skills-skillgrade 运行，或在 lint 期间设置 ENABLE_SKILLGRADE=1 并提供 API key。

陷阱

  • 模糊的 description（“Helps with X”）永远不会触发；贪婪的（“Use for anything about mobile”）会抢走同类技能的请求。
  • 像“see references/”这样没有加载条件的索引条目会让智能体要么全读要么不读，务必写明何时加载。
  • 过时事实比结构老化更快，把版本行放在顶部，让审查者知道要重新核实什么。
  • 编辑 plugins/<plugin>/skills/ 下的镜像副本是错误的，应编辑规范的 skills/<name>/，然后同步。
  • 内联 !command`` 快照每次加载都会运行，需用 fs.existsSync 守卫、快速、输出简短且只读。

验证

  • bun run lint-skills 通过：检查名称与文件夹一致、description 长度、## When to Use 标题、metadata.json 有效、市场暴露、镜像字节一致。
  • wc -l skills/<name>/SKILL.md 约 250 行或更少，且 references/ 中每个文件都在 Reference Index 中列出。
  • 对技能中每个命令 grep，与工具的 --help 或源码匹配。
  • 心理路由测试：三个应触发该技能的提示确实触发，每个同类技能各一个提示不触发。

错误处理

  • <skill>: name "<x>" does not match folder name → 让 frontmatter 的 name 等于目录名。
  • <skill>: description exceeds 1024 characters → 删减填充内容，保留具体触发词和负向子句。
  • <skill>: missing usage guidance → 添加 ## When to Use 标题。
  • <skill>: missing metadata.json / invalid metadata.json → 创建或修复 JSON（见 references/repo-layout.md）。
  • claude marketplace: skill "<x>" is not exposed by any plugin → 创建 plugins/<plugin>/skills/<x>/，然后运行 bun run sync-skills。
  • mirrored skills: ... (run bun run sync-skills) → 运行 bun run sync-skills，绝不手工编辑镜像。
  • <plugin>: unknown skill "<x>" → 插件文件夹没有匹配的 skills/<x>，创建规范技能或删除该文件夹。