走进 Skill 的内部机制-概念向

本文作者霜序skill-internals-mechanism.pngSkill 到底是什么很多人第一次看到 Skill会把它理解成一份写给模型看的 Markdown。这个理解不能说错但它只摸到了表面。真正有价值的 Skill不是把经验写成文档而是把一个可复用的工作流变成 Agent 能够发现、触发、加载、执行、验证和分发的能力包。换句话说Skill 的核心不是写说明而是把一次靠谱的做事方式压缩成下次还能靠谱复现的机制。Skill 为什么不是 MarkdownSKILL.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运行起来却更像一套轻量插件系统它真正复用的不是一段文字而是发现、加载、渲染、执行和验证这一整套工作流。