Agent Skills 为什么不生效？2026 Claude Code 技能触发与权限排障

终端里看不到 Skill，或者 Skill 已经出现在列表中，却始终没有读取正文，这是 Agent Skills 不生效 最常见的两类症状。

最快解法：先用最小 Skill 判断是“未发现、未触发，还是执行失败”，再逐项恢复权限和项目上下文；不要一开始就重装 Claude Code、修改模型或重新安装全部插件。

这篇内容适合三类人：正在排查 Claude Code 技能不触发的开发者，可按目录、frontmatter 和日志逐层定位；需要把团队自定义 Skill 放入远程代码库的工程师，可重点查看信任边界、版本和权限控制；负责 AI Coding 环境治理的技术负责人，可用验收步骤建立统一的 Skill 发布流程。

先把故障分成发现、触发和执行三类

Agent Skills 并不是“文件存在，模型就必然调用”。兼容的 Agent 通常先读取技能名称和描述，判断任务是否相关，随后才把 SKILL.md 正文加载进上下文，最后才可能调用其中涉及的工具或脚本。这个渐进式加载过程可以参考 Agent Skills 官方规范。

先用下面的表格确定排查方向：

现象	更可能的故障层	首要检查项	不建议立即做的事
技能列表完全没有目标 Skill	未发现	目录层级、项目根目录、文件名、工作区挂载	不要先修改模型
技能名称和描述可见，但自然语言任务不调用	未触发	description、调用方式、是否限制为手动触发	不要误判为安装失败
Skill 正文已读取，但 Read、Write、Bash 或 MCP 失败	执行失败	工具权限、当前目录、MCP 服务状态	不要直接开启全权限
本地有效，远程或云端无效	加载边界不一致	仓库提交、会话启动目录、远程配置	不要只复制本机目录

“技能被展示”不等于“技能正文已经读取”，“正文已经读取”也不等于“工具调用一定被批准”。如果不先区分这三层，反复修改提示词、重装客户端，通常只能增加变量，不能缩小故障范围。

第一步：确认 SKILL.md 位于正确目录

Claude Code 项目级 Skill 通常采用以下结构：

项目根目录/
└── .claude/
    └── skills/
        └── code-review/
            └── SKILL.md

个人 Skill 则通常放在用户目录下的对应 Skill 路径中。项目 Skill 适合提交到代码库，个人 Skill 只存在于当前机器，不能默认推断它会自动出现在远程 Mac 或云端工作区。具体目录规则应以 Claude Code 官方 Skills 文档 为准。

常见错误包括：

.claude/skills/SKILL.md                         ❌ 少了 Skill 名称目录
.claude/skills/tools/code-review/SKILL.md      ❌ 嵌套层级过深
skills/code-review/SKILL.md                    ⚠️ 不一定属于 Claude Code 项目 Skill
project-a/.claude/skills/...                   ⚠️ 当前会话可能没有进入 project-a

建议逐项检查：

• ✅ 当前终端会话确实从包含 .claude 的项目目录启动。
• ✅ SKILL.md 位于 Skill 名称目录之下，而不是直接放在 .claude/skills/。
• ✅ 文件名没有被改成 skill.md、README.md 或其他名称。
• ✅ 目录名没有隐藏字符、异常空格或容易混淆的字符。
• ✅ Skill 已提交到远程仓库，并且远程工作区检出的分支包含该文件。
• ✅ 如果 Skill 位于子项目，已确认会话启动位置能够覆盖该子项目。
• ✅ 修改顶层目录后，已经重新启动会话或重新加载项目上下文。

嵌套项目尤其容易造成误判。当前会话可能只加载启动目录及其可见范围内的配置；当 Skill 位于子目录时，Agent 还可能需要先接触该目录中的文件，才能判断它与当前任务相关。

Codex 的目录规则不应直接套用 Claude Code。Codex 官方文档使用 .agents/skills 作为项目 Skill 位置，因此同一份 Skill 放在 .claude/skills 后，并不代表其他客户端会从同一路径加载。需要跨客户端使用时，应为每个客户端确认目录、字段和加载边界，而不是只复制文件。

第二步：检查 frontmatter 和触发描述

一个最小可测试的 SKILL.md 可以先保持简单：

---
name: code-review
description: 审查代码变更、识别潜在缺陷，并在用户要求代码审查或风险检查时使用。
---

