adding-a-skill

添加技能

在此仓库中开发公开技能时，请使用本文档。普通技能变更放在 skills/<skill-name>/ 中；仅供仓库使用的指导放在 .agents/skills/ 下。

首先判断技能类型

• 普通公开技能： 在 skills/<name>/ 下创建包含 SKILL.md 的普通文件夹。这是最常见的情况。@agent-native/skills 会从 BuilderIO/skills@main 动态发现这些技能，因此只需让 npx @agent-native/skills@latest add --skill <name> 生效时，无需修改框架注册表。
• 指令式技能： 普通技能，可选地在用户传入 --update-instructions 时写入一行始终生效的托管 AGENTS.md / CLAUDE.md。这类技能需要额外修改框架；请参阅下文的 “托管指令块”。
• 应用支持 / MCP 技能： 注册托管/本地 MCP 服务或使用框架自有安装行为的技能。这些不是普通公开技能；请检查 ../agent-native/framework/packages/core/src/cli/skills.ts 和 ../agent-native/framework/packages/skills/src/built-in-apps.ts。
• 计划技能： visual-plan 和 visual-recap 在此仓库与 ../agent-native/framework 之间存在生成/同步副本。不要将它们视为独立的文档文件夹。
• Rewind： 其规范的 SKILL.md 由 Agent Native 生成，因为相关指令和本地 Screen Memory 工具共用一份隐私约定。 请将面向用户的 README 保留在此处；使用 npm run sync:agent-native-skills 生成技能，而不要手动编辑。

普通公开技能检查清单

1. 创建或更新 skills/<skill-name>/SKILL.md。

2. 如果该技能应出现在公开目录中，则添加 skills/<skill-name>/README.md。本仓库特意使用 README 作为公开技能页面。

3. 如果集合定位发生变化，请更新根目录的 README.md、 .codex-plugin/plugin.json、.claude-plugin/plugin.json 和 package.json 中的描述。

4. 保持技能简洁。SKILL.md 中只放必要的 Agent 指令；除非额外文档能直接支持该技能，否则不要添加。

5. 运行以下命令进行验证：

   python3 /Users/steve/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/<skill-name>
   

6. 在声称 CLI 路径可用之前，先在本地冒烟测试安装发现：

   node ../agent-native/framework/packages/skills/dist/cli.js add --copy . --skill <skill-name> --client codex --scope project --dry-run --json
   

7. 运行 npm run check。如果与变更无关的情况下检查因 visual-plan / visual-recap 同步而失败，请明确报告这一点，不要随意改写这些技能。

@agent-native/skills 安装路径

对于普通公开技能，安装路径是动态的：

• ../agent-native/framework/packages/skills/src/index.ts 设置 DEFAULT_SKILLS_SOURCE = "BuilderIO/skills"。

• 它会物化该仓库，通过 resolveSkillsRoot 读取插件清单，并通过 discoverSkills 发现所有 skills/*/SKILL.md。

• 因此，只需在 skills/<name>/ 下新建文件夹，即可支持：

  npx @agent-native/skills@latest add --skill <name>
  

除非技能由应用支持或需要自定义安装行为，否则无需修改 @agent-native/core 内置注册表。

托管指令块

如果技能需要通过 --update-instructions 影响 AGENTS.md / CLAUDE.md，请更新框架封装：

• 在 ../agent-native/framework/packages/skills/src/index.ts 中的 instructionContentForSkill(skillName) 内添加一行简洁说明。

• 在 ../agent-native/framework/packages/skills/src/index.spec.ts 中添加或更新测试。

• 运行：

  pnpm --filter @agent-native/skills test -- src/index.spec.ts --runInBand
  

此方式适用于持久行为规则，例如 quick-recap、efficient-fable、 stay-within-limits，以及可能适用于文档优先行为的 read-the-damn-docs。

应用支持或 MCP 技能

如果技能需要托管工具、身份验证、MCP 注册、本地文件模式或特殊安装标志，请先检查框架再进行编辑：

• ../agent-native/framework/packages/core/src/cli/skills.ts
• ../agent-native/framework/packages/skills/src/built-in-apps.ts
• ../agent-native/framework/packages/skills/src/sync-with-core.spec.ts

确保核心和独立的 @agent-native/skills MCP 描述符保持同步。

Agent Native 技能同步注意事项

visual-plan、visual-recap 和 rewind 比较特殊：

• 框架中包含规范副本／生成副本和 Plan 市场包。
• 此仓库的 npm run check 会比较这些副本，若存在差异，即使与新建的普通技能无关，也可能导致检查失败。
• 有意修改 Plan 技能时，请使用框架同步路径，而不要手动编辑生成副本。在框架中搜索 sync-plan-marketplace、sync-workspace-skills 和 skills.sync.spec.ts。
• Rewind 的 SKILL.md 由 packages/core/src/cli/skills-content/rewind-skill.ts 生成。其公开 README 会作为叠加层保留。普通副本安装程序无法配置 Rewind 的本地 MCP 连接；公开设置文档必须使用 @agent-native/skills 或 @agent-native/core。
• 发布整个 skills/ 目录的插件清单必须包含一条始终生效的设置指令：在 Clips 缺失时调用 Rewind，会在打开官方安装流程前请求许可，绝不会静默安装或启用捕获功能，并且在 Core 配置本地 MCP 连接且 screen_memory_status 成功之前，Rewind 始终不可用。

最终报告

完成技能更改时，请告知用户：

• 哪些技能文件发生了更改。
• @agent-native/skills 的动态安装发现功能是否足够。
• 是否添加了框架托管指令的更改，或是否有意留待后续处理。
• 哪些验证命令通过或失败，包括与此无关的 Plan 同步失败。