1. 为什么我盯上了 settings.json 这个入口Anthropic Claude Agent Skills 是 Claude 在 Agent 场景下的一套技能扩展机制它允许你把某个垂直任务的指令、脚本、模板打包成一个文件夹让 Claude 在需要时动态加载。适合谁适合已经在用 Claude Code 或 Claude API 做自动化、又不想每次都把一大段提示词复制粘贴的开发者。我最初接触它的时候第一反应是“这不就是个高级提示词模板吗”直到我把一个自定义 Skill 跑通、看到 Claude 真的按我写的规则去调用脚本才意识到它和普通提示词的区别在于技能是可寻址、可复用、可版本管理的。但真正卡住我的不是 SKILL.md 怎么写而是 settings.json。这个文件决定了 Claude Code 去哪里找技能、允不允许执行脚本、权限边界在哪。很多人照着文档写完 SKILL.md结果 Claude 根本不加载八成是 settings.json 没配对。这篇就按“从 settings.json 到可复用技能配置”这条线走一遍给你一份能直接抄的配置骨架再配一个最小验证步骤让你在本地十分钟内确认技能生效。在开始之前先说清楚Claude Agent Skills 的规范由 Anthropic 定义技能文件夹本身是纯文本 可选脚本不依赖任何特殊运行时。你需要的只是一个能跑 Claude Code 的终端环境以及一个能访问 Claude 模型的凭证。凭证这块我用的是 TaoToken 的接入方式后面会给出具体配置因为它对国内网络环境比较友好省去不少折腾。2. TaoToken 前置把模型通道先打通Claude Agent Skills 本身是本地文件系统层面的东西但技能要真正“跑起来”最终还是要调用 Claude 模型。所以第一步不是写技能而是确保你的 Claude Code 能正常连上模型。我试过直接配官方通道在部分网络环境下握手会超时后来换成 TaoToken 的接入点就稳定多了。TaoToken 在这里扮演的是模型访问通道的角色你通过它拿到 API Key然后把 Claude Code 的请求指向对应的 API 地址。它不是什么“中转黑盒”就是一个标准的 OpenAI/Anthropic 兼容接口层你可以在控制台里管理 Key、查看用量。对于 Agent Skills 这种需要频繁调用模型的场景通道稳定性直接决定了你的调试体验。具体操作分三步。第一去官网注册并进入控制台地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台里创建一个 API Key。第二记下你的 Key形如sk-xxxxxxxx这个 Key 后面要写进环境变量。第三确认你要用的模型名Claude 系列在 TaoToken 的模型列表里都有对应标识选一个你额度够用的即可。这里有个细节要注意API Key 不要硬编码进 settings.json 然后提交到 Git。正确做法是写进环境变量settings.json 里只引用变量名。我见过有人把 Key 直接写进配置文件推到公开仓库结果额度被刷光这个坑别踩。控制台入口我放在这里方便你直接跳https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建完 Key 后建议先复制到本地密码管理器页面刷新后就不再完整显示了。3. 可复制配置settings.json 骨架与技能目录结构这一节是全文的核心。Claude Code 读取技能的位置和权限都由 settings.json 控制。这个文件通常放在项目根目录的.claude/下或者用户级的~/.claude/下。项目级配置只对当前项目生效用户级配置对所有项目生效。调试阶段我建议用项目级避免污染全局。先看目录结构。一个标准的技能仓库长这样my-skills/ ├── settings.json └── skills/ └── pdf-extract/ ├── SKILL.md ├── scripts/ │ └── extract.py └── templates/ └── output.mdskills/目录下每个子文件夹就是一个独立技能。SKILL.md是必需的其余脚本和模板可选。Claude 在激活技能时会把 SKILL.md 的 Markdown 内容作为上下文注入同时按需读取 scripts 和 templates 里的文件。然后是 settings.json 的骨架。下面这份配置我实测可用字段含义我逐行注释{ skills: { enabled: true, paths: [ ./skills ], autoLoad: false, maxConcurrent: 3 }, permissions: { allowFileRead: true, allowScriptExec: true, allowedScriptDirs: [ ./skills/*/scripts ], denyPatterns: [ **/.env, **/secrets/** ] }, model: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, modelName: claude-sonnet-4-20250514 } }逐段解释。skills.enabled是总开关设为 false 时所有技能都不加载。skills.paths是技能搜索路径支持相对路径和绝对路径可以写多个。skills.autoLoad控制是否在会话启动时自动加载全部技能设为 false 时你需要手动触发调试阶段建议 false避免无关技能干扰。skills.maxConcurrent限制同时激活的技能数量防止上下文爆炸。permissions这块是安全边界。allowFileRead允许技能读取文件allowScriptExec允许执行脚本。allowedScriptDirs用通配符限定只有技能目录下的 scripts 能被执行这样即使技能里写了恶意路径也跑不出去。denyPatterns是黑名单.env和secrets目录一律拒绝读取这个一定要配否则技能可能把你的密钥读进上下文。model段就是接 TaoToken 的地方。baseUrl填https://taotoken.net/api注意这里不加任何 UTM 参数保持接口地址干净。apiKeyEnv写环境变量名不要写 Key 本身。modelName填你要用的 Claude 模型标识。环境变量这样设置Linux/macOS 下export TAOTOKEN_API_KEYsk-你的实际KeyWindows PowerShell$env:TAOTOKEN_API_KEYsk-你的实际Key想持久化就写进~/.bashrc或~/.zshrcWindows 用系统环境变量面板。设置完用echo $TAOTOKEN_API_KEY确认能打印出来。接下来是 SKILL.md 的最小内容。放在skills/pdf-extract/SKILL.md--- name: pdf-extract description: 从 PDF 文件中提取表单字段并输出结构化 JSON --- # PDF 提取技能 当此技能被激活时Claude 应执行以下流程 1. 确认用户提供的 PDF 文件路径存在且可读。 2. 调用 scripts/extract.py 处理该文件。 3. 将脚本输出的 JSON 直接返回给用户不要额外解释。 ## 示例 用户输入使用 pdf-extract 处理 ./docs/form.pdf 预期行为执行脚本并返回 {name: ..., address: ...} ## 约束 - 仅处理本地文件不接受 URL。 - 若脚本报错原样返回错误信息不要尝试自行修复。YAML frontmatter 里的name必须和文件夹名一致description会出现在技能列表里供你选择。正文部分用自然语言写清楚触发条件和执行步骤Claude 会把它当作系统级指令来遵循。配套的scripts/extract.py可以先用一个占位脚本验证链路import sys import json def main(): if len(sys.argv) 2: print(json.dumps({error: no file path provided})) return file_path sys.argv[1] result { file: file_path, status: parsed, fields: {name: demo, address: demo address} } print(json.dumps(result, ensure_asciiFalse)) if __name__ __main__: main()这个脚本不真的解析 PDF只是返回固定结构目的是先确认“Claude 能调用脚本并把结果带回来”这条链路通不通。链路通了再换成真正的解析逻辑。4. 验证请求确认技能真的生效配置写完怎么知道技能被加载了分两步验证。第一步验证模型通道第二步验证技能调用。先验证通道。在终端里直接发一个最小请求curl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [ {role: user, content: 只回复两个字通了} ] }如果返回的 JSON 里content字段包含“通了”说明通道没问题。如果返回 401检查 Key 和环境变量返回 404检查 baseUrl 和模型名返回超时检查网络。通道通了之后进入 Claude Code 会话输入技能列表命令不同版本命令可能略有差异常见的是/skills或/skill list。你应该能看到pdf-extract出现在列表里状态是 available。如果没出现回到 settings.json 检查skills.paths是否指向了正确的目录以及enabled是否为 true。然后触发技能。在会话里输入使用 pdf-extract 处理 ./docs/form.pdf预期结果是 Claude 调用scripts/extract.py并把脚本输出的 JSON 返回。你会看到类似这样的响应{ file: ./docs/form.pdf, status: parsed, fields: { name: demo, address: demo address } }看到这个 JSON说明整条链路——settings.json 加载、SKILL.md 解析、脚本执行、结果回传——全部打通。这时候你可以把 extract.py 换成真实的 PDF 解析逻辑技能就正式可用了。如果你更想先在对话界面里手动验证模型行为可以走模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在里面直接粘贴 SKILL.md 的内容作为系统提示观察 Claude 的反应确认指令写法没有歧义再放进技能目录。5. 本篇常见错排查技能不生效的原因就那么几类我按出现频率排一下。第一类settings.json 位置放错。项目级配置必须在项目根目录的.claude/settings.json不是根目录直接放settings.json。用户级在~/.claude/settings.json。放错位置 Claude Code 根本读不到技能列表永远是空的。第二类YAML frontmatter 格式错误。name和description之间不能有空行冒号后面要有一个空格---必须是文件第一行。我见过有人在---前面多敲了一个空行整个 frontmatter 就失效了Claude 把 SKILL.md 当普通文本读技能自然不加载。第三类脚本没有执行权限。Linux/macOS 下extract.py需要chmod x或者你在 SKILL.md 里明确写python3 scripts/extract.py而不是直接./scripts/extract.py。Windows 下注意路径分隔符SKILL.md 里统一用正斜杠/Claude 会自己转换。第四类权限配置太严导致脚本被拒。allowedScriptDirs的通配符写法要对./skills/*/scripts匹配的是 skills 下任意一级子目录的 scripts 文件夹。如果你写成./skills/scripts那只有 skills 根下的 scripts 能跑子目录里的全被拒。排查时可以先临时把allowScriptExec设为 true 且不配allowedScriptDirs确认链路通了再收紧。第五类模型名写错。TaoToken 的模型标识和官方可能略有差异写错会返回 404 或 model not found。去控制台的模型列表页核对一下当前可用的 Claude 模型名复制粘贴别手敲。第六类环境变量没生效。你在当前终端export了但 Claude Code 是在另一个终端或 IDE 里启动的读不到。解决办法是把环境变量写进 shell 配置文件然后重启 IDE 或终端。验证方法是在启动 Claude Code 的同一个终端里echo $TAOTOKEN_API_KEY。第七类技能名冲突。两个技能文件夹的name相同Claude 只会加载其中一个行为不可预测。命名时加前缀区分比如myorg-pdf-extract。排障时如果拿不准是配置问题还是通道问题可以先用模型对话入口发一条普通消息确认模型本身能回再回来查技能配置。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有完整的接口字段说明和错误码对照。6. 把技能用起来从单次调试到长期复用单次跑通只是开始。Agent Skills 真正的价值在于复用——你把一个技能调好之后可以把它提交到 Git 仓库团队成员 clone 下来改改 settings.json 里的路径就能用。技能文件夹是纯文本diff 友好code review 也方便。如果你打算长期在编码场景里用 Agent Skills比如让 Claude 自动跑测试、自动生成迁移脚本、自动整理 changelog那调用频率会很高这时候建议走 Coding Plan 这类长期方案额度更划算通道也更稳定https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。配置方式和单次调用一样只是 Key 的计费模式不同。还有一个实践建议技能目录按领域分仓库不要把所有技能塞进一个文件夹。比如skills-docs/、skills-testing/、skills-deploy/各一个仓库settings.json 的paths里按需引入。这样不同项目可以组合不同的技能集避免加载一堆用不上的技能占用上下文。最后提醒一句技能里的脚本执行权限是双刃剑。allowScriptExec打开后Claude 理论上可以执行你技能目录下的任何脚本。所以技能仓库的来源要可信第三方技能引入前先读一遍 SKILL.md 和 scripts 里的代码确认没有奇怪的文件读写或网络请求。denyPatterns一定要配把.env、id_rsa、credentials这类路径全挡掉。链路通了之后你可以试着把 extract.py 换成真实逻辑或者新建第二个技能验证多技能共存。settings.json 的骨架不用改加一个文件夹、加一个 SKILL.md 就行。