## 执行步骤

1. 读取相关变更。
2. 说明发现的问题及影响。
3. 在没有明确授权前，不修改源文件。

发现或触发异常时，优先检查以下问题：

1. --- YAML 边界没有闭合。
2. name 为空、重复，或与目录意图严重不一致。
3. description 只有“开发助手”“代码工具”等宽泛词。
4. YAML 缩进错误，或加入了当前客户端不支持的字段。
5. 描述中写了大量实现细节，却没有说明何时应该使用。
6. 描述范围过窄，只覆盖一种几乎不会出现的表达。
7. 描述范围过宽，和其他 Skill 的触发条件互相重叠。

官方说明把 description 视为模型判断是否加载 Skill 的主要信号。描述太宽，可能产生误触发；描述太窄，则可能在意图相近时不被选择。可以把描述写成“任务范围 + 触发条件 + 不处理范围”：

description: 当用户要求审查提交、定位潜在安全问题或评估代码变更风险时使用。仅处理代码审查，不负责自动修复、部署或发布。

从手动调用开始验证

如果技能列表中没有目标 Skill，应继续检查目录和会话边界；如果列表中已经出现名称与描述，则不要再把问题归因于安装失败。Claude Code 支持通过技能名称直接调用，因此手动调用可以作为第二个分界测试。

可依次执行：

/skill-name
请执行一个需要该 Skill 的完整代码审查任务。
请读取该 Skill 的说明，并先列出准备使用的工具。

第一条验证是否可直接调用，第二条验证自然语言触发，第三条帮助判断正文是否真的被读取。若第一条成功、第二条失败，重点应转向 description、触发边界和调用策略，而不是继续移动目录。

第三步：把正文读取和工具调用分开

Skill 被触发后，模型可能只读取说明，却没有调用 Read、Write、Bash 或 MCP 工具。这不一定代表 Skill 没有加载，也可能是任务本身不需要工具，或者工具在当前会话中不可用。

可以建立一组最小测试：

测试 A：要求 Skill 解释自己的任务范围，不允许修改文件。
测试 B：要求 Skill 读取一个明确存在的文件，并报告指定字段。
测试 C：要求 Skill 执行无破坏性的目录检查。
测试 D：要求 Skill 调用一个已经配置且允许使用的 MCP 工具。
测试 E：要求 Skill 进行写入操作，但必须先请求确认。

每次测试只记录一个层级：

• 发现：技能列表中是否出现名称和描述。
• 触发：自然语言任务是否使 Agent 选择该 Skill。
• 读取：输出中是否出现 Skill 正文里的专用步骤、术语或约束。
• 调用：目标工具是否真的被请求。
• 批准：工具请求是成功、等待确认，还是被拒绝。
• 结果：工具返回后，Skill 是否继续完成预期流程。

这套记录方式可以避免把“没有执行 Bash”误判为“Skill 没有读取”。有些 Skill 只负责规范输出或提供判断流程，本来就不需要调用外部工具。

第四步：按风险顺序恢复权限

工具权限不足时，常见表现分别是：

• Read 被拒绝：Skill 无法读取目标文件，后续判断可能停在准备阶段。
• Write 或 Edit 被拒绝：模型能够提出修改方案，但无法落盘。
• Bash 被拒绝：Skill 正文已经加载，但依赖的检查脚本不能运行。
• MCP 被拒绝：Skill 逻辑正常，但外部服务没有连接、没有目标工具，或账号权限不足。

建议按以下顺序恢复：

1. 先只允许 Read、目录遍历和必要的搜索工具。
2. 确认 Skill 能读取测试文件后，再开放一个无破坏性命令。
3. 对写入操作使用需要确认的模式，不要直接开放生产目录。
4. 单独测试 MCP，记录工具名称、参数和返回错误。
5. 最后再考虑是否需要扩大权限范围。

Claude Code 的权限配置会影响工具是否需要确认、是否可以自动执行以及哪些操作必须拒绝。官方权限说明还指出，拒绝规则的优先级高于允许规则，因此不能用一个宽泛的允许配置覆盖明确的禁止项。可参考 Claude Code 官方权限文档。

