SKILL.md 很重要但 Skill 不等于 SKILL.md。SKILL.md 是入口文件负责告诉 Agent这个 Skill 叫什么、什么时候该用、使用时应该遵循什么流程。可一个成熟的 Skill 往往还会带上引用材料、脚本、模板、图标、默认提示和工具依赖声明。一个常见结构大概长这样my-skill/├── SKILL.md├── references/├── scripts/├── assets/└── metadata-or-ui-config.yaml所以Markdown 更像 Skill 的控制面板。真正让它变成能力的是这份入口说明背后的资源组织、触发机制和执行约束。Agent 是怎么发现一个 Skill 的大多数支持 Skill 的 Agent不会一开始就把所有 Skill 的完整内容都塞进上下文。它们通常先拿到一个轻量索引name、description 和路径。只有当用户显式点名某个 Skill或者任务和 description 匹配时Agent 才会读取完整的 SKILL.md。skill-lifecycle.png这就是 Skill 的第一层机制先发现再加载。它带来一个很现实的后果很多 Skill 不是正文写得不好而是根本没有被正确发现。Agent 没读到正文之前正文再精彩也没用。如果要进一步优化发现准确率还需要面对一个真实场景对于中英混用的团队description 用中文写还是英文写Agent 的查询语言和 description 语言不一致时是否仍能命中目前大多数实现不处理这一问题所以保守的做法是在 description 里同时包含中英文关键触发词确保不同语言下的自然语言任务都能命中。Skill 真正保存的是做事方式如果把 Skill 当成知识库很容易写成百科背景、定义、概念、注意事项全塞进去。这样看起来很完整但对 Agent 未必有用。way-of-doing-things.png这也是 Skill 和普通文档最大的区别。普通文档是给人看的Skill 是给 Agent 执行的。它不追求讲得多而追求下次还能按这个流程做对。为什么 description 决定 Skill 是否生效description 不是介绍文案而是触发器。一个不好的 description 往往很泛description: Help with reports.它的问题不是英文短而是不知道什么时候该触发。周报算 report 吗PR 总结算 report 吗线上事故复盘算 report 吗Agent 只能猜。更好的写法应该把触发场景、边界和用户可能说的话放进去description: Use when the user asks to generate a weekly report from Notion records, summarize this week’s completed work, classify items by scope, or produce a Chinese weekly status update.这类描述更像路标而不是名片。它告诉 Agent看到哪些任务应该进来哪些任务不该进来。还有一个容易被忽略的点当安装的 Skill 很多时初始 Skill 列表会受到上下文预算限制描述可能被压缩甚至部分 Skill 会被省略。所以触发词要前置边界要简洁最重要的信息要放在开头。另外对于中英混用的协作环境可以将中英文触发词并列放入 description例如 review code / 审查代码以兼容不同语言的自然语言查询。为什么要渐进披露Skill 的内部机制里有一个非常关键的设计叫渐进披露。skill-progressive_-disclosure.png它大概分三层第一层只暴露 name、description、路径用来决定是否触发。第二层触发后读取完整 SKILL.md获得核心流程。第三层根据任务需要再读取 references/调用 scripts/使用 assets/。这套机制的本质是把上下文当成稀缺资源。Agent 不需要一开始知道所有细节它只需要先知道该不该用这个 Skill。等真的命中任务再读取更深的内容。所以写 Skill 时不要把所有东西都塞进 SKILL.md。正文应该保留核心流程和判断规则大段规范、案例、API 文档、业务字段说明应该放到 references/ 里按需读取。渐进披露也带来一个被忽略的设计问题当用户通过 /skill-name 反复手动触发同一个 Skill 时之前的上下文会不会污染下一轮行为稳妥的做法是每次手动触发时清空上下文、重新加载渲染后的 Skill 内容确保复现一致。Skill 在运行时到底发生了什么不同 Agent 对 Skill 的实现会有一些差异目录位置不同、命令名规则不同、frontmatter 字段不同、权限模型不同。但它们的核心运行机制非常接近可以先理解成一条管线发现 Skill - 建立索引 - 判断触发 - 读取正文 - 渲染上下文 - 执行任务 - 验证结果对应的流程大概是这样skill-runtime-flow.png如果把这个过程写成伪源码它大概不是模型读一个 Markdown 文件这么简单而是一条从发现到执行的渲染管线。注意下面代码是基于 Agent Skills 规范和 Claude Code 文档整理出的概念模型不是某个具体 Agent 的真实源码。type SkillMeta {name: stringdescription: stringlocation: stringcommandName?: stringdisableModelInvocation?: booleancontext?: “inline” | “fork”allowedTools?: string}async function runSkillLifecycle(userInput: string) {const catalog skillRoots().flatMap(scanSkillDirs).map(readFrontmatterOnly)const skill startsWithSlashCommand(userInput)? findByCommandName(userInput, catalog): modelSelectsFromCatalog(userInput, catalog)if (!skill) return runWithoutSkill(userInput)const raw readFile(skill.location)const body stripFrontmatter(raw)const prompt await renderOnce(body, {arguments: parseArguments(userInput),dynamicContext: true,})return skill.context “fork”? runSubagent(prompt, skill.allowedTools): appendToMainConversation(prompt, skill.allowedTools)}这里有几个关键点发现阶段通常只读取 name、description、路径等轻量信息不会把所有 SKILL.md 全部塞进上下文。触发可以来自用户显式输入 /skill-name也可以来自模型根据 description 判断任务相关。渲染阶段会处理参数和动态上下文。有些实现会在模型看到 Skill 前先执行命令、读取文件或展开环境信息并且通常只展开一轮避免递归展开带来的风险。执行阶段可能把 Skill 内容注入主会话也可能 fork 到子代理里隔离执行。前者适合持续指导当前任务后者适合调研、总结、代码探索这类不想污染主会话上下文的工作。这也解释了为什么 Skill 看起来只是 Markdown运行起来却更像一套轻量插件系统它真正复用的不是一段文字而是发现、加载、渲染、执行和验证这一整套工作流。如何验证一个 Skill 是否真的有效判断一个 Skill 有没有价值不是看它写得多完整而是看它有没有改变 Agent 的行为。可以看五个指标触发准确率用户自然描述任务时它是否会被正确选中误触发率不该用它的时候它是否乱入执行稳定性同类任务重复执行步骤是否一致验证闭环它是否要求 Agent 做必要检查维护成本新增边界时是补充几句规则还是要重写整份文档还可以准备一组测试提示词帮我从 Notion 生成这周周报把今天 GitLab 的 fix/feat/hotfix 提交同步到 Notion帮我 review 这个 GitLab MR为这个 Bug 生成禅道修复备注观察它们是否命中对应 Skill是否读取该读的 reference是否运行该运行的脚本是否给出符合团队习惯的输出。如果一个 Skill 只有在用户精确喊出名字时才工作它还只是一个手册。如果用户自然描述需求时它也能稳定接管流程它才真正进入了 Agent 的工作系统。一个延伸问题怎么测试 Skill 的稳定性 由于 LLM 行为有随机性同一个 Skill 多次执行可能得到不同结果。建议对输出不做逐字一致的断言而是做关键动作校验——比如是否读了 references/ 下的文件、是否运
SKILL.md 很重要但 Skill 不等于 SKILL.md。SKILL.md 是入口文件负责告诉 Agent这个 Skill 叫什么、什么时候该用、使用时应该遵循什么流程。可一个成熟的 Skill 往往还会带上引用材料、脚本、模板、图标、默认提示和工具依赖声明。一个常见结构大概长这样my-skill/├── SKILL.md├── references/├── scripts/├── assets/└── metadata-or-ui-config.yaml所以Markdown 更像 Skill 的控制面板。真正让它变成能力的是这份入口说明背后的资源组织、触发机制和执行约束。Agent 是怎么发现一个 Skill 的大多数支持 Skill 的 Agent不会一开始就把所有 Skill 的完整内容都塞进上下文。它们通常先拿到一个轻量索引name、description 和路径。只有当用户显式点名某个 Skill或者任务和 description 匹配时Agent 才会读取完整的 SKILL.md。skill-lifecycle.png这就是 Skill 的第一层机制先发现再加载。它带来一个很现实的后果很多 Skill 不是正文写得不好而是根本没有被正确发现。Agent 没读到正文之前正文再精彩也没用。如果要进一步优化发现准确率还需要面对一个真实场景对于中英混用的团队description 用中文写还是英文写Agent 的查询语言和 description 语言不一致时是否仍能命中目前大多数实现不处理这一问题所以保守的做法是在 description 里同时包含中英文关键触发词确保不同语言下的自然语言任务都能命中。Skill 真正保存的是做事方式如果把 Skill 当成知识库很容易写成百科背景、定义、概念、注意事项全塞进去。这样看起来很完整但对 Agent 未必有用。way-of-doing-things.png这也是 Skill 和普通文档最大的区别。普通文档是给人看的Skill 是给 Agent 执行的。它不追求讲得多而追求下次还能按这个流程做对。为什么 description 决定 Skill 是否生效description 不是介绍文案而是触发器。一个不好的 description 往往很泛description: Help with reports.它的问题不是英文短而是不知道什么时候该触发。周报算 report 吗PR 总结算 report 吗线上事故复盘算 report 吗Agent 只能猜。更好的写法应该把触发场景、边界和用户可能说的话放进去description: Use when the user asks to generate a weekly report from Notion records, summarize this week’s completed work, classify items by scope, or produce a Chinese weekly status update.这类描述更像路标而不是名片。它告诉 Agent看到哪些任务应该进来哪些任务不该进来。还有一个容易被忽略的点当安装的 Skill 很多时初始 Skill 列表会受到上下文预算限制描述可能被压缩甚至部分 Skill 会被省略。所以触发词要前置边界要简洁最重要的信息要放在开头。另外对于中英混用的协作环境可以将中英文触发词并列放入 description例如 review code / 审查代码以兼容不同语言的自然语言查询。为什么要渐进披露Skill 的内部机制里有一个非常关键的设计叫渐进披露。skill-progressive_-disclosure.png它大概分三层第一层只暴露 name、description、路径用来决定是否触发。第二层触发后读取完整 SKILL.md获得核心流程。第三层根据任务需要再读取 references/调用 scripts/使用 assets/。这套机制的本质是把上下文当成稀缺资源。Agent 不需要一开始知道所有细节它只需要先知道该不该用这个 Skill。等真的命中任务再读取更深的内容。所以写 Skill 时不要把所有东西都塞进 SKILL.md。正文应该保留核心流程和判断规则大段规范、案例、API 文档、业务字段说明应该放到 references/ 里按需读取。渐进披露也带来一个被忽略的设计问题当用户通过 /skill-name 反复手动触发同一个 Skill 时之前的上下文会不会污染下一轮行为稳妥的做法是每次手动触发时清空上下文、重新加载渲染后的 Skill 内容确保复现一致。Skill 在运行时到底发生了什么不同 Agent 对 Skill 的实现会有一些差异目录位置不同、命令名规则不同、frontmatter 字段不同、权限模型不同。但它们的核心运行机制非常接近可以先理解成一条管线发现 Skill - 建立索引 - 判断触发 - 读取正文 - 渲染上下文 - 执行任务 - 验证结果对应的流程大概是这样skill-runtime-flow.png如果把这个过程写成伪源码它大概不是模型读一个 Markdown 文件这么简单而是一条从发现到执行的渲染管线。注意下面代码是基于 Agent Skills 规范和 Claude Code 文档整理出的概念模型不是某个具体 Agent 的真实源码。type SkillMeta {name: stringdescription: stringlocation: stringcommandName?: stringdisableModelInvocation?: booleancontext?: “inline” | “fork”allowedTools?: string}async function runSkillLifecycle(userInput: string) {const catalog skillRoots().flatMap(scanSkillDirs).map(readFrontmatterOnly)const skill startsWithSlashCommand(userInput)? findByCommandName(userInput, catalog): modelSelectsFromCatalog(userInput, catalog)if (!skill) return runWithoutSkill(userInput)const raw readFile(skill.location)const body stripFrontmatter(raw)const prompt await renderOnce(body, {arguments: parseArguments(userInput),dynamicContext: true,})return skill.context “fork”? runSubagent(prompt, skill.allowedTools): appendToMainConversation(prompt, skill.allowedTools)}这里有几个关键点发现阶段通常只读取 name、description、路径等轻量信息不会把所有 SKILL.md 全部塞进上下文。触发可以来自用户显式输入 /skill-name也可以来自模型根据 description 判断任务相关。渲染阶段会处理参数和动态上下文。有些实现会在模型看到 Skill 前先执行命令、读取文件或展开环境信息并且通常只展开一轮避免递归展开带来的风险。执行阶段可能把 Skill 内容注入主会话也可能 fork 到子代理里隔离执行。前者适合持续指导当前任务后者适合调研、总结、代码探索这类不想污染主会话上下文的工作。这也解释了为什么 Skill 看起来只是 Markdown运行起来却更像一套轻量插件系统它真正复用的不是一段文字而是发现、加载、渲染、执行和验证这一整套工作流。如何验证一个 Skill 是否真的有效判断一个 Skill 有没有价值不是看它写得多完整而是看它有没有改变 Agent 的行为。可以看五个指标触发准确率用户自然描述任务时它是否会被正确选中误触发率不该用它的时候它是否乱入执行稳定性同类任务重复执行步骤是否一致验证闭环它是否要求 Agent 做必要检查维护成本新增边界时是补充几句规则还是要重写整份文档还可以准备一组测试提示词帮我从 Notion 生成这周周报把今天 GitLab 的 fix/feat/hotfix 提交同步到 Notion帮我 review 这个 GitLab MR为这个 Bug 生成禅道修复备注观察它们是否命中对应 Skill是否读取该读的 reference是否运行该运行的脚本是否给出符合团队习惯的输出。如果一个 Skill 只有在用户精确喊出名字时才工作它还只是一个手册。如果用户自然描述需求时它也能稳定接管流程它才真正进入了 Agent 的工作系统。一个延伸问题怎么测试 Skill 的稳定性 由于 LLM 行为有随机性同一个 Skill 多次执行可能得到不同结果。建议对输出不做逐字一致的断言而是做关键动作校验——比如是否读了 references/ 下的文件、是否运
