1. 同事.skill 爆火背后，SKILL.md 到底解决了什么问题
最近 GitHub 上有个叫「同事.skill」的项目火得离谱，5 天 6600+ Stars，朋友圈和各大技术社区都在讨论。它的核心玩法很直白：把离职同事的聊天记录、工作文档、代码评审意见导入进去，AI 就能生成一个在技术能力、沟通风格、甚至甩锅话术上都高度还原的“数字分身”。
很多人第一反应是“这不就是个高级 Prompt 吗？”但真正拆开看，它背后依赖的是一套已经标准化的 Agent Skills 机制，入口文件就是 SKILL.md。这个文件不是简单的提示词堆砌，而是一个可被 AI 智能体动态发现、按需加载的能力包描述文件。它解决的核心问题是：如何让 AI 在需要的时候，自动知道“该用什么能力、按什么步骤、遵守什么规则”。
如果你手头有一堆团队规范、排查流程、代码审查标准，却只能靠口口相传或者写成长篇 Wiki 没人看，那 SKILL.md 就是把这些隐性经验变成 AI 可执行指令的最佳载体。这篇文章我会带你从零拆解 SKILL.md 的结构，给出可直接复制的骨架，并一步步验证它在本地 AI 工具中的加载效果。适合想玩 Agent Skills 但不知道从哪下手的前后端、运维和效率工具爱好者。
2. 前置准备：TaoToken 接入与 Skills 运行环境
在开始写 SKILL.md 之前，你需要一个能稳定调用大模型 API 的入口。我目前用的是 TaoToken 提供的 API 服务，它兼容 OpenAI 格式，接入成本低，适合用来做 Agent Skills 的本地验证。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。
你需要先拿到一个 API Key。登录后进入控制台，在 API Keys 页面创建一个新 Key，复制保存好。这个 Key 后面会用在环境变量里，不要直接硬编码到代码中。
接下来准备本地环境。我假设你用的是 macOS 或 Linux，Windows 用户可以用 WSL2。需要安装 Node.js 18+ 和 Git。如果你打算用 Claude Code 或 Cursor 来加载 Skills，确保它们是最新版本。这里我以命令行方式演示，方便你理解底层加载逻辑。
创建一个工作目录：
mkdir -p ~/agent-skills-demo/colleague-skill cd ~/agent-skills-demo/colleague-skill然后设置环境变量，把刚才拿到的 Key 写进去：
export TAOTOKEN_API_KEY="sk-你的实际Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"如果你用的是 OpenAI SDK 或兼容库，直接把 base_url 指向https://taotoken.net/api即可。这样后续所有模型调用都会走 TaoToken，不需要额外配置网络代理。
3. SKILL.md 骨架：从同事经验到可复用配置
SKILL.md 的标准结构由两部分组成：YAML 前置元数据（frontmatter）和 Markdown 正文。元数据告诉 AI “这个 Skill 叫什么、什么时候用、什么时候不用”，正文则写清楚具体步骤、规则和示例。
下面是我根据「同事.skill」的思路，整理的一份可直接复用的骨架。你可以把它保存为SKILL.md：
--- name: colleague-reviewer version: "1.0.0" description: > When to use: 当需要对 Pull Request 进行结构化代码审查， 或需要模拟资深同事的评审风格给出意见时。 When NOT to use: 纯文档变更、依赖版本升级、或简单的 typo 修复。 user-invocable: true tags: ["code-review", "team-convention", "best-practices"] --- # 同事风格代码审查 ## Prerequisites - 已安装 Git CLI - 有目标仓库的 read 权限 - 已配置 TAOTOKEN_API_KEY 环境变量 ## Steps 1. 获取 PR 的 diff 内容，提取变更文件列表 2. 按以下维度逐一审查： - 架构合理性：是否符合团队分层规范 - 异常处理：是否有兜底逻辑和错误码 - 安全审计：SQL 注入、XSS、敏感信息硬编码 - 性能影响：N+1 查询、不必要的全表扫描 - 日志规范：关键路径是否有 tracing 3. 生成结构化审查报告，每个问题标注严重等级 ## Rules - 每个问题必须标注 Critical / Warning / Info - 必须给出修复建议，不能只指出问题 - 涉及安全类问题一律标记为 Critical - 语气模仿团队资深同事：直接、不绕弯、偶尔反问 ## Examples ### Input "审查这个接口：GET /api/users?page=1&size=100" ### Expected Output | 维度 | 发现 | 严重等级 | 建议 | |------|------|---------|------| | 查询 | 未使用索引，全表扫描 | Critical | 为 user_id 添加索引 | | 分页 | offset 分页，大页码性能退化 | Warning | 改用 cursor-based 分页 | | 日志 | 无请求耗时记录 | Info | 添加 tracing 埋点 |这个骨架的关键在于description里的 When to use / When NOT to use。很多人写 Skill 时只写“帮助代码审查”，结果 AI 在任何场景下都想加载它，浪费 Token 还容易误触发。精确的触发条件能让 Agent 只在真正需要时才读取完整正文。
另外，Rules部分就是“炼化同事经验”的核心。你可以把团队里那位资深同事常说的“这里为什么不用 interface”“这个需求上次对齐过的”转化成可执行的规则。比如：
## Rules - 新增接口必须定义在 api/ 目录下，且使用统一的 Response 结构 - 任何数据库查询必须带 context 超时控制 - 如果发现重复代码超过 3 处，必须建议抽取公共函数 - 评审语气参考：先问“这个场景考虑过并发吗”，再给结论这样 AI 在审查时就会带上你同事的“味道”，而不是干巴巴地列问题。
4. 本地验证：让 AI 真正加载并执行 SKILL.md
写完 SKILL.md 后，怎么验证它真的被加载了？我试过两种方式：一种是用 Claude Code 的 skill 安装命令，另一种是直接用脚本模拟加载流程。这里重点讲第二种，因为更透明，方便你排查问题。
先安装依赖：
npm init -y npm install openai dotenv创建一个verify-skill.js文件：
import OpenAI from "openai"; import fs from "fs"; import dotenv from "dotenv"; dotenv.config(); const client = new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); // 读取 SKILL.md const skillContent = fs.readFileSync("./SKILL.md", "utf-8"); // 提取 frontmatter 和正文 const frontmatterMatch = skillContent.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/); const metadata = frontmatterMatch[1]; const body = frontmatterMatch[2]; console.log("=== Skill 元数据 ==="); console.log(metadata); console.log("=== 正文长度 ===", body.length, "字符"); // 模拟 Agent 判断是否加载 const userTask = "帮我审查这个 PR：修改了用户查询接口，加了分页参数"; const response = await client.chat.completions.create({ model: "gpt-4o-mini", messages: [ { role: "system", content: `你是一个 Agent，当前可用 Skill 元数据如下：\n${metadata}\n\n如果用户任务匹配 When to use，请输出 LOAD，否则输出 SKIP。只输出一个词。`, }, { role: "user", content: userTask }, ], }); const decision = response.choices[0].message.content.trim(); console.log("=== 加载决策 ===", decision); if (decision === "LOAD") { const reviewResponse = await client.chat.completions.create({ model: "gpt-4o-mini", messages: [ { role: "system", content: `你已加载以下 Skill，请严格按 Steps 和 Rules 执行：\n${body}` }, { role: "user", content: userTask }, ], }); console.log("=== 审查结果 ==="); console.log(reviewResponse.choices[0].message.content); }运行：
node verify-skill.js如果一切正常，你会看到元数据被打印出来，加载决策输出LOAD，然后模型按照 SKILL.md 里的 Steps 和 Rules 生成一份带严重等级和修复建议的审查报告。这说明你的 SKILL.md 结构是有效的，AI 能正确识别触发条件并执行。
如果你想在 Claude Code 里验证，可以把整个目录放到~/.claude/skills/下，然后运行claude skill list查看是否被发现。Cursor 用户则把目录放到.cursor/skills/即可自动加载。
5. 常见报错与排查
报错一：401 Unauthorized或Invalid API Key
检查TAOTOKEN_API_KEY是否设置正确，注意不要有多余空格。如果你用的是.env文件，确认dotenv.config()在创建 OpenAI 客户端之前调用。另外确认 baseURL 写的是https://taotoken.net/api，不要漏掉/api。
报错二：Skill 没有被加载，决策输出 SKIP
大概率是description里的 When to use 写得太模糊。比如只写“代码审查”，而用户任务是“帮我看看这个 PR”，模型可能判断不匹配。改成“当需要对 Pull Request 进行结构化代码审查时”会更准确。另外检查 frontmatter 的 YAML 格式，冒号后面要有空格，多行描述用>折叠。
报错三：模型输出格式混乱，没有按表格返回
在 SKILL.md 的 Rules 里明确要求输出格式，比如“必须使用 Markdown 表格，列包括维度、发现、严重等级、建议”。如果还是不稳定，可以在 Examples 里给一个完整的输入输出示例，模型通过模式匹配会学得更快。
报错四：Cannot find module 'openai'
确认在项目目录下执行了npm install openai，并且package.json里设置了"type": "module"，否则import语法会报错。或者把文件后缀改成.mjs。
报错五：Token 消耗过快
检查是不是把大段参考文档直接塞进了 SKILL.md 正文。正确做法是把详细规范放到references/目录，正文只保留精简指令，需要时再让 AI 读取。这就是渐进式披露的意义。
6. 把经验沉淀成 Skill，才是正经事
玩梗归玩梗，「同事.skill」真正有价值的地方不是复刻某个人，而是证明了隐性经验可以被结构化封装。你团队里那些“只可意会”的规范、排查思路、评审习惯，完全可以用 SKILL.md 写成 AI 可执行的配置。新人入职第一天就能调用“老员工级别”的上下文，代码审查不再依赖某个人是否在线。
如果你已经写好了自己的 SKILL.md，下一步就是把它接入到日常工具里。需要创建和管理 API Key 的话，直接进控制台操作：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。想先测试模型对话效果，可以用这个入口：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。如果你打算长期做编码 Agent 或者团队级 Skill 管理，Coding Plan 会更划算：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入文档和 API Keys 管理分别在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 和 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
先把一个最小的 SKILL.md 跑通，再逐步把团队里那些“只有老同事才知道”的规则加进去。每加一条规则，就相当于把一份隐性经验固化成了可复用的资产。这件事的长期价值，远比炼化一个数字分身大得多。
