读懂 skills 项目架构SKILL.md rules 文档驱动的技能包设计哲学【免费下载链接】skillsMy own collection of skills for modern Node.js development项目地址: https://gitcode.com/gh_mirrors/skills15/skillsskills是一个面向 AI 辅助开发AI-assisted development的技能包合集收录了 11 个针对现代 Node.js 开发的技能包每个技能包都由SKILL.md 入口 rules/ 规则文档库两层结构组成用零行可执行业务逻辑的方式把最佳实践注入 AI 编码助手。本文拆解这套文档驱动的技能包架构是如何设计的为什么规则必须拆成独立文件以及基准测试如何保证技能真正生效。一、总览11 个技能包零行业务逻辑README.md 开门见山这不是一个常规应用而是面向 AI 辅助开发的skills/prompt 库。目前收录的技能包如下技能包定位nodeNode.js 开发最佳实践流、测试、性能、优雅关闭fastifyFastify 后端开发最佳实践覆盖请求完整生命周期nodejs-coreNode.js 内部机制V8、libuv、C 插件、构建系统typescript-magicianTypeScript 高级类型系统与泛型技巧oauthOAuth 2.0/2.1 规范专家与 Fastify 集成模式init创建并维护高信号 AGENTS.md其余documentation、linting-neostandard-eslint9、octocat、snipgrapher、skill-optimizer整个仓库唯一的代码只有少量 TypeScript作用见第七节。二、技能包三件套一个目录一个技能包打开任意技能目录结构完全一致。以skills/node为例skills/node/ ├── SKILL.md # 入口元数据 激活说明 规则索引 ├── tile.json # 注册表清单 └── rules/ # 15 份详细规则文档 ├── streams.md ├── testing.md └── ...SKILL.md是技能包入口与索引契约告诉 AI 何时使用该技能并链接到每一个 rules 文档。rules/*.md是详细规则每一份都是一个可独立加载的知识单元。tile.json是让技能注册表识别该包的清单声明包名、版本并指向 SKILL.md 入口参见 skills/fastify/tile.json。三、SKILL.md 设计为激活而写而非为人类阅读每个 SKILL.md 顶部都是 YAML frontmatter 元数据见 skills/node/SKILL.mdname: node description: Provides domain-specific best practices for Node.js development... Use when setting up Node.js projects with native TypeScript support... metadata: tags: node, nodejs, typescript, backend关键设计藏在description里它不是给人看的功能摘要而是给模型看的激活说明。node 技能的描述中显式列出了触发词native TypeScript in Node、strip types、Node 22 TypeScript 等AI 遇到类似的任务描述时才会激活对应技能包。fastify 技能同样在 skills/fastify/SKILL.md 中枚举了完整触发词清单Fastify、REST API、server.ts 等。frontmatter 之后SKILL.md 通常只有三部分When to use—— 激活边界说明什么任务该用这个技能Common Workflows / 高优先级清单—— 高信号操作摘要比如优雅关闭的四步流程注册信号 → 停止接活 → 排空请求 → 关闭外部连接How to use—— 规则索引逐一链接全部规则文件完整列表见 skills/node/SKILL.md。仓库的 AGENTS.md 把这条索引契约写成了硬规则每个 rules 文件都必须被 SKILL.md 显式引用新增/重命名/删除任何规则文件时必须在同一次变更中同步更新链接。四、rules/ 目录按需加载的详细规则每个 rules 文件自带 frontmattername、description、tags是一个自包含的知识单元。例如 skills/node/rules/error-handling.md 只讲错误分类与异步边界处理skills/node/rules/streams.md 只讲流与背压。fastify 技能更进一步在 skills/fastify/SKILL.md 中给出了**推荐阅读顺序**新手走plugins → routes → schemas上生产走logging → configuration → deployment——阅读路径本身也成了技能设计的一部分。五、为什么不在一个文件里写完所有规则这是整套设计哲学的核心项目给出了四个答案上下文预算—— SKILL.md 可能常驻 AI 上下文而 rules 只有在主题命中时才被加载。skill-optimizer 技能专门有一篇 rules/context-budget.md主题就是如何在不损失行为的前提下降低 token 成本。激活率—— 入口写得越长越容易被上下文稀释。skill-optimizer 的实用启发式很直接宁要少数高信号规则不要大量软建议。可维护性—— 独立文件可以单独修改、评审与回归而索引契约让结构一致性可检查。可度量—— 两层结构让每条规则的效果可以单独归因、单独优化。六、基准测试闭环一个被度量的技能包仓库的 docs/skill-benchmarking.md 定义了跨模型基准测试流程对每个测试场景在多个模型上分别运行无技能与有技能两组对照发布门槛docs/skill-benchmarking.md任何标准在所有模型上保持 0%或任何关键场景启用技能后分数反而下降都不能发布每次运行结果记录在 docs/skill-benchmark-runs.md 中失败项会立即开 issue 跟踪。更有趣的是skill-optimizer这个技能——一个优化技能的技能它自己定义了完整的优化闭环测基线 → 找失败模式 → 改措辞 → 重跑评测 → 带护栏发布见 skills/skill-optimizer/SKILL.md。用文档驱动的方式管理如何写文档形成了自指式设计。七、极简代码面一个也是文档的库有人可能会疑惑有 package.json 的文档项目是什么src/index.ts 只导出一个version常量package.json 中 TypeScript 配置为 strict noEmit只做类型检查、lint 与单元测试守护少量代码与示例资产AGENTS.md 一句话点题绝大多数逻辑是 Markdown 中的指令文本。这让同一份文件同时服务两种读者装给 AI 工具时是技能库人打开时是可读文档。总结记住三点即可把 SKILL.md 当激活契约—— description 写给模型看要列触发词与激活边界rules/ 存细节SKILL.md 只存索引—— 拆分上下文预算实现按需加载任何改动都要过基准门槛—— 对比启用/禁用技能无回归才允许发布。如果你想写自己的第一个技能包直接以 skills/node/ 为模板复制frontmatter When to use 规则索引骨架再把每个主题拆成一个独立的 rule 文件即可。【免费下载链接】skillsMy own collection of skills for modern Node.js development项目地址: https://gitcode.com/gh_mirrors/skills15/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考