本文作者：霜序

skill-internals-mechanism.png

Skill 到底是什么？
很多人第一次看到 Skill，会把它理解成"一份写给模型看的 Markdown"。这个理解不能说错，但它只摸到了表面。真正有价值的 Skill，不是把经验写成文档，而是把一个可复用的工作流变成 Agent 能够发现、触发、加载、执行、验证和分发的能力包。

换句话说，Skill 的核心不是"写说明"，而是"把一次靠谱的做事方式压缩成下次还能靠谱复现的机制"。

Skill 为什么不是 Markdown
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: string
description: string
location: string
commandName?: string
disableModelInvocation?: boolean
context?: “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，运行起来却更像一套轻量插件系统：它真正复用的不是一段文字，而是"发现、加载、渲染、执行和验证"这一整套工作流。