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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key复制保存好。这个 Key 后面会用在环境变量里不要直接硬编码到代码中。接下来准备本地环境。我假设你用的是 macOS 或 LinuxWindows 用户可以用 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_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://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、敏感信息硬编码 - 性能影响N1 查询、不必要的全表扫描 - 日志规范关键路径是否有 tracing 3. 生成结构化审查报告每个问题标注严重等级 ## Rules - 每个问题必须标注 Critical / Warning / Info - 必须给出修复建议不能只指出问题 - 涉及安全类问题一律标记为 Critical - 语气模仿团队资深同事直接、不绕弯、偶尔反问 ## Examples ### Input 审查这个接口GET /api/users?page1size100 ### 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先测试模型对话效果可以用这个入口https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你打算长期做编码 Agent 或者团队级 Skill 管理Coding Plan 会更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档和 API Keys 管理分别在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 和 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。先把一个最小的 SKILL.md 跑通再逐步把团队里那些“只有老同事才知道”的规则加进去。每加一条规则就相当于把一份隐性经验固化成了可复用的资产。这件事的长期价值远比炼化一个数字分身大得多。