1. 装完 Claude Code 却对着空终端发呆，问题到底出在哪

Claude Code 是一个跑在终端里的 AI 编程助手，能读写文件、执行命令、调用外部工具，适合开发者、运维、数据分析师，以及任何想把重复性电脑操作交给 AI 的人。但很多人装完之后，打开终端，光标一闪一闪，脑子里只有一个念头：然后呢？

我见过太多这样的场景。API Key 配好了，claude命令也能跑起来，问它“你好”它回你“你好”，问它“帮我写个 Python 脚本”它给你一段代码——然后就没有然后了。你关掉终端，觉得这东西好像也就那样，跟网页版聊天机器人没什么区别。

问题不在于 Claude Code 能力不够，而在于你把它当成了一个“问答机器”在用。它真正的价值在于Agent Skills——一套让 AI 自己组装自动化工作流的机制。你可以把它理解成给 AI 写一份“岗位说明书”：告诉它遇到什么情况该做什么、按什么顺序做、做到什么程度算完成。写完之后，你只需要说一句“帮我处理这件事”，剩下的步骤它自己编排。

这篇文章面向的就是“装了 Claude Code 但不知道能干嘛”的新手。我会用一个具体场景——高校教师备课——来演示整套流程：从零创建一个 skill 目录，写好描述文件，让 Claude Code 自己搜索、挑选、组装多个 skill，最后跑通一次从触发到产出的完整验证。全程不需要你写一行代码，但你需要理解 skill 的结构和配置方式。

核心检索词先摆出来：Claude Code 的 Agent Skills 是一套基于文件系统的技能描述机制，每个 skill 是一个包含SKILL.md的目录，里面用自然语言加少量元数据描述“这个技能做什么、什么时候触发、需要哪些工具”。Claude Code 启动时会扫描这些目录，把技能加载进上下文，然后在对话中根据你的意图自动匹配和调用。

换句话说，你不需要记住每个 skill 的命令，也不需要手动一步步指挥。你只需要把工作流描述清楚，AI 自己会决定先调哪个、后调哪个、中间怎么传递数据。

下面从最基础的环境准备开始，一步步走到能跑通一个多 skill 协作的自动化工作流。

2. 前置准备：TaoToken 接入与 Claude Code 环境配置

在开始写 skill 之前，得先确保 Claude Code 能正常调用模型。这里涉及三个东西：Base URL、API Key、Model ID。不管你用哪种接入方式，这三件套缺一不可。

TaoToken 提供的是 API 接入层，官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点直接走 https://taotoken.net/api 。你需要先去控制台创建一个 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建完之后复制出来，后面配置要用。

Claude Code 的配置方式取决于你用的版本和安装方式。最常见的是通过环境变量或者配置文件来指定接入信息。如果你用的是 Claude Code 的 CLI 版本，可以在项目根目录或者用户目录下创建配置文件。我实测下来，最稳妥的方式是同时设置环境变量和项目级配置，避免因为路径问题导致读不到。

先看环境变量方式。在终端里执行：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="你的API Key" export ANTHROPIC_MODEL="claude-sonnet-4-20250514"

这三行分别对应 Base URL、Key 和 Model ID。注意 Base URL 不要加 UTM 参数，直接写 API 端点。Model ID 根据你实际使用的模型来填，TaoToken 支持的模型列表可以在文档里查到，地址是 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

如果你不想每次开终端都 export，可以写进~/.bashrc或~/.zshrc。但更推荐的方式是用 Claude Code 自己的配置文件。在项目根目录创建.claude/settings.json，内容如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的API Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }

这个文件的好处是项目级隔离，不同项目可以用不同的 Key 和模型。如果你用的是 Claude Code 的桌面版或者 IDE 插件，配置入口可能在设置界面里，找到“API 配置”或“模型接入”类似的选项，把上面三个值填进去就行。

配置完成后，验证一下是否生效。在终端里跑：

claude --version

然后进入交互模式，问一句“你现在用的是什么模型”。如果返回的模型名称和你配置的一致，说明接入成功。如果报 401 错误，大概率是 Key 复制错了或者有多余空格。如果报连接超时，检查 Base URL 是否写成了带 UTM 的完整链接——API 调用只需要https://taotoken.net/api这个前缀。

还有一个容易踩的坑：有些教程会让你配ANTHROPIC_AUTH_TOKEN，但 Claude Code 不同版本对环境变量的读取优先级不一样。我建议统一用ANTHROPIC_API_KEY，并且在 settings.json 和 shell 环境变量里保持一致，避免出现“明明配了却读不到”的情况。

