一文讲透 Skill是什么、何时用、怎么封装这篇文章用一个完整的 Skill 示例代码带你搞懂 Skill 解决了什么问题、什么时候该用、以及 frontmatter 渐进式披露Progressive Disclosure的核心实现逻辑。一、Skill 解决了什么问题核心是解决“能力无法沉淀、复用和按需加载”的问题具体对应四个痛点痛点Skill 的解法Prompt 每次重写、无法复用把指令 流程打包成可复用的资产全量塞进 system prompt浪费上下文渐进式披露元数据常驻、正文按需加载工具只有原子操作缺流程编排Skill 提供多步流程 工具组合的编排专家知识散落在人脑 / 文档里难传递把领域知识 最佳实践固化成包一句话总结工具解决能不能做Skill 解决怎么做得专业、且能反复做。二、什么情况下需要用到 Skill判断标准重点看是否有“复用”和“知识沉淀”价值。该用 Skill 的场景某类任务高频反复执行每次都要走一套固定流程需要多步骤、有顺序、有判断不是一次函数调用能搞定需要领域知识 多个工具组合纯 prompt 写太长或每次重写浪费需要跨项目 / 跨团队复用把专家经验固化下来上下文窗口有限希望能力按需加载而非常驻不该用 Skill用 Tool 就够单次、一次性的原子操作查个天气、发个请求没有知识沉淀价值的简单调用逻辑简单到一句 prompt 就能说清一句话判据“这个能力会不会被反复使用要不要把经验传下去” 两个都是 Yes 才上 Skill。三、Skill 封装的技巧实操层结合主流 Agent Skills如 Claude Skills的真实机制关键技巧如下统一入口 元数据SKILL.md frontmatter每个 Skill 一个目录入口文件用 YAML 头写name和description。name / description 是广告位正文是说明书。渐进式披露最核心的技巧元数据name description始终常驻上下文 —— 便宜完整指令正文只在被触发时加载—— 贵用到才给这样 Agent 能知道有什么能力又不浪费 tokendescription 写何时用不写是什么description 里写清触发条件“当用户想生成 PPT 时”而不是能力清单。目的是让 Agent自动判断什么时候该加载它。资源随包携带Skill 目录里带脚本scripts/、参考文档reference/、模板assets/。正文只引用不内联大段内容。单一职责 可组合一个 Skill 只干一类活Skill 内部可以调用工具包括 MCP 工具甚至其他 Skill形成分层。可版本化、可分发Skill 本质是文件 / 目录能进 git、能分享、能做版本管理让能力像代码一样被工程化管理。四、完整示例目录结构 SKILL.md含 frontmatter4.1 目录结构skills/ └── video-downloader/ # 一个 Skill 一个目录 ├── SKILL.md # 入口frontmatter 元数据 正文指令 ├── scripts/ │ └── fetch_video_info.py # 可执行脚本资源 ├── reference/ │ └── yt-dlp-cheatsheet.md # 参考文档资源 └── assets/ └── config.example.json # 模板 / 配置资源4.2 SKILL.md 完整示例--- name: video-downloader description: 当用户需要下载视频、提取音频或查询视频信息时使用。 触发场景用户提到下载视频音频yt-dlpB站YouTube等关键词。 不要在没有明确下载意图时使用。 --- # 视频下载技能 你负责把用户给的视频链接下载到本地或提取音频。 ## 使用前必读 先读取 assets/config.example.json了解默认输出目录、格式等参数。 ## 标准流程 1. 先运行 scripts/fetch_video_info.py url 拿到视频标题、可用格式、时长。 2. 把可选清晰度 / 格式列给用户确认不要擅自选最高清。 3. 确认后执行下载命令。 4. 校验文件是否生成、大小是否合理。 ## 平台差异 不同平台的参数、限速、是否需要 Cookie见 reference/yt-dlp-cheatsheet.md。 遇到报错先去该文档查对应平台的处理方式。 ## 注意事项 - 不要下载版权受限内容先提醒用户确认授权。 - 大文件要提示磁盘空间。关键点frontmatter 里的description写的是何时用 / 何时不用触发条件不是能力清单。这样 Agent 才能自动判断该不该加载它。五、渐进式披露的实现逻辑核心三层加载越靠后越重用到才加载。// 1) 解析 frontmatter只提取 name descriptionfunctionparseFrontmatter(md){constmmd.match(/^---\n([\s\S]*?)\n---/);constmeta{};for(constlineofm[1].split(\n)){const[k,v]line.split(:).map(ss.trim());if(k)meta[k]v.replace(/^[]|[]$/g,);}returnmeta;}// 2) 启动时遍历所有 Skill只收集「元数据」便宜常驻functioncollectSkillMetadata(skillsDir){constskills[];for(constdiroflistDirs(skillsDir)){constmdreadFile(${dir}/SKILL.md);constmetaparseFrontmatter(md);skills.push({name:meta.name,description:meta.description,// 只留这一段进 system promptpath:${dir}/SKILL.md,// 全文路径用到才读});}returnskills;}// 3) 构建 system prompt只注入元数据列表不注入正文functionbuildSystemPrompt(skills){constskillListskills.map(s-${s.name}:${s.description}).join(\n);return[你是一个 Agent拥有以下技能按需加载,skillList,,规则当用户任务匹配某个技能的 description 时,调用 loadSkill(name) 加载该技能的完整指令再执行。,].join(\n);}// 4) 运行时命中后按需加载完整正文贵用到才读functionloadSkill(name){constskillskills.find(ss.namename);returnreadFile(skill.path);// 返回完整 SKILL.md包含脚本/文档引用}token 账本面试最加分的一句层内容是否常驻开销元数据name description常驻每个约 50–100 token正文SKILL.md 指令按需加载每个可能上千 token资源scripts / reference / assets正文引用后才读可能几万 token10 个 Skill 全部元数据常驻也不到 1k token若全量塞进 system prompt 则可能几万 token。渐进式披露让 Agent知道有哪些能力但不为没用的能力付费。总结frontmatter负责让 Agent 知道何时用它SKILL.md 正文 资源目录负责教它怎么做加载器负责三层按需取用这就是 Skill 封装的完整闭环。记住一句话Skill 是把人做某类事的专业经验指令 流程 工具 知识打包成一个可发现、可复用、按需加载、可版本化的能力单元。