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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台里创建一个 API Key。第二，记下你的 Key，形如sk-xxxxxxxx，这个 Key 后面要写进环境变量。第三，确认你要用的模型名，Claude 系列在 TaoToken 的模型列表里都有对应标识，选一个你额度够用的即可。
这里有个细节要注意：API Key 不要硬编码进 settings.json 然后提交到 Git。正确做法是写进环境变量，settings.json 里只引用变量名。我见过有人把 Key 直接写进配置文件推到公开仓库，结果额度被刷光，这个坑别踩。
控制台入口我放在这里，方便你直接跳：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。API Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_KEY="sk-你的实际Key"Windows PowerShell：
$env:TAOTOKEN_API_KEY="sk-你的实际Key"想持久化就写进~/.bashrc或~/.zshrc，Windows 用系统环境变量面板。设置完用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_ascii=False)) 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有完整的接口字段说明和错误码对照。
6. 把技能用起来：从单次调试到长期复用
单次跑通只是开始。Agent Skills 真正的价值在于复用——你把一个技能调好之后，可以把它提交到 Git 仓库，团队成员 clone 下来改改 settings.json 里的路径就能用。技能文件夹是纯文本，diff 友好，code review 也方便。
如果你打算长期在编码场景里用 Agent Skills，比如让 Claude 自动跑测试、自动生成迁移脚本、自动整理 changelog，那调用频率会很高，这时候建议走 Coding Plan 这类长期方案，额度更划算，通道也更稳定：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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 就行。
