Claude Skills 在子代理里不生效?从加载、调用到权限逐项排查

主代理能用 Skill,子代理却不执行?通过可下载的最小配置,对照预加载、动态调用、权限与目录故障,区分预期输出和实际运行证据。

两个独立绣绷,小绣绷由自己的橙色线轴供线

Claude Skill 在主会话能用,到了自定义子代理却不执行,先把问题拆成四层:是否发现技能、是否预加载、是否发起调用、加载后能否执行操作。把 Skill 加进工具列表,不等于预加载技能正文;把名字写进 skills:,也不等于授予技能所需的全部工具权限。

当前 Claude Code 官方文档支持子代理在启动时预加载技能,也支持运行中动态调用。旧文章中“子代理绝不能调用 Skill”的结论,需要放回对应版本理解。子代理的 skills 字段负责启动时注入指令,Skill 工具则是运行中的另一条调用路径。

本文针对本地 Claude Code 的自定义代理和项目技能,资料核对日期为 2026 年 11 月 18 日。下载包是编辑制作的诊断样例,已在本地检查文件与结果校验器;本轮没有执行模型推理,也没有测成功率。下文输出均为验收预期,不是 Claude 实际返回的截图或记录。

先判断失败发生在哪一层

现象优先检查要保留的证据
主会话也找不到技能发现路径或调用控制实际技能名、文件位置、frontmatter、组织策略
主会话能用,子代理不遵守技能规则预加载或动态调用真正启动的代理定义、预加载警告或 Skill 调用
Skill 调用被拒绝工具可用性与权限规则被拒绝的准确工具名和匹配规则
指令已加载,但读文件或脚本失败执行操作文件路径、工作目录、被拒操作或脚本报错
换一个目录就失效作用范围或重名启动目录、仓库根目录、实际技能来源

固定一份失败输入,每次只改一个变量。每个正向和失败对照都重新打开主会话、启动新的子代理,避免上一轮答案被带进下一次委派。不要把标记和预期答案放进委派消息或自动加载的项目指令。一次同时移动文件、放开权限、改写 description,即使成功,也无法知道是哪项起效。

需要了解整体概念,可先看 Hooks、Subagents 与 Skills 综合指南(英文)。本文只解决如何定位故障。

1. 建一个能观察结果的最小技能

使用单独的临时目录,准备已安装的 Claude Code 和已有授权的模型连接。推理前记录 claude --version、模型及服务提供方。运行模型可能消耗现有账户额度或 API 余额,下载本例不会自动发起调用。

下载诊断项目,也可以按下文创建文件。压缩包包含同一套配置、提示词、结果校验器和说明。解压到新目录,检查文件后,从该目录启动 Claude Code。样例不含 hooks、网络请求或凭证文件。

skill-diagnostic/
├── .claude/
│   ├── agents/
│   │   ├── audit-preloaded.md
│   │   └── audit-dynamic.md
│   └── skills/
│       └── sample-audit/
│           └── SKILL.md
├── sample.csv
└── check_result.py

将以下内容保存为 .claude/skills/sample-audit/SKILL.md。标记用于观察格式指令是否生效,不是安全机制,也不能单独证明指令从哪里加载。为方便逐字对照,配置与测试输出保留英文。

---
name: sample-audit
description: Audit the synthetic sample.csv fixture and report missing amounts.
---
Read sample.csv in the working directory. Do not change any files.
Return exactly four lines, with no Markdown fences:
SKILL_MARKER=sample-audit-v1
ROWS=<number of data rows, excluding the header>
MISSING_AMOUNT_IDS=<comma-separated IDs, or none>
TOTAL_KNOWN_AMOUNT=<sum of nonempty amounts, two decimal places>
Keep IDs as text. A blank amount is missing, not zero.

输入文件 sample.csv 只有三条合成记录:

id,amount
0007,12.50
0008,
0009,7.50

不要把下文四行预期答案直接粘进委派提示词,否则代理不使用技能也可能复述正确答案。只有要求输出同时依赖技能规则和输入文件,这个对照才有诊断价值。

2. 先检查启动时预加载

保存 .claude/agents/audit-preloaded.md:

---
name: audit-preloaded
description: Audit sample.csv using the preloaded sample-audit instructions.
tools: Read
skills:
  - sample-audit
