no-mistakes如何把SKILL.md装进Claude Code：agent技能安装原理

no-mistakes如何把SKILL.md装进Claude Code：agent技能安装原理

【免费下载链接】no-mistakesgit push no-mistakes项目地址: https://gitcode.com/GitHub_Trending/no/no-mistakes

no-mistakes 是一个本地 git 门禁：你git push no-mistakes，它就在隔离 worktree 里跑完 review、test、lint、docs、push、PR、CI 全流程。而它最巧妙的产品设计，是把一份 SKILL.md 装进 Claude Code 等编码 agent 的技能目录，让 agent 直接学会/no-mistakes斜杠命令。本文带你拆解 agent 技能安装的完整原理。

SKILL.md 是什么：agent 的"技能说明书"

Claude Code 支持"技能（Skill）"机制：只要某个目录下存在一份带 YAML frontmatter 的SKILL.md，agent 启动时就会扫描到它，把里面的说明当作可执行的指令集。

no-mistakes 的技能文件由三部分构成（见 skills/no-mistakes/SKILL.md）：

• name: no-mistakes—— 技能目录名，也是 agent 暴露出来的斜杠命令名/no-mistakes
• description—— 触发描述，是 agent 决定是否加载技能的最关键字段，里面写满了"gate、ship、validate、push safely"等触发词
• 正文—— 教 agent 如何用no-mistakes axi命令族驱动门禁、如何读懂输出、遇到 gate 停顿该怎么做决策

frontmatter 由代码动态拼装，见 internal/skill/skill.go 的Markdown()函数：name、description、user-invocable: true三个字段加上正文，确定性输出。

安装三步走：单一事实源 → 渲染 → 落盘

技能安装的核心逻辑在 internal/skill/install.go。整个过程分三步：

第 1 步：单一事实源（Single Source of Truth）技能内容不是一份手写死的 Markdown，而是由 internal/skill/skill.go 这个 Go 包在内存中渲染。包注释写得很直白：它是技能身份和SKILL.md正文的"唯一事实源"。这样 CLI 的状态页、仓库里的公开技能文件、安装到用户目录的副本三者永远一致。

第 2 步：确定安装目录init命令调用InstallUser()，写入两个用户级技能根目录（见 internal/skill/install.go 的InstallBases）：

第 3 步：幂等写入Install()对每个基础目录执行MkdirAll+WriteFile。重跑init会用相同内容覆盖旧文件，天然完成"刷新"。一个细节很值得学：如果你把~/.claude/skills软链到~/.agents/skills（或反过来），普通MkdirAll会撞到悬空符号链接报错——no-mistakes 专门实现了resolveThroughSymlinks逐段解析路径（internal/skill/install.go），带循环检测，让软链布局也能透明工作。

触发这一切的入口是no-mistakes init：创建本地裸仓库门禁、配好 remote 后，顺带调用skill.InstallUser()并把结果打印成一行提示（见 internal/cli/init.go）：

skill /no-mistakes installed for agents at user level

安装发生在用户级而非仓库级——一次安装，所有仓库通用。旧版本曾把技能副本 vendor 进每个仓库，现在init发现旧副本只会提示你删掉（Vendored()只读不写，见 internal/skill/install.go）。

装完之后：/no-mistakes 如何生效

SKILL.md 落盘后，下次打开 Claude Code，agent 扫描~/.claude/skills/发现这个技能，就多出一个/no-mistakes命令。它支持两种调用模式（正文由 internal/skill/skill.go 渲染）：

• 仅校验：裸敲/no-mistakes，对已提交的变更跑完整流水线
• 先做后验：/no-mistakes <任务>，agent 先完成开发、提交到特性分支，再把任务原话作为--intent驱动门禁

agent 拿到的是机器可读的 TOON 输出，按"校验—决策"循环推进；碰到需要人工判断的 gate，就升级给你 approve / fix / skip。

防漂移：genskill 生成器 + CI 校验

一个常见隐患是：仓库里的技能文件、安装到用户目录的副本、代码里的模板三者慢慢"漂移"。no-mistakes 用一个生成器堵住它：

• cmd/genskill/main.go 把skill.Markdown()渲染成仓库里的skills/no-mistakes/SKILL.md
• go run ./cmd/genskill --check在 CI 里做 diff 校验，一旦提交的文件落后于生成器就失败
• 测试 internal/skill/skill_test.go 则断言 frontmatter 三字段齐全、---正确闭合、关键正文快照存在

三者合起来保证：你在init时装进 Claude Code 的内容，和仓库里公开的那份逐字节相同。

快速核对清单：验证你的技能装好了

1. 运行no-mistakes init，看到skill /no-mistakes installed for agents at user level
2. 确认~/.claude/skills/no-mistakes/SKILL.md存在（Claude Code）或~/.agents/skills/no-mistakes/SKILL.md存在（其他 agent）
3. 重启 Claude Code，输入/no-mistakes能唤起命令
4. 命令行为异常时跑no-mistakes doctor，它会报告配置问题

更多细节可查阅官方文档 docs/src/content/docs/reference/cli.md 和 docs/src/content/docs/guides/agents.md。

一句话总结：no-mistakes 的技能安装 = 代码内单一事实源 + 确定性渲染 + 幂等写入用户级双目录 + CI 防漂移，四步把一份 SKILL.md 变成 Claude Code 里的/no-mistakes斜杠命令。

【免费下载链接】no-mistakesgit push no-mistakes项目地址: https://gitcode.com/GitHub_Trending/no/no-mistakes