环境通了之后，就可以开始装 skill 了。但在此之前，你需要理解 skill 的目录结构，否则后面让 AI 自己创建 skill 的时候，你没法判断它写得对不对。

3. 可复制配置：skill 目录结构与 SKILL.md 写法

Agent Skills 的核心是一个目录，里面至少包含一个SKILL.md文件。这个文件用 Markdown 写，头部是 YAML frontmatter，用来声明 skill 的名称、描述、触发条件等元数据；正文部分用自然语言描述这个 skill 具体做什么、按什么步骤做、需要哪些工具、输出什么格式。

先看一个最小可用的 skill 目录结构：

.claude/skills/ └── find-skills/ └── SKILL.md

find-skills是一个很实用的基础 skill，功能是用关键词搜索可用的 skill。它的SKILL.md大概长这样：

--- name: find-skills description: 根据关键词搜索可用的 Agent Skills，返回匹配的 skill 列表和安装方式 trigger: 当用户需要查找、搜索、发现新的 skill 时触发 --- # Find Skills ## 功能 根据用户提供的关键词，在 skill 仓库中搜索匹配的技能。 ## 使用方式 当用户说“帮我找一下 XX 相关的 skill”时，调用此技能。 ## 步骤 1. 提取用户描述中的核心关键词，翻译成英文 2. 调用 skills 搜索接口，获取匹配结果 3. 返回 skill 名称、描述、仓库地址和安装命令

注意 frontmatter 里的name和description是必须的，trigger是可选的但强烈建议写。Claude Code 在加载 skill 时，会先读 frontmatter 判断这个 skill 是否和当前对话相关，相关才会把正文加载进上下文。这样设计的好处是：你可以装几十个 skill，但不会一次性占满上下文窗口。

安装find-skills的方式有两种。一种是直接用npx skills add命令：

npx skills add https://github.com/vercel-labs/skills --skill find-skills

执行后会提示你选择安装到哪个工具，用方向键选到 Claude Code，按空格选中，回车确认。然后选择 Global 还是 Project，Global 表示全局可用，Project 表示只在当前项目生效。接着选 Symlink 或 Copy，Symlink 的好处是源文件更新后自动同步。最后确认安装。

另一种方式是手动创建目录和文件。如果你已经知道 skill 的内容，可以直接在.claude/skills/下新建目录，把SKILL.md写进去。手动方式适合调试和修改，因为你可以直接编辑文件，不用重新走安装流程。

安装完成后，验证 skill 是否被正确加载。在 Claude Code 里输入：

/skills

如果能看到find-skills出现在列表里，说明加载成功。如果没看到，检查目录层级是否正确——.claude/skills/find-skills/SKILL.md这个路径不能多一层也不能少一层。另外注意文件名必须是大写的SKILL.md，小写在某些系统上会读不到。

有了find-skills之后，你就可以让 Claude Code 自己去搜索和安装其他 skill 了。但这里有个关键点：搜索关键词要用英文。因为 skill 仓库里的描述大多是英文的，中文关键词匹配率很低。比如你想找“备课”相关的 skill，应该搜teaching、lesson-plan、courseware这类词。

下面进入实际组装阶段。我会用一个完整的备课工作流来演示：从描述场景开始，到让 AI 搜索 skill、挑选 skill、创建主控 skill、最后跑通验证。

4. 验证请求：从触发到产出的完整跑通流程

假设你是一个高校教师，要教“数据结构与算法”这门课，面向大二学生。你希望 Claude Code 帮你完成：写教学大纲、生成教案、做 PPT 大纲、出实验题和作业。这些任务如果手动做，每一样都要花不少时间。现在用 Agent Skills 把它们串起来。

第一步，先让 Claude Code 理解你的工作流程。打开 Claude Code，输入：

我是一名高校教师，需要为“数据结构与算法”这门课备课。 请帮我梳理一下从教学大纲到教案、PPT、实验作业的完整流程， 并抽象成一套通用的工作流步骤。

Claude Code 会返回一个分步骤的流程描述，大概包括：确定课程目标和学时分配、编写教学大纲、按周拆分教学内容、为每周写教案、生成 PPT 大纲、设计实验和作业题。这个流程不需要完全准确，它的作用是给后续的 skill 搜索提供上下文。

第二步，用find-skills搜索相关 skill。输入：