---
Follow the preloaded audit instructions on sample.csv.
Do not read SKILL.md yourself. If the audit instructions are absent,
report PRELOAD_MISSING rather than inventing a format.

当前预加载列表只处理前 32 个不同的名称。预加载注入技能正文,不会把技能目录里所有参考文件一并读入。本例只有一个技能,不涉及数量上限。

文件准备好后,新开会话并输入:

Use the audit-preloaded subagent to audit sample.csv.
Return its result verbatim. Do not perform the audit in the parent.

先在记录中确认实际选中的是 audit-preloaded。这个代理故意只开放 Read,因此看不到 Skill 调用是正常的。如果代理自己读取了 SKILL.md,或由主代理完成审计,就不能据此认定预加载成功。它们也是得到答案的途径,但不是本次要验证的路径。

预期结果为:

SKILL_MARKER=sample-audit-v1
ROWS=3
MISSING_AMOUNT_IDS=0008
TOTAL_KNOWN_AMOUNT=20.00

只把子代理的回答复制到 result.txt,运行 python3 check_result.py result.txt。校验器检查四行是否符合样例,不能证明加载路径,所以仍需检查会话记录和调试证据。

再做失败对照:将代理 skills: 列表中的 sample-audit 改成不存在的 sample-audit-missing,新开主会话及子代理。预期诊断是 PRELOAD_MISSING,但不能保证模型逐字返回该标签。当前文档说明,缺失或被禁用的预加载项会被跳过,并写入调试警告。完成后恢复原名称。如果失败配置仍输出正常答案,检查主代理是否转交了技能指令、是否选错代理,或其他文件是否泄露了标记和答案。

Claude Code 英文官方文档中的 skills 预加载配置

这是本次保存的英文官方文档截图,仅说明文档机制,不是本轮模型运行成功的截图。

3. 不预加载,单独检查动态调用

保存 .claude/agents/audit-dynamic.md:

---
name: audit-dynamic
description: Audit sample.csv by invoking the sample-audit skill.
tools: Read, Skill
---
First invoke the sample-audit skill using the Skill tool.
Then follow it on sample.csv. Do not read SKILL.md directly.
If the skill cannot be invoked, report INVOCATION_FAILED and the reason.

这里没有 skills: 字段。要求主代理把任务委派给 audit-dynamic,原样返回其结果。动态路径验收需要同时看到:子代理记录中调用了 sample-audit 的 Skill 工具,最终输出也符合上面的四行结果。只有标记正确还不够。

随后只从该代理的 tools: 列表移除 Skill,其他内容不动。预期会出现调用失败,因为代理被要求使用一个没有开放的工具。验证后恢复 Skill。这个失败对照不要同时添加 skills:,否则会引入独立的预加载路径,无法判断动态调用是否成功。

这个显式调用实验只能回答“能不能调用”,不能回答“会不会自动选择”。要检查自动选择,另建一个保留 tools: Read, Skill 的代理,把要求调用 sample-audit 的指令删掉,description 也改成中立的 Audit local CSV files。给它普通审计任务,不提技能名,再看是否出现 Skill 调用。如果显式调用正常而这个独立检查没有触发,再排查技能 description 与任务的匹配程度。显式调用成功,不代表自动选择已通过。

4. 区分调用开关与执行权限

在这个临时项目里逐项修改,每次检查后恢复原配置:

只改一项预期区别处理方式
技能增加 disable-model-invocation: true模型动态调用和预加载都不应使用它需要人工触发的技能继续保留该设置;本例用允许模型调用的技能
改为增加 user-invocable: false隐藏手动命令,本身不禁止模型调用不要仅凭命令菜单里没有它就判断模型不可用
动态代理的显式工具列表移除 Skill动态调用不可用,不影响另一个预加载代理的机制只在需要动态调用的代理中开放 Skill
移除输入文件的访问权限指令可能已加载,但数据无法读取修正准确的文件、工具权限或路径

两个调用开关用途不同,见控制技能由谁调用。不要为了让子代理自动使用部署或破坏性操作技能,就取消原本有意设置的手动限制。

工具出现在列表中,也不代表每次使用都获准。检查 Claude Code 权限规则中的 deny、组织策略,以及准确技能名对应的规则。技能的 allowed-tools 不能补回代理工具集合中已移除的工具,也不能覆盖 deny。实际技能需要执行 Python 脚本时,应先确认指令加载,再检查 Bash 和脚本路径。本例的数据审计只需 Read,刻意减少了一层变量。

