为什么一个正确的 skill 文件会处于不可见状态
只有当一个 skill 的名称和描述进入模型可见的目录时，它才会对 agent 产生影响。Zed 的文档指出了导致文件无法进入目录的四个条件，以及一个带有警告的准入条件。
目录有字节预算限制。 这是最出乎意料的一点：
"50KB 目录预算。所有 skill 名称和描述的总大小上限为 50KB。不符合要求的 skill 将从目录中丢弃，并在 UI 中显示警告。请保持描述简洁。"
请注意这里测量的是什么——是名称和描述，而不是主体内容。因此，一个 skill 可能会因为你其他 skill 的描述过于冗长而被丢弃。添加一个新 skill 可能会驱逐一个你已经依赖了数月的 skill，而唯一的信号就是你可能根本没有注意到的 UI 警告。
不支持嵌套。 Zed 的表述非常明确：
"仅限扁平布局。Skill 必须是 skills 根目录的直接子项。像 ~/.agents/skills/group/my-skill/ 这样的嵌套文件夹是无法被检索到的。"如果你一直在将 skill 整理到文件夹中（按领域分组的直觉是好的），这些 skill 不仅仅是优先级降低了，而是根本无法被找到。
未受信任的工作区毫无作用。 这一点在克隆新仓库的第一天经常让人踩坑：
"项目本地 skill 仅从受信任的工作区加载。在授予信任之前，来自新克隆或未受信任项目的 skill 将被排除在目录和斜杠命令之外。"
克隆一个包含 skill 的仓库并打开它，此时它们都不存在。既不在目录中，也不作为斜杠命令存在。
Frontmatter 字段可以使 skill 选择性退出。 Zed 将此作为一项功能记录在案，它确实很有用："在 skill 的 frontmatter 中添加 disable-model-invocation: true 可以阻止 agent 自主调用它。" 这完全合理，但也极易让你忘记自己在六周前曾这样设置过。
还有一个值得了解的“擦边”行为。 关于描述："保持在 1024 字节以内；描述较长的 skill 仍会加载，但会伴有警告。" 因此，过长的描述不会排除该 skill，但它消耗的 50KB 预算会超出其应有的份额——这就是为什么一个描述问题会变成另一个 skill 被排除的问题。
还有第六种行为，它不是排除，但解释了另一种困惑："如果全局 skill 和项目本地 skill 共享相同的名称，则项目本地 skill 优先。" 你的 skill 可能存在并被遮蔽（shadowed），而不是不存在。
所有这些情况的模式与为什么 agent 会忽略你的指令文件中讨论的模式一致——工具从未加载的文件与模型选择不使用的文件看起来完全一样，而这两者需要完全不同的解决方法。
人们通常会尝试的替代方法
重写描述使其更具吸引力。 这通常是第一步，但只有在 skill 已经存在于目录中且在相关性判断中落败时才有帮助。如果它是因预算、嵌套或信任问题而被丢弃，那么更好的描述不会改变任何事情——而更长的描述只会让预算问题变得更糟。
重启 Zed。 这可以理解，但对于内容更改来说是不必要的。Zed 文档中提到了实时重载："添加、删除或编辑 SKILL.md 会立即生效，无需重启会话。" 重启确实能解决信任问题（如果你在重新进入时接受了提示），这可能就是为什么它有时看起来有效的原因。
显式调用 skill。 这是一个很好的诊断方法，注意它能证明什么。如果显式调用有效，但自主使用从未发生，那么你面对的是 disable-model-invocation 或描述问题，而不是检索问题。如果斜杠命令也缺失了，那么你处于信任问题的范畴，因为 Zed 会将未受信任的项目 skill "排除在目录和斜杠命令之外"。
将 skill 复制到全局根目录。 这通常能解决问题，这也是为什么它是一个令人满意的死胡同：它之所以有效，是因为全局根目录是受信任且扁平的，所以你无意中同时消除了两个原因，却不知道到底是哪一个在起作用。下一个项目依然会遇到同样的问题。
将所有内容移入指令文件。 这很有诱惑力，但它只是改变了成本结构，而不是解决问题：始终加载的指令会在每条消息上消耗上下文，而这正是 skill 作为按需使用界面存在的全部意义。这两者之间的区别，以及为什么一个不能替代另一个，已在为什么 agent skill 不是记忆中进行了阐述。
解决方案：按固定顺序消除这四个原因
请按顺序执行这些步骤。每一步的成本都很低，且结论明确。顺序至关重要，因为如果前面的条件成立，后面的检查就毫无意义。
步骤 1：在查看其他任何内容之前，先解决信任和布局问题
这两者都是结构性的，且都是“是或否”的问题。
确认工作区是受信任的。如果你最近克隆了这个仓库且从未授予信任，那么所有项目本地 skill 都会被排除——而这些 skill 缺少斜杠命令就是你的确认依据。
然后进行扁平化。遍历 skills 根目录（用户级根目录和工作区自身的根目录），并检查每个 skill 是否为直接子项。Zed 举出的失败例子非常精确：像 ~/.agents/skills/group/my-skill/ 这样的路径是无法被检索到的。如果你发现了分组文件夹，这就是你的答案，解决方法是将它们向上移动一级，而不是重命名任何内容。
在此过程中值得了解的是：.agents/skills/ 并非 Zed 独有的约定。Windsurf、Zencoder 和 OpenHands 都会从相同的路径读取 skill，而 Factory 则将 .agents/ 作为其兼容目录之一。另一个工具所容忍的分组布局，恰恰就是随共享仓库一起引入并默默让你在 Zed 中丢失 skill 的原因。
步骤 2：审计目录预算总额，而非单个 skill
这是没有人会运行的检查，因为预算是共享的，而失败往往被归咎于错误的文件。
将两个根目录下每个 skill 的名称和描述长度相加。你需要对照 50KB 的名称和描述上限来查看总和。然后寻找 Zed 所说的当 skill 不适用时会在 UI 中显示的警告——如果存在该警告，你就找到了原因，解决方法是修剪描述，而不是删除 skill。
顺便将每个描述保持在 1024 字节的指导值以下。Zed 允许较长的描述伴随警告加载，但它们消耗的预算是较短描述所不会消耗的，而且它们挤出的 skill 不会是你正在编辑的那一个。
步骤 3：区分“不在目录中”与“选择不使用它”
现在，也只有在现在，frontmatter 和相关性问题才是可以解答的。
检查是否存在 disable-model-invocation: true。如果设置了此项，则该 skill 已刻意退出了自主选择，并且只有在你要求时才会运行。
检查是否与全局 skill 存在名称冲突，因为项目本地 skill 具有优先权，你所期望的全局 skill 正在被遮蔽。
然后，如果 skill 存在并被加载，但 agent 仍然不使用它，你就进入了描述的范畴——注意在此处进行迭代的一个成本。Zed 文档指出："对 skill 的 name 或 description 的更改会使当前会话中模型的 prompt 缓存失效"，因此在会话中期进行快速调整是有实际代价的。
在开始重构之前，还有一个需要记住的限制："将 SKILL.md 的主体保持在 500 行以内。将详细材料移至参考文件，并从主体中链接到它们。" 较长的主体是与目录无关的另一个问题，但它们是导致一个确实被触发的 skill 仍无法发挥作用的原因。
在 MemoryLake 中进行设置
上述四个原因都是机械性的，一旦你排除了它们，就会面临一个更难的问题：这些知识中到底有哪些应该属于 skill。可重用的步骤属于 skill。而既定决策——为什么存在这种约定、你拒绝了哪种方法、实际限制是什么——并不是步骤，将它们绑定到某个编辑器的目录中会使它们受到字节预算和信任提示的限制。
MemoryLake 将第二类内容作为一个每个工具都能读取的层来保存，因此这些决策不会与你的 skill 争夺目录空间，也不会在新克隆的仓库中消失。
步骤 1：创建 API 密钥
登录并打开你的工作区设置，然后生成一个 API 密钥。这是你的编辑器和 agent 用来读取同一层的凭据，因此只需创建一次，并确保在你工作的每台机器上都可以访问它。
步骤 2：上传你的第一批记忆
将目前填充在你的 skill 描述中的材料转移过来：约定背后的原因、导致显而易见的方法失效的限制、你不想重新争议的决策。更短的描述，更小的目录，同样可用的知识。
步骤 3：连接你的 AI 和 agent
连接 Zed 以及你使用的任何其他工具。既定决策将无处不在，而你的 skill 则重新专注于它们擅长的事情——agent 可以按需获取的步骤。
这在实践中带来了什么改变
第一个区别是预算不再是一场零和博弈。当描述因推理过程存在于别处而变得简短时，添加一个 skill 就不再会驱逐另一个，而 UI 中的警告也不再是你学会去忽略的东西。
第二个区别是新克隆的仓库可以立即使用。信任门禁是一个明智的安全默认设置——而新贡献者在第一小时内所需的知识不应该被阻挡在它后面。它留下的空白与当 Zed 忘记项目上下文时中所描述的完全相同。
第三个区别是你的组织直觉不再受到惩罚。你想要文件夹是因为你在五个领域中拥有 30 个 skill。保持 skill 扁平，将领域推理放在一个没有布局限制的层中，这样你既能获得结构，又不会失去检索能力。
第四个区别体现在外部 agent 上。Zed 特别指出，它无法控制的 agent 会读取它们自己的指令文件，我们在 Zed 的外部 agent 与上下文中讨论过这一点。编辑器目录之外的一个层是所有这些工具唯一可以共享的东西。
保持 skill 目录可被检索的最佳实践
将描述视为目录空间，而不是文档。 用一句话说明它的作用以及何时使用它。其他所有内容都放入主体或参考文件中。
每次添加后审计总额。 上限适用于总和，因此有意义的数字绝不是针对单个 skill 的。
即使感觉不对，也要保持布局扁平。 根目录的直接子项，不要有分组文件夹。如果需要，可以将分组编码到名称中。
在克隆时主动授予信任。 请记住，在授予信任之前，项目 skill 在目录和斜杠命令中都是不存在的——这使得它们的缺失无法作为判断其他问题的有效信号。
在调试内容之前检查遮蔽情况。 具有相同名称的项目本地 skill 优先，因此你正在读取的全局 skill 可能并不是起作用的那一个。
不要动授权要求。 Zed 规定，即使在受信任的项目中，未经你的明确授权，agent 也无法编辑 SKILL.md 文件或其捆绑的资源，以防止受损的对话修改控制未来对话的 skill。这是一个很好的默认设置；不要绕过它。
决定什么内容到底属于 skill。 步骤，属于。推理，不属于。分类问题与你应该给 AI agent 多少记忆中的问题相同，而正确处理这一问题是保持目录小巧的关键。
结论
Zed 的 skill 系统文档齐全，其限制也已全部公布：名称和描述的 50KB 预算、仅限根目录的直接子项、仅限受信任的工作区以及一个选择性退出字段。让它们变得棘手的是，四个独立的原因会产生一个完全相同的症状，而且其中三个会让你的文件看起来完全正常。
因此，请按顺序排查。首先是信任和布局，因为它们是结构性的。其次是预算，作为一个总额。最后是 frontmatter 和相关性，因为只有当 skill 实际存在于目录中时，这些问题才有意义。然后思考整个过程背后的根本问题——你试图教给 agent 的东西到底是不是一个步骤，或者它是否是一个根本不应该去竞争目录空间的决策。总体而言，了解工具实际加载的内容以及加载顺序是很有价值的；编码 agent 实际读取的内容涵盖了更广泛的图景。