做一个能复用、能测试的 Skill

假设每次新增笔记，你都要检查 frontmatter、阅读顺序、链接和页面渲染。步骤已经稳定，但每次都重新解释。这适合写成一个 Skill。

本章提供可复制的教学文件，不会自动在你的环境安装 Skill。先看流程是否符合自己的项目，再选择保存位置。

Skill 保存流程，脚本保证固定检查

Skill 通常把任务说明、步骤和可选资源放在一个目录里。模型先看到名称与描述，选用时再读取具体说明；因此描述要写清触发条件，而不只是“提高工作效率”。机制见 OpenAI Build skills。

项目规则回答“每次都遵守什么”；Skill 回答“遇到这一类任务怎么做”；脚本负责那些可以确定性判断的步骤。写了 Skill 不会自动提高权限，也不保证步骤一定执行成功。

最小文件与放置位置

以 check-note-content 为名：

check-note-content/
  SKILL.md

当前 Codex 的仓库级位置是 .agents/skills/check-note-content/SKILL.md；Claude Code 的仓库级位置是 .claude/skills/check-note-content/SKILL.md。后者机制见 Claude Code skills。

这是两个产品的加载目录，不要假定互相兼容。跨工具维护时可共享经过测试的说明内容，但仍要核对宿主的发现与执行规则。

一份完整的 SKILL.md 示例

---
name: check-note-content
description: >-
  检查 shanshi-site 中新增或修改的知识 MDX 及阅读顺序。
  用于笔记内容检查，不用于视觉改版、工具开发、提交或部署。
---
 
# 输入
要检查的文章或 diff 范围。未提供时先查看工作区，
列出候选文章；有来源不明或重叠改动时先确认范围。
 
# 工作
1. 读取项目规则、目标 MDX、content-schema.ts
   与 knowledge-map.ts。
2. 检查标题与摘要是否准确表达正文，
   每篇是否解决明确问题。
3. 检查必填字段、日期、来源、前置知识及关联对象。
4. 区分真实案例、简化代码、教学假设和演算数据。
5. 核对内部链接、标题锚点和阅读顺序。
6. 读取 package.json，运行项目已有测试及构建检查。
7. 打开受影响页面，检查代码块、表格与窄屏阅读。
   浏览器不可用时保留为未验证项。
 
# 边界
这是检查任务，只读报告问题；未经另行授权不修正文。
不安装依赖，不修改测试标准，不 stage、commit、push 或部署。
不更新未实际核对的 verifiedAt。
 
# 输出
按影响排序列问题：位置、具体表现、依据、建议修法。
最后分别列出已通过、失败和未执行的检查。
没有证据的问题标为待确认，不编造测试或页面结果。

这份说明刻意没有“发现问题就自动修一切”。检查和修改是不同任务，如果你希望 Skill 包含修复，应明确哪些可以自动修、哪些要先确认。

用四类输入测试它

第一次可以显式指定 Skill；再用自然语言测试自动匹配。误触发时先修 description；步骤漏掉字段时修正文或脚本；结果不准确时看它是否读到了真实数据。不要把所有问题都归因为描述不够长。

什么时候再加脚本、参考和资产

当“是否重复 slug”“是否缺少字段”已经能程序化检查，就调用项目现有校验。本站已有 content schema、registry 和测试，不应复制另一套略有不同的规则。

需要更长的内容规范时再加 references/；需要输出模板时再加 assets/；确有缺失的确定性检查再考虑 scripts/。新脚本要独立测试，不能因为属于 Skill 就跳过代码审阅。

Skill 之外的扩展怎样选

• MCP 或 CLI：需要读外部工单、日志或设计文件时，用它提供数据与动作；不把连接能力当成工作流程本身。
• Hook：某个事件发生时执行已审查的检查或脚本；覆盖与约束能力取决于宿主，不等于通用安全沙箱。
• 子代理：确有可独立处理的调查或评审任务时隔离上下文；如果任务相互依赖、不断共享修改，协调成本可能更高。
• Plugin：流程稳定后需要分发给其他人时再考虑打包。

先证明一个小 Skill 比手动重述更可靠，再扩展。一个名称宏大的“万能开发 Skill”很难测试，也容易在不相关任务里带入多余步骤。