不要把 bypassPermissions 当成排错办法。它会改变正在调查的权限条件,三行只读数据不需要这样处理。

5. 排查目录和名称

先核对项目,不要一发现问题就把技能搬到个人全局目录:

pwd
claude --version
ls -l .claude/skills/sample-audit/SKILL.md
ls -l .claude/agents/audit-preloaded.md
ls -l .claude/agents/audit-dynamic.md

代理文件和技能文件分工不同、位置也不同。放在 .claude/agents/ 中的文件,不会因为正文写了“skill”就成为技能。本例让文件夹名、frontmatter 的 name 和预加载项完全一致;不要在 skills: 中写文件路径或 /sample-audit。

在 monorepo 里,packages/web/.claude/skills/ 下的技能不等于仓库根目录技能。嵌套发现与 Claude 实际访问的区域有关。先把样例放在项目根目录验证,再逐步恢复真实子目录。调用名称对应的指令不符合预期时,检查个人与项目技能重名,以及插件命名空间。官方技能发现与命名规则说明了来源优先级;把所有技能搬到全局目录,可能制造新的重名问题。

如果文件位于 ../shared/.claude/skills/sample-audit/SKILL.md,用 claude --add-dir ../shared 启动,并确认新会话能发现它。仅设置 permissions.additionalDirectories 会授予文件访问权限,不会加载该目录的技能。嵌套技能可从所属子目录启动,或在支持的版本中使用 /add-dir,再重复按名调用。报告中记录启动目录和 --add-dir 参数。技能引用相对路径时,还应区分是相对技能目录还是工作目录;本例的 sample.csv 明确相对工作目录。

如果是在会话启动后才创建顶层 skills 目录,先重启再判断“找不到技能”。本例要求先建文件再启动,就是为了排除这一因素。

6. 最小样例仍失败时,留下这些证据

按当前 CLI 参考,新开本地会话并保存私有调试日志:

claude --debug-file ./claude-skill-debug.log

每次只复现一个变体,检查选中的代理、实际技能名、缺失或禁用警告、动态路径里的 Skill 调用,以及被拒绝的 Read 或 Bash 操作。分享前检查日志,它可能包含路径、提示词及其他会话信息,不要公开凭证或无关聊天记录。

可直接使用这个报告模板:

Claude Code 版本 / 操作系统:
模型 / 服务提供方(不含密钥):
工作目录 / 仓库根目录:
代理名称与定义:
技能名称、路径与 frontmatter:
路径:预加载 或 动态调用
准确提示词与合成输入:
预期结果 / 实际结果:
代理选择证据 / 相关工具调用或警告:
本次唯一修改 / 恢复原配置后的结果:

如果卡在启动、鉴权、TLS 或限流,当前请求还不能证明技能加载是否正常。对应问题可看 Claude Code SSL 证书报错排查和Claude Code 限流排查。重试被拒绝的模型请求修不好拼错的预加载名称;修改技能文件也修不好证书错误。

context: fork、SDK 和 Ofox 应该怎么区分?

技能中设置 context: fork,是启动代理执行这个技能的任务;代理中设置 skills:,是代理按自己的指令启动,再加载额外技能内容。按工作流方向选择,不能把两种 frontmatter 互换。详见在子代理中运行技能。

不要假设本例的自定义代理知道你和主代理聊过的一切。必要输入应明确传递。Claude Code 还提供其他 fork 行为,不能把本例的隔离方式推广到所有代理或会话分叉。

如果通过 Claude Agent SDK 启动,另外核对 SDK 技能文档中的文件系统设置和 Skill 工具配置。终端会话能发现本地技能,不代表另一个工作目录里启动的 SDK 进程加载了相同配置。

已经通过 Ofox 接入 Claude Code 的读者,可用 Claude Code 接入文档核对连接配置,用 API 错误处理文档处理请求错误。服务连接与本地技能加载需要分别检查;更换 API 地址本身不会授予 Claude 账户功能,也不会修复本地代理定义。

完成标准应当具体:实际启动了指定代理,记录能看出预期的加载路径,四行输出通过校验,对应的失败对照表现不同。保存这些证据,再逐项恢复真实工作流。