基于上面梳理的工作流，帮我搜索有没有相关的 skill。 关键词用英文，比如 teaching、lesson-plan、courseware、syllabus 这些。

Claude Code 会调用find-skills，返回几个匹配的 skill。可能包括lesson-plan-generator、courseware-builder、syllabus-designer之类的。每个 skill 会附带仓库地址和安装命令。

第三步，让 Claude Code 自己挑选最匹配的 skill。不要自己一个个看，直接说：

帮我深入分析每个 skill 的功能描述，挑选出和当前备课流程最匹配的几个。 先不要安装，把挑选结果和理由列出来。

Claude Code 会对比每个 skill 的description和trigger，选出覆盖“大纲编写”“教案生成”“PPT 制作”三个环节的 skill。这一步的关键是让 AI 做决策，因为它读过的 skill 描述比你多，匹配判断更准。

第四步，安装选中的 skill。可以直接让 Claude Code 执行安装：

把刚才选中的三个 skill 安装到当前项目的 .claude/skills/ 目录下。

或者手动执行npx skills add命令逐个安装。安装完成后，用/skills确认列表里能看到它们。

第五步，创建主控 skill。这是整个流程的核心。前面装的三个 skill 需要分别触发，你得记住每个 skill 的名字和调用方式，很麻烦。所以创建一个“主控 skill”，让它来协调其他三个 skill。输入：

我现在需要创建一个主控 skill，作为整个备课工作流的入口。 当我说“帮我备课，课程是 XX”时，这个主控 skill 应该自动： 1. 调用大纲 skill 生成教学大纲 2. 调用教案 skill 按周生成教案 3. 调用 PPT skill 生成课件大纲 4. 把结果整理到一个输出目录里 请帮我设计这个主控 skill 的 SKILL.md，包括 frontmatter 和正文步骤。 设计完之后，启用一个 subagent 去 review 这个设计，检查有没有遗漏或逻辑问题。

Claude Code 会生成一个teaching-workflow的 skill 目录，里面包含SKILL.md。内容大概如下：

--- name: teaching-workflow description: 高校教师备课全流程主控技能，协调大纲、教案、PPT 三个子技能 trigger: 当用户说“帮我备课”“准备 XX 课程的课”时触发 --- # Teaching Workflow ## 功能 作为备课工作流的主控入口，按顺序调用子技能完成教学大纲、教案、PPT 大纲的生成。 ## 前置条件 - 已安装 syllabus-designer、lesson-plan-generator、courseware-builder 三个 skill - 用户提供了课程名称、目标学生年级、备课周数 ## 步骤 1. 确认课程画像：课程名称、学生年级、总学时、备课周数 2. 调用 syllabus-designer 生成教学大纲 3. 按周调用 lesson-plan-generator 生成教案 4. 调用 courseware-builder 生成 PPT 大纲 5. 将所有输出整理到 output/ 目录下，按周分文件夹存放 ## 输出格式 - output/syllabus.md - output/week-01/lesson-plan.md - output/week-01/slides-outline.md - output/week-02/lesson-plan.md - output/week-02/slides-outline.md

第六步，跑通验证。在 Claude Code 里输入：

/teaching-workflow 帮我备课，课程：CS201 数据结构与算法，面向大二学生，先备前两周的课

如果一切正常，Claude Code 会先确认课程画像，然后依次调用三个子 skill，最后在output/目录下生成对应的文件。你可以打开文件检查内容是否完整。如果某个环节卡住了，比如 PPT skill 没有正确触发，可以单独调用那个 skill 排查问题。

整个流程跑下来，你只做了几件事：描述场景、搜索 skill、让 AI 挑选、创建主控 skill、下一条命令。剩下的编排逻辑全部由 Claude Code 自己完成。这就是 Agent Skills 的核心价值——你负责说清楚要什么，AI 负责组装怎么做到。

5. 常见报错排查：401、local proxy failed、reading choices 怎么处理

即使配置看起来没问题，实际跑的时候还是会遇到各种报错。下面列几个我踩过的坑和对应的排查思路。

401 错误：Unauthorized

这是最常见的接入问题。报错信息通常是：

API error: 401 Unauthorized - invalid api key

原因一般有三个：Key 复制时带了空格或换行、Key 已经过期或被删除、环境变量和配置文件里的 Key 不一致。排查步骤：先在终端里执行echo $ANTHROPIC_API_KEY，确认输出的 Key 和你复制的一致。然后检查.claude/settings.json里的 Key 是否相同。如果用了多个配置文件，注意优先级——项目级配置会覆盖全局配置。最后去 TaoToken 控制台确认 Key 状态是否正常，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

