1. 为什么你的 Claude Agent Skills 总是加载失败Claude Agent Skills 是 Anthropic 在 Claude Code 与 Claude Desktop 中引入的一套「提示词扩展机制」——它不是一个可执行函数也不是一段被硬编码进系统提示词的文本而是一组以SKILL.md为核心、通过settings.json与config.toml声明加载路径的文件夹。当你输入「帮我从 report.pdf 提取文本」时Claude 并不是在跑一个正则匹配器而是在 Skill 工具的available_skills列表里做一次纯 LLM 推理选中pdf这个 skill然后把SKILL.md的完整内容作为isMeta: true的用户消息注入对话上下文同时通过contextModifier预先批准Bash(pdftotext:*)、Read、Write这些工具权限。听起来很优雅但真正落地时90% 的人卡在同一个地方配置文件写对了skill 却不出现在available_skills里。原因通常不是模型问题而是加载链路断在了settings.json的skills路径、config.toml的[skills]段、或者SKILL.md的 frontmatter 字段上。这篇内容面向需要在本地 AI 工具链中稳定接入统一 Key/API 通道的开发者从第一性原理拆解 Claude Agent Skills 的配置加载与执行链路给出settings.json与config.toml的可复制骨架并附上验证动作让你在 Claude 工具链中完成一次可复现的配置落地。适合谁看已经在用 Claude Code 或 Claude Desktop、想把自己的领域知识打包成 skill 的开发者正在给团队搭统一 API 通道、需要让多个 skill 共享同一套 Key 的工程同学以及被disable-model-invocation、allowed-tools、when_to_use这些字段绕晕的人。2. 前置准备TaoToken 统一 Key 与 Claude 工具链对接在动settings.json之前先把 API 通道打通。Claude Code 与 Claude Desktop 都支持通过环境变量或配置文件指定ANTHROPIC_BASE_URL与ANTHROPIC_API_KEY这样所有 skill 调用、模型推理都走同一条通道不用在每个 skill 里单独配 Key。TaoToken 提供的就是这样一条统一通道一个 Key 覆盖 Claude 系列模型兼容 Anthropic 原生 API 格式base_url指向https://taotoken.net/api即可。它的价值在于——当你同时跑skill-creator、internal-comms、自定义的pdfskill 时不需要为每个 skill 维护独立的凭证也不用担心某个 skill 触发了模型切换比如model: claude-opus-4-20250514后 Key 失效。具体操作分两步。第一步在 TaoToken 控制台创建一个 API Key建议按项目或按 skill 分组命名方便后续审计。第二步把 Key 写进 Claude Code 的环境变量。macOS/Linux 下编辑~/.zshrc或~/.bashrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥Windows PowerShell 下用$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_API_KEY sk-你的TaoToken密钥写完后source ~/.zshrc或重开终端用echo $ANTHROPIC_BASE_URL确认生效。这一步做完Claude Code 启动时就会把请求打到 TaoToken 通道skill 加载、模型推理、工具调用全部走这一条链路。注意不要把 Key 直接写进settings.json并提交到 Git。环境变量 .gitignore是更稳的做法。如果团队协作用.env.example占位真实 Key 走 CI 注入。3. 可复制配置settings.json 与 config.toml 骨架Claude Agent Skills 的加载来源有四个用户级~/.config/claude/skills/、项目级.claude/skills/、插件提供的 skills、以及内置 skills。settings.json负责声明这些路径和权限config.toml负责声明模型与通道参数。下面给出可直接复制的骨架。3.1 settings.json 骨架{ skills: { paths: [ ~/.config/claude/skills, .claude/skills ], autoLoad: true, maxDescriptionTokens: 15000 }, permissions: { allow: [ Skill(pdf), Skill(skill-creator), Bash(pdftotext:*), Read, Write ], deny: [ Bash(rm:*), Bash(curl:*) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api } }关键字段说明skills.paths是加载根目录Claude Code 会递归扫描每个子目录下的SKILL.mdautoLoad为true时启动即扫描为false时只在你手动/skill-name时加载maxDescriptionTokens控制available_skills列表的 token 预算默认 15000skill 多的时候可以调低逼自己写短描述。permissions.allow里预先放行Skill(pdf)和Bash(pdftotext:*)这样 skill 执行时不会每次都弹权限确认。3.2 config.toml 骨架[api] base_url https://taotoken.net/api api_key_env ANTHROPIC_API_KEY timeout_seconds 120 [model] default claude-sonnet-4-5-20250929 fallback claude-haiku-4-20250514 [skills] enabled true scan_on_startup true skill_dirs [ ~/.config/claude/skills, .claude/skills ] [skills.limits] max_skill_md_bytes 20000 max_available_skills_tokens 15000api_key_env指向环境变量名而不是明文 Key这是和settings.json配合的关键。model.default是会话默认模型fallback是 skill 里写了model: inherit时的兜底。max_skill_md_bytes限制单个SKILL.md大小超过就拒绝加载防止有人把 5000 行文档塞进去把上下文撑爆。3.3 SKILL.md 最小骨架--- name: pdf description: Extract text from PDF documents. Use when user wants to extract or process text from PDF files. allowed-tools: Bash(pdftotext:*),Read,Write version: 1.0.0 --- # PDF 文本提取 ## 概述 从 PDF 文档中提取纯文本输出到指定文件。 ## 指令 ### 步骤 1验证文件存在 使用 Read 工具确认目标 PDF 路径可访问。 ### 步骤 2执行提取 运行 pdftotext {baseDir}/input.pdf {baseDir}/output.txt。 ### 步骤 3读取结果 使用 Read 工具读取 output.txt 并向用户展示。 ## 输出格式 纯文本保留段落换行。 ## 错误处理 若 pdftotext 返回非零退出码报告 stderr 内容并建议检查 PDF 是否加密。name会成为 Skill 工具里的command值description是 Claude 做意图匹配的唯一信号必须写清楚「什么时候用」allowed-tools用逗号分隔支持Bash(git:*)这种通配符限定{baseDir}是运行时变量解析为 skill 安装目录永远不要硬编码绝对路径。4. 验证请求从加载到执行的完整链路配置写完怎么确认 skill 真的被加载了分三步验证。4.1 验证 skill 被发现启动 Claude Code输入/skills或查看启动日志应该能看到类似输出Skills and commands included in Skill tool: pdf, skill-creator, internal-comms如果pdf不在列表里按顺序排查SKILL.md是否存在、frontmatter 是否有name和description、description是否为空、disable-model-invocation是否为true。这四个是过滤条件缺一个就进不了available_skills。4.2 验证 Skill 工具被调用在对话里输入「从 report.pdf 提取文本」观察 Claude 是否返回tool_use{ type: tool_use, id: toolu_123abc, name: Skill, input: { command: pdf } }如果 Claude 直接回答而不调用 Skill 工具说明description写得不够「面向行动」。把description改成「Use when user wants to extract or process text from PDF files」这种明确触发条件的句式比「PDF processing helper」有效得多。4.3 验证上下文注入与工具权限Skill 工具执行后系统会注入两条用户消息一条isMeta: false的元数据用户可见一条isMeta: true的完整SKILL.md内容用户不可见但发给 API。同时contextModifier会把allowed-tools里的工具预先批准。验证方法是看后续 Claude 是否直接调用Bash(pdftotext:*)而不弹权限确认。如果弹了检查settings.json的permissions.allow是否包含对应规则。一个完整的成功结果长这样[Skill 工具调用] command: pdf [元数据注入] The pdf skill is loading [上下文注入] You are a PDF processing specialist... [Bash 执行] pdftotext report.pdf output.txt [Read 执行] 读取 output.txt [输出] 提取的文本内容...5. 本篇常见错排查5.1 skill 不出现description 为空或 when_to_use 未记录过滤条件是cmd.hasUserSpecifiedDescription || cmd.whenToUse。when_to_use字段在代码库里广泛出现但未在官方文档中记录可能是实验性功能。稳妥做法是直接在description里写触发条件不要依赖when_to_use。5.2 权限反复弹窗allowed-tools 格式错误allowed-tools是逗号分隔字符串不是数组。写成allowed-tools: [Bash, Read]会解析失败。正确写法是allowed-tools: Bash(pdftotext:*),Read,Write。另外通配符要写在括号里Bash(pdftotext:*)只允许pdftotext子命令Bash(*)等于放行所有命令安全风险极高。5.3 路径找不到硬编码绝对路径SKILL.md里写Read /home/user/project/config.json在别人机器上必然失败。统一用{baseDir}/config.json运行时解析为 skill 安装目录。这是 skill 可移植性的核心。5.4 上下文爆炸SKILL.md 超过 5000 字SKILL.md建议控制在 5000 字约 800 行以内。超出的详细文档放references/目录用Read({baseDir}/references/detail.md)按需加载。references/里的内容只有被 Read 时才进上下文assets/里的文件只按路径引用、不进上下文两者区别要分清。5.5 模型切换后 Key 失效skill 里写model: claude-opus-4-20250514会覆盖会话模型。如果 TaoToken 通道没开通该模型权限请求会 403。排查方法是在config.toml的[model]段确认default和fallback都在通道支持列表内skill 里的model字段要么删掉用inherit要么确认通道已开通。5.6 加载顺序问题项目级覆盖用户级同名 skill 在~/.config/claude/skills/和.claude/skills/都存在时项目级优先。如果改了用户级 skill 但没生效检查项目目录下是否有同名覆盖。用/skills --verbose可以看到每个 skill 的来源路径。6. 把配置沉淀成可复用的工程资产走到这里你已经完成了从settings.json到config.toml再到SKILL.md的完整配置落地并且验证了 skill 从加载、意图匹配、上下文注入到工具执行的整条链路。剩下的工作是把这套配置沉淀成团队资产把settings.json和config.toml放进项目仓库的.claude/目录把自定义 skill 放进.claude/skills/用.env.example声明ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY的占位真实 Key 走 CI 注入。如果你还在调试阶段想先验证模型通道是否通畅可以直接用模型对话页面发一条测试请求确认base_url和 Key 组合可用。如果你准备把这套配置用于长期编码或 Agent 工作流建议看一下 Coding Plan它把通道、模型、额度打包成可预测的订阅省去每次调 skill 都担心额度波动的麻烦。接入文档里有settings.json和config.toml的完整字段说明遇到本文没覆盖的字段可以直接对照。最后留一个实用技巧每次改完SKILL.md的description用/skills --verbose确认它出现在available_skills列表里再发一条真实请求验证 Claude 能选中它。描述写得好不好不看文档看行为——Claude 选不中就是描述没写对。
Claude Agent Skills 第一性原理深度解析：从 settings.json 到可复制配置
1. 为什么你的 Claude Agent Skills 总是加载失败Claude Agent Skills 是 Anthropic 在 Claude Code 与 Claude Desktop 中引入的一套「提示词扩展机制」——它不是一个可执行函数也不是一段被硬编码进系统提示词的文本而是一组以SKILL.md为核心、通过settings.json与config.toml声明加载路径的文件夹。当你输入「帮我从 report.pdf 提取文本」时Claude 并不是在跑一个正则匹配器而是在 Skill 工具的available_skills列表里做一次纯 LLM 推理选中pdf这个 skill然后把SKILL.md的完整内容作为isMeta: true的用户消息注入对话上下文同时通过contextModifier预先批准Bash(pdftotext:*)、Read、Write这些工具权限。听起来很优雅但真正落地时90% 的人卡在同一个地方配置文件写对了skill 却不出现在available_skills里。原因通常不是模型问题而是加载链路断在了settings.json的skills路径、config.toml的[skills]段、或者SKILL.md的 frontmatter 字段上。这篇内容面向需要在本地 AI 工具链中稳定接入统一 Key/API 通道的开发者从第一性原理拆解 Claude Agent Skills 的配置加载与执行链路给出settings.json与config.toml的可复制骨架并附上验证动作让你在 Claude 工具链中完成一次可复现的配置落地。适合谁看已经在用 Claude Code 或 Claude Desktop、想把自己的领域知识打包成 skill 的开发者正在给团队搭统一 API 通道、需要让多个 skill 共享同一套 Key 的工程同学以及被disable-model-invocation、allowed-tools、when_to_use这些字段绕晕的人。2. 前置准备TaoToken 统一 Key 与 Claude 工具链对接在动settings.json之前先把 API 通道打通。Claude Code 与 Claude Desktop 都支持通过环境变量或配置文件指定ANTHROPIC_BASE_URL与ANTHROPIC_API_KEY这样所有 skill 调用、模型推理都走同一条通道不用在每个 skill 里单独配 Key。TaoToken 提供的就是这样一条统一通道一个 Key 覆盖 Claude 系列模型兼容 Anthropic 原生 API 格式base_url指向https://taotoken.net/api即可。它的价值在于——当你同时跑skill-creator、internal-comms、自定义的pdfskill 时不需要为每个 skill 维护独立的凭证也不用担心某个 skill 触发了模型切换比如model: claude-opus-4-20250514后 Key 失效。具体操作分两步。第一步在 TaoToken 控制台创建一个 API Key建议按项目或按 skill 分组命名方便后续审计。第二步把 Key 写进 Claude Code 的环境变量。macOS/Linux 下编辑~/.zshrc或~/.bashrcexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥Windows PowerShell 下用$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_API_KEY sk-你的TaoToken密钥写完后source ~/.zshrc或重开终端用echo $ANTHROPIC_BASE_URL确认生效。这一步做完Claude Code 启动时就会把请求打到 TaoToken 通道skill 加载、模型推理、工具调用全部走这一条链路。注意不要把 Key 直接写进settings.json并提交到 Git。环境变量 .gitignore是更稳的做法。如果团队协作用.env.example占位真实 Key 走 CI 注入。3. 可复制配置settings.json 与 config.toml 骨架Claude Agent Skills 的加载来源有四个用户级~/.config/claude/skills/、项目级.claude/skills/、插件提供的 skills、以及内置 skills。settings.json负责声明这些路径和权限config.toml负责声明模型与通道参数。下面给出可直接复制的骨架。3.1 settings.json 骨架{ skills: { paths: [ ~/.config/claude/skills, .claude/skills ], autoLoad: true, maxDescriptionTokens: 15000 }, permissions: { allow: [ Skill(pdf), Skill(skill-creator), Bash(pdftotext:*), Read, Write ], deny: [ Bash(rm:*), Bash(curl:*) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api } }关键字段说明skills.paths是加载根目录Claude Code 会递归扫描每个子目录下的SKILL.mdautoLoad为true时启动即扫描为false时只在你手动/skill-name时加载maxDescriptionTokens控制available_skills列表的 token 预算默认 15000skill 多的时候可以调低逼自己写短描述。permissions.allow里预先放行Skill(pdf)和Bash(pdftotext:*)这样 skill 执行时不会每次都弹权限确认。3.2 config.toml 骨架[api] base_url https://taotoken.net/api api_key_env ANTHROPIC_API_KEY timeout_seconds 120 [model] default claude-sonnet-4-5-20250929 fallback claude-haiku-4-20250514 [skills] enabled true scan_on_startup true skill_dirs [ ~/.config/claude/skills, .claude/skills ] [skills.limits] max_skill_md_bytes 20000 max_available_skills_tokens 15000api_key_env指向环境变量名而不是明文 Key这是和settings.json配合的关键。model.default是会话默认模型fallback是 skill 里写了model: inherit时的兜底。max_skill_md_bytes限制单个SKILL.md大小超过就拒绝加载防止有人把 5000 行文档塞进去把上下文撑爆。3.3 SKILL.md 最小骨架--- name: pdf description: Extract text from PDF documents. Use when user wants to extract or process text from PDF files. allowed-tools: Bash(pdftotext:*),Read,Write version: 1.0.0 --- # PDF 文本提取 ## 概述 从 PDF 文档中提取纯文本输出到指定文件。 ## 指令 ### 步骤 1验证文件存在 使用 Read 工具确认目标 PDF 路径可访问。 ### 步骤 2执行提取 运行 pdftotext {baseDir}/input.pdf {baseDir}/output.txt。 ### 步骤 3读取结果 使用 Read 工具读取 output.txt 并向用户展示。 ## 输出格式 纯文本保留段落换行。 ## 错误处理 若 pdftotext 返回非零退出码报告 stderr 内容并建议检查 PDF 是否加密。name会成为 Skill 工具里的command值description是 Claude 做意图匹配的唯一信号必须写清楚「什么时候用」allowed-tools用逗号分隔支持Bash(git:*)这种通配符限定{baseDir}是运行时变量解析为 skill 安装目录永远不要硬编码绝对路径。4. 验证请求从加载到执行的完整链路配置写完怎么确认 skill 真的被加载了分三步验证。4.1 验证 skill 被发现启动 Claude Code输入/skills或查看启动日志应该能看到类似输出Skills and commands included in Skill tool: pdf, skill-creator, internal-comms如果pdf不在列表里按顺序排查SKILL.md是否存在、frontmatter 是否有name和description、description是否为空、disable-model-invocation是否为true。这四个是过滤条件缺一个就进不了available_skills。4.2 验证 Skill 工具被调用在对话里输入「从 report.pdf 提取文本」观察 Claude 是否返回tool_use{ type: tool_use, id: toolu_123abc, name: Skill, input: { command: pdf } }如果 Claude 直接回答而不调用 Skill 工具说明description写得不够「面向行动」。把description改成「Use when user wants to extract or process text from PDF files」这种明确触发条件的句式比「PDF processing helper」有效得多。4.3 验证上下文注入与工具权限Skill 工具执行后系统会注入两条用户消息一条isMeta: false的元数据用户可见一条isMeta: true的完整SKILL.md内容用户不可见但发给 API。同时contextModifier会把allowed-tools里的工具预先批准。验证方法是看后续 Claude 是否直接调用Bash(pdftotext:*)而不弹权限确认。如果弹了检查settings.json的permissions.allow是否包含对应规则。一个完整的成功结果长这样[Skill 工具调用] command: pdf [元数据注入] The pdf skill is loading [上下文注入] You are a PDF processing specialist... [Bash 执行] pdftotext report.pdf output.txt [Read 执行] 读取 output.txt [输出] 提取的文本内容...5. 本篇常见错排查5.1 skill 不出现description 为空或 when_to_use 未记录过滤条件是cmd.hasUserSpecifiedDescription || cmd.whenToUse。when_to_use字段在代码库里广泛出现但未在官方文档中记录可能是实验性功能。稳妥做法是直接在description里写触发条件不要依赖when_to_use。5.2 权限反复弹窗allowed-tools 格式错误allowed-tools是逗号分隔字符串不是数组。写成allowed-tools: [Bash, Read]会解析失败。正确写法是allowed-tools: Bash(pdftotext:*),Read,Write。另外通配符要写在括号里Bash(pdftotext:*)只允许pdftotext子命令Bash(*)等于放行所有命令安全风险极高。5.3 路径找不到硬编码绝对路径SKILL.md里写Read /home/user/project/config.json在别人机器上必然失败。统一用{baseDir}/config.json运行时解析为 skill 安装目录。这是 skill 可移植性的核心。5.4 上下文爆炸SKILL.md 超过 5000 字SKILL.md建议控制在 5000 字约 800 行以内。超出的详细文档放references/目录用Read({baseDir}/references/detail.md)按需加载。references/里的内容只有被 Read 时才进上下文assets/里的文件只按路径引用、不进上下文两者区别要分清。5.5 模型切换后 Key 失效skill 里写model: claude-opus-4-20250514会覆盖会话模型。如果 TaoToken 通道没开通该模型权限请求会 403。排查方法是在config.toml的[model]段确认default和fallback都在通道支持列表内skill 里的model字段要么删掉用inherit要么确认通道已开通。5.6 加载顺序问题项目级覆盖用户级同名 skill 在~/.config/claude/skills/和.claude/skills/都存在时项目级优先。如果改了用户级 skill 但没生效检查项目目录下是否有同名覆盖。用/skills --verbose可以看到每个 skill 的来源路径。6. 把配置沉淀成可复用的工程资产走到这里你已经完成了从settings.json到config.toml再到SKILL.md的完整配置落地并且验证了 skill 从加载、意图匹配、上下文注入到工具执行的整条链路。剩下的工作是把这套配置沉淀成团队资产把settings.json和config.toml放进项目仓库的.claude/目录把自定义 skill 放进.claude/skills/用.env.example声明ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY的占位真实 Key 走 CI 注入。如果你还在调试阶段想先验证模型通道是否通畅可以直接用模型对话页面发一条测试请求确认base_url和 Key 组合可用。如果你准备把这套配置用于长期编码或 Agent 工作流建议看一下 Coding Plan它把通道、模型、额度打包成可预测的订阅省去每次调 skill 都担心额度波动的麻烦。接入文档里有settings.json和config.toml的完整字段说明遇到本文没覆盖的字段可以直接对照。最后留一个实用技巧每次改完SKILL.md的description用/skills --verbose确认它出现在available_skills列表里再发一条真实请求验证 Claude 能选中它。描述写得好不好不看文档看行为——Claude 选不中就是描述没写对。