xtl
Back to writing

/ Skills

[Skills-07] Encoding Repetitive Work: Git Guardrails, Scaffolds, and Personal Workflows

Distilling four miscellaneous and two personal skills for Git safety, hooks, migrations, exercise scaffolds, editing, and Obsidian.

2 minSkill · Git · Tooling · Testing

这一组不是作者主推的通用工程 flow，而是四个 misc 工具和两个绑定个人环境的 skill。它们依然值得读，因为展示了何时应该把稳定、重复、易错的操作沉淀为脚本化能力，以及哪些细节不应该直接复制到别人的项目。

覆盖：git-guardrails-claude-code、migrate-to-shoehorn、scaffold-exercises、setup-pre-commit、edit-article、obsidian-vault。

1. git-guardrails-claude-code：在执行前阻止危险命令#

这个 skill 为 Claude Code 配置 hook，在 shell command 真正执行前解析并拦截高风险 Git 操作，例如：

  • git push 和变体；
  • git reset --hard；
  • git clean；
  • 强制删除 branch；
  • 其他会重写远端或大量丢弃本地工作的命令。

核心设计是 fail closed：无法可靠判断命令是否安全时，宁可阻止并解释，也不静默放行。脚本必须考虑 shell 包装、路径前缀、多个参数和常见变体，不能只做脆弱的字符串相等比较。

Guardrail 不是 Git 权限系统。它保护的是 Agent 会话中的误操作，不能替代 branch protection、remote 权限和备份。真正需要执行危险操作时，应由人明确改变策略，而不是让 Agent 寻找绕过方式。

2. setup-pre-commit：把快速反馈放在 commit 入口#

这个 skill 检测 package manager 和已有 scripts，安装 Husky、lint-staged、Prettier，并建立 pre-commit 顺序：

lint-staged：只格式化 staged 文件
  -> typecheck：验证全局类型
  -> test：运行项目测试

如果项目没有 typecheck 或 test script，就省略对应命令并告知用户，而不是凭空发明。已有 Prettier 配置优先，只有缺失时才创建默认值。

最后一次 commit 本身就是 smoke test：新 hook 必须在真实 Git 路径里成功。可迁移原则是先发现项目约定，再生成最小增量，不用统一模板覆盖已有工具链。

3. migrate-to-shoehorn：机械迁移也需要语义验证#

该 skill 把测试中的 TypeScript as assertion 迁移到 @total-typescript/shoehorn。典型目标是避免构造巨大完整对象，只为测试填少数字段，同时让这种“测试替身不完整”变得显式。

迁移步骤包括：

  1. 识别 test files 与 assertion 模式；
  2. 安装并遵守当前 package manager；
  3. 用 fromPartial 等 helper 替换适合的 assertion；
  4. 保持原测试意图和 runtime value；
  5. 运行 typecheck 与 tests；
  6. 对不适合机械替换的 union narrowing、brand 或 deliberate unsafe cast 单独处理。

重点是不要做盲目全局替换。语法相似的 as 可能承担完全不同的类型语义。

4. scaffold-exercises：把课程目录约定变成生成流程#

这个 skill 创建课程练习所需的 section、problem、solution 和 explainer 结构，并以现有课程为 prior art，确保生成结果通过 lint。

它会先扫描命名、编号、export、测试和 metadata 约定，再创建新目录；每个问题需要可运行起点、目标说明、solution 和解释材料。生成之后运行 repo 自己的检查，而不是只确认文件存在。

脚手架 skill 的价值不在 mkdir，而在封装隐性组织知识：哪些文件成套出现、编号如何连续、哪个 index 需要更新、平台如何发现练习。

5. edit-article：先处理信息 DAG，再润色句子#

这是 personal skill，流程只有两层：

  1. 按 heading 划分 section，识别每节主张，把信息依赖看作 DAG，先确保读者在使用概念前已经获得概念；向用户确认结构；
  2. 逐节重写 clarity、coherence 和 flow，并将 paragraph 限制在最多 240 characters。

它最可迁移的部分是“结构先于文风”。一篇文章如果概念顺序错误，局部润色只会让错误结构读起来更顺。240 characters 则是作者个人偏好，不应视作普遍写作定律。

6. obsidian-vault：个人 skill 要显式写环境假设#

这个 skill 固定了作者自己的 vault 路径、flat root 布局、Title Case 文件名、[[wikilinks]] 和 * Index.md 聚合方式。它支持：

  • 按文件名或正文搜索；
  • 创建带相关 wikilink 的 note；
  • 通过反向搜索找 backlinks；
  • 更新 topic index；
  • 遵守编号序列。

它无法直接搬到别人的机器，因为路径和组织偏好都是个人的。真正可复用的是模板：把 storage location、naming、linking、indexing 和 search commands 写成明确契约。个人 skill 不需要假装通用，反而应把局限写清楚，避免 Agent 在错误目录操作。

7. 何时把一次操作升级为 skill#

这组六个案例给出一个实用判断：

  • 操作会重复；
  • 顺序错误会带来明显成本；
  • 项目或个人有稳定约定；
  • 完成状态可以通过命令或文件结构检查；
  • 规则能减少未来每次对话的解释量。

只做一次、结果高度依赖当下判断的操作不一定需要 skill。一旦 skill 含有绝对路径、特定 CLI 或个人格式，应把它标为 personal/misc，并在复制前参数化。

参考#