local proxy failed / connection refused

报错信息类似：

Error: connect ECONNREFUSED 127.0.0.1:xxxx local proxy failed

这通常是因为 Claude Code 尝试走本地代理，但代理没有启动或者端口不对。检查你的环境变量里有没有HTTP_PROXY、HTTPS_PROXY或ALL_PROXY的设置。如果有，确认代理服务是否在运行。如果不需要代理，直接 unset 掉：

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

然后重新启动 Claude Code。另外检查ANTHROPIC_BASE_URL是否被错误地写成了本地地址，正确的应该是https://taotoken.net/api。

reading choices 报错

这个报错通常出现在 skill 加载阶段：

Error reading choices: unexpected end of JSON input

原因是某个 skill 的SKILL.mdfrontmatter 格式不对，比如 YAML 语法错误、缺少闭合的---、或者description字段里有特殊字符没有转义。排查方法：逐个检查.claude/skills/下每个SKILL.md的 frontmatter，确保---成对出现，字段值用引号包裹。可以用在线 YAML 校验工具检查语法。

OAuth 相关报错

如果你看到：

OAuth error: invalid_grant

说明 Claude Code 在尝试用 OAuth 方式认证，但你配置的是 API Key 方式。检查是否有残留的 OAuth token 文件，通常在~/.claude/目录下。删掉credentials.json或类似文件，强制走 API Key 认证。另外确认ANTHROPIC_API_KEY已经正确设置，Claude Code 会优先使用 API Key 而不是 OAuth。

skill 不触发

装了 skill 但 Claude Code 不调用它。先确认/skills列表里能看到。如果能看到但不触发，检查trigger字段的描述是否和你的输入匹配。比如 trigger 写的是“当用户说帮我备课”，但你输入的是“准备一下课程”，可能匹配不上。解决办法是把 trigger 写得更宽泛，或者直接在输入里包含触发关键词。

CC Switch / Cline MCP / Codex auth.json 相关

如果你同时用了多个工具，注意配置隔离。CC Switch 用来切换不同的 API 端点，Cline MCP 是另一个 AI 编程工具的配置，Codex 的auth.json是 OpenAI 体系的认证文件。这三者和 Claude Code 的配置不要混在一起。Claude Code 只读.claude/settings.json和环境变量，不会读auth.json。如果你在 Cline 里配了 TaoToken 的 Base URL 和 Key，想在 Claude Code 里也用，需要单独再配一遍。三件套始终是：Base URL 填https://taotoken.net/api，Key 填你创建的 API Key，Model ID 填你实际使用的模型名称。

遇到报错不要慌，先把完整报错信息复制出来，丢给 Claude Code 让它分析。大多数配置问题它都能给出排查方向。这也是 Agent Skills 思路的延伸——用 AI 解决 AI 自己的问题。

6. 把闲置的 Claude Code 变成工作流组装器

回到最开始的问题：装了 Claude Code 不知道能干嘛。答案不是去学更多命令，而是换一个使用方式——从“问它问题”变成“给它写岗位说明书”。

Agent Skills 的本质是把你的工作流程显式地写下来，让 AI 按图索骥。你不需要会写代码，只需要能把一件事的步骤说清楚。find-skills帮你找现成的技能，主控 skill 帮你协调多个技能，Claude Code 负责执行和编排。三者组合起来，就是一个能自己组装工作流的助手。

如果你还没配好接入，先去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 创建一个 Key，然后按第 2 节的配置片段填好 Base URL、Key 和 Model ID。配好之后，从find-skills开始装，再找一个你工作中重复性最高的场景，试着写一个主控 skill。第一次可能会遇到 skill 不触发或者输出格式不对的问题，把报错丢回给 Claude Code，让它自己修。

长期做编码或者 Agent 开发的话，可以了解一下 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合需要稳定调用和批量任务的场景。如果只是想先验证模型效果，可以直接用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 试几句，确认接入正常再往下走。

最后说一个实用技巧：主控 skill 写完之后，先别急着跑完整流程。单独调用每个子 skill，确认它们各自能正常输出。子 skill 都通了，再串起来跑主控。这样出问题的时候容易定位是哪个环节的锅。另外，skill 的SKILL.md是可以随时改的，跑一次发现哪里不对，直接编辑文件，不用重新安装。改完在 Claude Code 里输入/reload重新加载即可。