Agent Skills 工程化实践 13：剩下 10 个 Skills 为什么不能和稳定主流程混为一谈

先看稳定性，而不是先看名字

上游当前共有 35 个面向使用者的 SKILL.md：25 个 promoted Skills 会进入 Claude Code plugin；4 个位于 skills/misc/，公开但上游明确表示较少使用；6 个位于 skills/in-progress/，仍处于 beta，可能改变或删除，也不进入 plugin。

这一篇补齐后 10 项。它们有些非常实用，但适用面更窄，或者稳定性还不足。安装与写博客时都应保留这个标签，不能因为文件已经公开，就把它们描述成主流程承诺。

Misc：四个窄而具体的工具

`git-guardrails-claude-code`

触发方式：Model-invoked；Claude Code 专用。 典型请求：

为当前项目设置 Claude Code git guardrails，并保留已有 hooks。

它安装 PreToolUse hook，拦截 git push、reset --hard、clean -f、branch -D、checkout . 与 restore . 等危险命令。输出包括 executable hook、合并后的 .claude/settings.json，并用模拟 JSON 验证拒绝路径返回 exit code 2。

它不是通用 Git permission system，也不替代 branch protection、review 与最小权限。最大风险是覆盖已有 settings；正确实现必须 merge hooks，而不是重写整个文件。

上游 Skill：git-guardrails-claude-code

`migrate-to-shoehorn`

触发方式：Model-invoked；只用于 TypeScript tests。 典型请求：

把 user-service.spec.ts 的 fixtures 从 as unknown as 迁移到 @total-typescript/shoehorn。

它把测试中的 as Type 或 as unknown as Type 改为 fromPartial / fromAny。fromPartial 适合“只提供部分字段，但仍希望剩余内容参与 type-check”；fromAny 只适合故意构造错误类型的 negative case。

不能把它带进 production code，也不能机械替换所有 assertion。迁移前要理解 fixture 为什么不完整，迁移后运行相关测试与 typecheck，确认没有把真实类型错误藏起来。

上游 Skill：migrate-to-shoehorn

`scaffold-exercises`

触发方式：Model-invoked；面向上游作者的课程目录约定。 典型请求：

按这份课程计划 scaffold exercises，并确保 ai-hero-cli lint 通过。

它生成 exercises/XX-section/XX.YY-exercise/{problem,solution,explainer} 结构，补齐非空 readme.md、必要的 main.ts，并运行 pnpm ai-hero-cli internal lint 后 commit。

它不是通用教学脚手架。目录、variant 与 linter 都与 AI Hero 课程体系绑定；普通项目如果只借用名字而没有同样 contract，生成物反而会制造错误约定。

上游 Skill：scaffold-exercises

`setup-pre-commit`

触发方式：Model-invoked；适合 JS/TS repo。 典型请求：

为这个 npm repo 配置 pre-commit checks，复用现有 Prettier 和 scripts。

它根据 lockfile 与 package.json 配置 Husky、lint-staged、Prettier，并在 repo 已有对应 scripts 时加入 typecheck/test。输出通常包括 .husky/pre-commit、.lintstagedrc、devDependencies，以及必要时才创建的 Prettier config。

如果 repo 没有 typecheck 或 test，它应该省略并明确说明，不能捏造命令。完整 test suite 放在 pre-commit 可能明显拖慢提交；大型 repo 应把重检查移到 pre-push 或 CI，只在 pre-commit 保留快速、与 staged files 相关的反馈。

上游 Skill：setup-pre-commit

In Progress：六个仍可能改变的 beta Skills

`loop-me`

触发方式：User-invoked。 它把 recurring work 或生活流程 grill 成 implementer 不必继续追问的 workflow spec：

/loop-me 每周把客户反馈整理成一份产品决策 brief

