https://txtmix.com/tags/open-standard/Recent content in Open Standard on Text MatrixHugozh-cnThu, 23 Jul 2026 03:05:08 +0800https://txtmix.com/posts/tech/agentskills-agentskills-agent-skills-open-spec-guide/Thu, 02 Jul 2026 21:02:26 +0800https://txtmix.com/posts/tech/agentskills-agentskills-agent-skills-open-spec-guide/<h1 id="agentskillsagentskills-原理拆解agent-skills-开放规范是怎么设计的">agentskills/agentskills 原理拆解：Agent Skills 开放规范是怎么设计的</h1> <h2 id="学习目标">学习目标</h2> <p>读完本文后，你应该能够：</p> <ul> <li>理解 Agent Skills 规范的四层结构和渐进披露三阶段</li> <li>区分六个 frontmatter 字段的设计意图和使用边界</li> <li>解释 scripts/、references/、assets/ 三个可选目录的角色差异</li> <li>写出一个符合规范的最小 skill 目录并验证它</li> <li>判断你的团队是否应该采用 Agent Skills 规范，以及从哪层开始</li> </ul> <h2 id="目录">目录</h2> <ul> <li><a href="#%e6%a0%b8%e5%bf%83%e5%88%a4%e6%96%ad%e4%b8%89%e6%ae%b5%e5%bc%8f%e5%8a%a0%e8%bd%bd%e6%98%af%e6%95%b4%e4%b8%aa%e8%a7%84%e8%8c%83%e7%9a%84%e8%ae%be%e8%ae%a1%e5%8e%9f%e7%82%b9" rel="">核心判断：三段式加载是整个规范的设计原点</a></li> <li><a href="#%e7%b3%bb%e7%bb%9f%e5%9c%b0%e5%9b%be%e8%a7%84%e8%8c%83%e7%9a%84%e5%9b%9b%e5%b1%82%e7%bb%93%e6%9e%84" rel="">系统地图：规范的四层结构</a></li> <li><a href="#frontmatter-%e5%ad%97%e6%ae%b5%e8%af%ad%e4%b9%89" rel="">Frontmatter 字段语义</a></li> <li><a href="#%e6%b8%90%e8%bf%9b%e6%8a%ab%e9%9c%b2%e4%b8%89%e9%98%b6%e6%ae%b5" rel="">渐进披露三阶段</a></li> <li><a href="#%e6%96%87%e4%bb%b6%e5%bc%95%e7%94%a8%e8%a7%84%e5%88%99" rel="">文件引用规则</a></li> <li><a href="#scriptsreferencesassets-%e7%9a%84%e8%a7%92%e8%89%b2%e5%b7%ae%e5%bc%82" rel="">Scripts/、references/、assets/ 的角色差异</a></li> <li><a href="#42-%e4%b8%aa%e5%85%bc%e5%ae%b9%e5%ae%a2%e6%88%b7%e7%ab%af%e6%84%8f%e5%91%b3%e7%9d%80%e4%bb%80%e4%b9%88" rel="">42 个兼容客户端意味着什么</a></li> <li><a href="#%e5%8f%82%e8%80%83%e5%ae%9e%e7%8e%b0skills-ref-%e5%ba%93" rel="">参考实现：skills-ref 库</a></li> <li><a href="#%e5%86%99%e4%b8%80%e4%b8%aa-skill-%e7%9a%84%e6%9c%80%e5%b0%8f%e9%97%ad%e7%8e%af" rel="">写一个 skill 的最小闭环</a></li> <li><a href="#%e5%ae%83%e4%b8%8d%e6%98%af%e4%bb%80%e4%b9%88" rel="">它不是什么</a></li> <li><a href="#%e4%b8%8e%e5%87%a0%e4%b8%aa%e7%9b%b8%e9%82%bb%e6%a6%82%e5%bf%b5%e7%9a%84%e5%8c%ba%e5%88%ab" rel="">与几个相邻概念的区别</a></li> <li><a href="#metadata-%e4%b8%8e-allowed-tools-%e7%9a%84%e6%89%a9%e5%b1%95%e4%bd%bf%e7%94%a8" rel="">Metadata 与 allowed-tools 的扩展使用</a></li> <li><a href="#%e5%a4%9a-skill-%e7%bb%84%e5%90%88%e4%b8%8e%e5%86%b2%e7%aa%81%e5%a4%84%e7%90%86" rel="">多 skill 组合与冲突处理</a></li> <li><a href="#description-%e7%9a%84%e4%bc%98%e5%8c%96%e6%98%af%e4%b8%80%e4%b8%aa%e7%8b%ac%e7%ab%8b%e8%af%be%e9%a2%98" rel="">Description 的优化是一个独立课题</a></li> <li><a href="#%e4%bb%93%e5%ba%93%e7%bb%93%e6%9e%84%e4%b8%8e%e6%96%87%e6%a1%a3%e7%ab%99%e7%9a%84%e8%bf%90%e4%bd%9c%e6%96%b9%e5%bc%8f" rel="">仓库结构与文档站的运作方式</a></li> <li><a href="#%e9%80%82%e7%94%a8%e8%be%b9%e7%95%8c%e4%b8%8e%e9%87%87%e7%94%a8%e9%a1%ba%e5%ba%8f" rel="">适用边界与采用顺序</a></li> <li><a href="#%e5%b8%b8%e8%a7%81%e9%97%ae%e9%a2%98faq" rel="">常见问题（FAQ）</a></li> <li><a href="#%e8%87%aa%e6%b5%8b%e9%a2%98" rel="">自测题</a></li> <li><a href="#%e7%bb%83%e4%b9%a0" rel="">练习</a></li> <li><a href="#%e8%bf%9b%e9%98%b6%e8%b7%af%e5%be%84" rel="">进阶路径</a></li> </ul> <h2 id="核心判断">核心判断</h2> <p>把它当成 LLM 工具链的&quot;VS Code 扩展目录&quot;会更容易理解：一个 skill 是一个带元数据的文件夹，agent 在启动时只看 <code>name</code> 与 <code>description</code>（≈100 tokens），匹配任务时才把完整 <code>SKILL.md</code> 读进上下文（&lt;5000 tokens 推荐），需要时再去翻 <code>scripts/</code>、<code>references/</code>、<code>assets/</code>。这种三段式加载（progressive disclosure）是整个规范的设计核心——它决定了 frontmatter 字段为什么是 6 个而不是 30 个，也决定了为什么 <code>SKILL.md</code> 推荐 500 行以内。</p>