如果 Skill 依赖 MCP，还要确认 MCP 服务是否连接、目标工具是否出现在工具列表、账号是否具备对应权限，以及返回的是认证错误、工具错误还是业务错误。MCP 工具由服务器暴露给客户端调用，Skill 本身不会凭空创建一个未连接的外部能力。相关机制可查看 MCP SDK 官方文档。

第五步：检查远程项目和信任边界

本地有效、远程无效，通常说明加载来源不同。个人目录中的 Skill 只存在于本机；远程代码库中的项目 Skill 则必须随仓库提交，并确保远程会话检出的提交包含正确文件。云端工作区还可能拥有独立的启动目录、项目设置、账号和 MCP 配置。

如果需要把远程 Mac 作为固定验收环境，先查看 Zutcloud 的 Mac 方案与价格说明，重点确认工作区交付方式、账号隔离和项目数据如何进入测试环境，而不是只比较机器型号。

团队发布前至少检查：

• ✅ Skill 是否与代码一起提交，并能够锁定到可复现的提交。
• ✅ 远程环境是否确实挂载了包含 Skill 的仓库。
• ✅ 工作区启动目录是否能覆盖目标 Skill 的父目录。
• ✅ 项目设置是否允许加载项目级 Skill。
• ✅ Skill 是否依赖本机脚本、环境变量、凭据或 MCP 配置。
• ✅ 第三方提交者是否能够修改 .claude/skills/。
• ✅ Skill 是否包含下载、删除、上传、发布或执行外部脚本的指令。

第三方仓库中的 Skill 本质上属于 Agent 指令。能够修改 Skill 的提交者，可能改变 Agent 的行为；如果会话同时开放 Bash、网络访问或其他高权限工具，未经审查的 Skill 就可能把这些能力用于不符合预期的操作。官方示例仓库中的 安全与受管控 Agent 工具说明 也说明了权限和工具边界的重要性。

因此，审查第三方 Skill 时，不仅要看 Markdown 文案，还要检查脚本、外部链接、环境变量读取、凭据访问和工具调用范围。对生产代码库，建议先在隔离分支或临时远程工作区中运行，不要直接把新 Skill 接入主分支。

建立可回归的 Skill 验收流程

新增或更新 Skill 时，不要只测试一句示例提示。更稳妥的方式是保留一个独立测试项目，放入最小文件、模拟配置和可回滚分支，生产代码库只在验收通过后接入。

1．发现验收

确认路径、目录名称、frontmatter 和仓库提交状态正确，并在目标客户端的技能列表中看到名称与描述。

2．触发验收

准备一条应该触发的任务和一条不应该触发的相邻任务。前者要包含真实工作中的多步意图，后者用于检查描述是否过宽。

3．工具调用验收

分别测试只读、脚本执行、写入和 MCP 调用，并记录允许、拒绝、等待确认和工具返回错误的区别。

4．敏感操作验收

让 Skill 走到删除文件、修改配置、提交代码或访问外部服务之前，确认人工批准仍然生效。

5．版本回滚验收

更新 Skill 后重新执行全部用例。如果触发范围扩大、工具权限变宽或输出格式改变，应能够回退到上一个提交，而不是现场修改生产 Skill。

Codex 官方的 Skill 评估建议也强调，应同时准备“应该触发”和“不应该触发”的多组真实提示，用于比较 Skill 描述对加载决策的影响。(Codex 官方评估说明)

建议在仓库中保留：

skill-validation/
├── fixtures/
├── prompts/
│   ├── should-trigger.txt
│   └── should-not-trigger.txt
├── expected/
├── permissions/
└── rollback-notes.md

如果需要继续定位，可以先阅读 Zutcloud 的帮助中心，再在远程 Mac 工作区中复现这个最小测试项目。对于需要多人共享的 Skill，不要直接复制个人目录，而应从项目提交、权限规则和回滚节点重新验证。

如果当前方案只是把 Skill 放在个人电脑上，问题通常在于环境不可复制、权限容易漂移，而且个人目录不会自然跟随代码库进入远程会话。相比之下，租用 Zutcloud 的 Mac 作为固定测试工作区，可以把 Skill 验收项目、工具配置和回滚流程放在同一套可复现环境中，更适合排查 Agent Skills 不生效 这类持续运行问题；但如果团队长期进行稳定高负载任务、必须拥有物理接口，或要求完全控制硬件，自购 Mac 仍然更合适。