它读取 idea，或从 NOTES.md 中寻找候选，产出/更新 workflows/*.md 与 workspace terminology。它写的是 workflow contract，不负责实现 scheduler 或 automation。

重要原则是 push checkpoints right：不要每一步都要求人确认 raw output，而要把自动处理尽量向后推进，只在 decision-ready brief 处让人接管。AI、schedule 与 checkpoint 都不是默认项，只有真实需求证明需要才加入。

上游 Skill：loop-me

`writing-fragments`

触发方式：User-invoked；写作 explore 阶段。 典型调用：

/writing-fragments research/agent-skills-notes.md

它扩大素材空间，收集 sentences、claims、vignettes、quotes、half-thoughts 与 leading words；输出是一份 H1 加 horizontal rules 分隔的异质 raw pile，并持续 append。

它禁止 outline、phase 与 article structure，也不负责写成成文。每次继续前必须完整重读文件，保留人的手工修改；只有用户明确要求时才能局部编辑已有 fragment。

上游 Skill：writing-fragments

`writing-beats`

触发方式：User-invoked；写作 exploit 路线之一。 典型调用：

/writing-beats research/agent-skills-notes.md，输出到 drafts/agent-skills.md

它把固定 raw pile 组织成 choose-your-own-adventure 式 beats journey。每轮只给 2–3 个当前 reachable 的 next beats；用户选择后只写一个 beat，再从新的 grounded context 继续。

它不会预写后续 beats，也不应该把所有素材强塞进文章。一个 concept 在前文没有 grounded，后续 beat 就不能依赖它。它与 writing-shape 是两条替代 exploit 路线，通常二选一。

上游 Skill：writing-beats

`writing-shape`

触发方式：User-invoked；另一条写作 exploit 路线。 典型调用：

/writing-shape research/agent-skills-notes.md，输出到 drafts/agent-skills.md

它先完整读取只读 raw pile，确认 reader prerequisites，再给出 2–3 个 opening；之后每次只追加一个由用户同意的 block，并显式讨论该段应该采用 prose、list、table、callout 还是 code。

素材缺口必须被指出，不能暗自发明例子。用户决定何时完成；Skill 不负责 publishing 与 frontmatter。相比 writing-beats，它更关注逐段 shape 与形式选择，而不是 reader journey 的 next beat。

上游 Skill：writing-shape

`claude-handoff`

触发方式：User-invoked；Claude CLI 专用。 典型调用：

/claude-handoff 下一任务只处理登录回归测试

它生成 redacted handoff prompt，并通过 claude --bg --name "<name>" "<summary>" 直接启动新的 Claude Code background agent。它依赖 claude --bg 与 claude agents。

它不同于 promoted handoff：后者只写 portable temp document，可以交给不同 harness 或人；claude-handoff 会直接启动 Claude background agent。摘要仍应引用现有 artifacts，不复制全文，也不能包含 secrets 或 PII。

上游 Skill：claude-handoff

`setup-ts-deep-modules`

触发方式：User-invoked；TypeScript repo 专用。 运行：

/setup-ts-deep-modules

它使用 dependency-cruiser 强制 package root files 作为 public entry points，subfolders 作为 private implementation/tests。输出包括合并后的 .dependency-cruiser.cjs、lint:boundaries、示例 package、packages README 与 Agent pointer。

验证必须真实经历三步：clean pass；临时 deep import 失败；还原后再次 pass。它不能覆盖已有 dependency-cruiser config，不修改 tsconfig/path aliases，也不主张 giant barrel。它解决 package encapsulation，不替代 package layering 与 domain design。

上游 Skill：setup-ts-deep-modules

一份稳妥的采用原则

先从 25 个 promoted Skills 里选择与你的 failure modes 直接相关的 5–8 个；
misc 只在 repo 与工具前提完全匹配时安装；
in-progress 必须按 beta 管理，固定 commit，并准备承担行为变化；
selective install 要检查 wrapper 与 primitive 的依赖；
每个 Skill 的成功标准是留下可验证 artifact，不是“Agent 说已经执行”。

这样，35 个 Skills 才是一张能力地图，而不是一份必须全部启用的 checklist。

来源与版本

Misc 状态：skills/misc/README.md
In-progress 状态：skills/in-progress/README.md
参考分支：main · 核验 commit：8b78b53 · 核验日期：2026-08-14

来源记录 https://github.com/mattpocock/skills 参考分支：main 参考 commit：8b78b531ab96 核验日期：2026/8/14