本地AI Agent终极指南：Claude Code + Skills深度实战，从原理到落地全解析

本文由莫潇羽@无忆研习社原创撰写，转载请注明出处：www.wuyi.wiki

写在前面

折腾AI工具这些年，我见证了太多"概念先行、落地困难"的产品。从最早的ChatGPT插件，到后来的各种Agent框架，很多东西看起来很美好，真正用起来却一地鸡毛。但这一次，当我花了将近两周时间深入研究Claude Code和Skills系统之后，我必须说——这可能是目前最值得普通人投入精力学习的本地AI Agent方案。

为什么这么说？因为它同时满足了三个关键条件：门槛足够低、能力足够强、成本足够省。更重要的是，它不是什么实验性的玩具，而是已经被Anthropic官方验证过、并且正在大规模商用的成熟方案。

我是莫潇羽，无忆研习社（www.wuyi.wiki）的站长。这篇文章，我会把自己这段时间的研究心得、踩过的坑、以及总结出来的最佳实践，毫无保留地分享给大家。全文超过一万三千字，建议收藏后慢慢阅读。

一、理解本地Agent的本质：为什么Claude Code值得关注

1.1 从"对话"到"执行"的范式转变

在过去的两年里，我们和AI的交互方式主要是"对话"——你问它答，它给建议你来执行。但这种模式有一个根本性的问题：AI再聪明，也只是一个"顾问"，真正干活的还是你自己。

想象一下这个场景：你让AI帮你整理一个装满杂乱文件的文件夹。传统的AI会给你一个很详细的分类方案，告诉你应该创建哪些子文件夹、哪些文件应该放到哪里。然后呢？然后你得自己一个一个地去移动文件。AI说得再好，活儿还是你干。

Claude Code和Cowork代表的本地Agent方案，彻底改变了这种状况。它们不是给你建议，而是直接帮你把活儿干了。你只需要说一句"帮我把Downloads文件夹按文件类型整理一下"，几分钟后，整理好的文件夹就呈现在你面前。

这就是从"对话"到"执行"的范式转变。而这个转变的背后，是一整套精心设计的技术架构在支撑。

1.2 Claude Code、Cowork和Skills的关系

很多朋友刚接触这些概念的时候会有点懵：Claude Code是什么？Cowork又是什么？Skills又是怎么回事？它们之间是什么关系？

让我用一个比喻来解释。

Claude Code可以理解为一台"发动机"。它是一个命令行工具，能够接收自然语言指令，然后在你的电脑上执行各种操作。它的核心能力包括：读写文件、运行代码、安装软件包、调用系统命令等等。本质上，它是一个拥有"手脚"的AI——不仅能"想"，还能"做"。

Cowork则是基于这台发动机打造的一辆"轿车"。它把Claude Code的底层能力包装成了一个图形化的应用，让不懂命令行的普通用户也能享受到本地Agent的便利。你不需要打开黑乎乎的终端，只需要在桌面应用里打字聊天，Claude就能帮你处理文件、生成报告、整理数据。

但Cowork有一个门槛：它目前需要订阅Claude的Max计划，这意味着每月要花费不菲的订阅费用。对于只是想尝鲜或者轻度使用的朋友来说，这个成本有点高。

这就是Claude Code的价值所在。它是免费的（只需要支付模型调用的API费用），而且通过一些配置，你可以用国产大模型来驱动它，把成本压缩到几乎可以忽略不计的程度。

Skills则是这套系统的"技能包"。如果说Claude Code是一个什么都会一点的通才，那么Skills就是让它在特定领域变成专家的"培训手册"。比如，你可以给它安装一个"PDF处理"的Skill，它就能像专业的PDF编辑软件一样处理各种PDF操作；安装一个"视频生成"的Skill，它就能根据你的描述自动生成视频。

这三者的关系可以总结为：Claude Code是基础能力层，Skills是专业能力层，Cowork是易用性包装层。而我们这篇文章要讲的，就是如何用Claude Code + Skills，打造一个功能媲美Cowork、但成本低得多的本地Agent。

1.3 为什么现在是最佳入场时机

我关注Claude Code已经有一段时间了，但直到最近才开始大力推荐它，原因有三个：

第一，Skills系统已经足够成熟。Anthropic在去年十月就发布了Skills功能，但当时的生态还比较单薄，可用的Skill不多，创建自定义Skill的流程也比较繁琐。而现在，官方的Skills库已经涵盖了文档处理、数据分析、创意设计等多个领域，第三方社区贡献的Skills更是数以万计。可以说，你能想到的大部分需求，都已经有现成的Skill可以使用。

第二，国产大模型的兼容性大幅提升。之前使用Claude Code，要么登录Claude官方账号（国内网络环境下困难重重），要么购买Anthropic的API（需要国际信用卡，价格也不便宜）。但现在，智谱、MiniMax、Kimi等国产大模型厂商都推出了兼容Claude Code的API接口，几十块钱就能用一个月，对普通用户来说友好太多了。

第三，Agent Skills已成为行业开放标准。Anthropic在去年底将Agent Skills规范作为开放标准发布，OpenAI、Google、Microsoft、Cursor等各大厂商都已经跟进支持。这意味着你在Claude Code里创建和使用的Skills，未来可以无缝迁移到其他AI工具中。投入精力学习这套体系，是一项长期有价值的投资。

二、深入理解Skills：不只是提示词，而是AI的"职业培训"

2.1 Skills的本质是什么

在讲具体操作之前，我想先帮大家建立对Skills的正确认知。这一点非常重要，因为我发现很多人把Skills简单理解为"高级提示词"或者"预设的对话模板"，这是一个很大的误区。

Skills本质上是一种"程序化知识"的封装方式。

什么是程序化知识？就是那种"知道怎么做一件事"的知识。比如，怎么把PDF文件分页、怎么把Word文档转换成特定格式、怎么根据品牌规范设计一张海报——这些都是程序化知识。

AI模型虽然聪明，但它的"聪明"更多体现在理解和生成文本上。对于具体的、步骤化的操作任务，尤其是那些涉及特定软件、特定格式、特定流程的任务，AI往往做得不够好。不是因为它"不会"，而是因为它缺乏标准化的执行流程。

Skills解决的就是这个问题。它通过一个结构化的文件（SKILL.md），把"怎么做这件事"的知识清晰地描述出来，让AI在执行任务时有章可循。

2.2 一个Skill的组成结构

每个Skill都是一个文件夹，里面至少包含一个SKILL.md文件。这个文件分为两部分：

头部的YAML元数据，用来告诉Claude"这个Skill是干什么的、什么时候应该使用它"。就像一本书的目录和简介。

正文的Markdown内容，包含具体的指令、示例、注意事项等。就像书的正文内容。

让我用一个简单的例子来说明。假设我们要创建一个"代码解释"的Skill：

---
name: explain-code
description: 用生动的类比和图示来解释代码的工作原理。当用户询问"这段代码是怎么工作的"或者想要理解某个代码库时使用。
---

这是元数据部分。name字段会变成斜杠命令（/explain-code），description则帮助Claude判断什么时候应该自动加载这个Skill。

# 代码解释技能

当解释代码时，请遵循以下步骤：

1. 先打个比方：把代码的功能比作日常生活中的事物，让非技术人员也能理解
2. 画个图：用ASCII艺术画出代码的流程、结构或者组件关系
3. 逐步讲解：一步一步说明代码的执行过程
4. 提醒陷阱：指出这段代码容易出错的地方或者常见的误解

## 示例

用户问："这个排序函数是怎么工作的？"

好的回答应该包含：
- 用"整理扑克牌"来比喻排序过程
- 画出数据流动的示意图
- 解释每一行代码的作用
- 提醒边界情况的处理

这就是正文部分。当Claude加载这个Skill后，它就会按照这些指令来解释代码。

2.3 Skills的三级加载机制

Skills有一个很巧妙的设计：它不会一次性把所有内容都塞进Claude的上下文窗口，而是采用按需加载的方式。

第一级是元数据，也就是Skill的名称和描述。这部分内容始终在上下文中，大概只占100个词左右。Claude会根据这些信息判断哪些Skills可能和当前任务相关。

第二级是SKILL.md的正文。只有当Claude判断某个Skill确实需要使用时，才会把正文内容加载进来。这样既保证了灵活性，又节省了宝贵的上下文空间。

第三级是附属资源，比如脚本文件、模板文件、参考文档等。这些内容通常是在Skill执行过程中根据需要读取的，甚至有些脚本可以直接执行而不需要读入上下文。

这种三级加载机制的好处是显而易见的：你可以安装很多个Skills，但它们不会互相争抢上下文空间。Claude会智能地判断哪些需要用、什么时候用，实现了能力扩展和资源效率的完美平衡。

2.4 Skills和提示词的本质区别

说到这里，你可能会问：这和写一个很详细的提示词有什么区别？

区别大了。

第一，可复用性。一个好的Skill可以被无数次使用，而且保证每次的执行标准是一致的。提示词呢？每次对话都要重新输入，稍微改一个字可能效果就不一样了。

第二，可组合性。多个Skills可以像乐高积木一样组合使用。比如，你可以同时启用"品牌设计规范"Skill和"PPT制作"Skill，Claude就能做出既符合品牌规范、又具有专业水准的演示文稿。提示词很难做到这种灵活的组合。

第三，可分享性。Skills采用开放的文件格式，可以通过Git仓库、npm包等方式分享给其他人。社区创建的优秀Skills，你一条命令就能安装到自己的环境里使用。

第四，可进化性。Skills可以包含可执行的脚本代码。这意味着一些复杂的操作可以用代码实现，而不是依赖AI的"即兴发挥"。当某个操作的最佳实践发生变化时，只需要更新Skill里的代码，所有使用这个Skill的任务都会自动受益。

从某种意义上说，Skills是把"人类专家"的知识和经验转化成了AI可以直接使用的"职业技能"。这比单纯的提示词工程要高出一个维度。

三、环境准备：手把手教你安装Claude Code

现在进入实操环节。这部分内容我会写得非常详细，争取让完全没有编程基础的朋友也能跟着做下来。预计用时在一小时左右，取决于你的网络状况。

3.1 准备工作

在开始之前，你需要准备以下条件：

网络环境：由于安装过程中需要从国外服务器下载一些软件包，建议使用能够访问国际网络的环境。如果你平时能正常使用ChatGPT、Gemini这些工具，那网络应该没问题。

操作系统：Windows 10/11、macOS、Linux都支持。本文会同时照顾Windows和macOS用户，给出两套操作指引。

耐心和信心：不要被黑乎乎的终端界面吓到。终端本质上就是一个"命令行版的聊天窗口"，你输入命令，它给你反馈，仅此而已。

3.2 认识你的终端

终端（Terminal）是我们和操作系统进行命令交互的工具。在图形界面时代，我们已经习惯了用鼠标点点点来操作电脑，但很多专业工具和底层操作仍然需要通过命令行来完成。

macOS用户：按下 Command + 空格，输入"Terminal"或"终端"，就能打开终端应用。你会看到一个带有简洁文字界面的窗口，光标在那里闪烁等待你的输入。

Windows用户：在开始菜单旁边的搜索框里输入"PowerShell"，点击"Windows PowerShell"打开。或者你也可以使用传统的"命令提示符"（CMD），在搜索框输入"cmd"即可。

打开终端后，你会看到类似这样的界面：

用户名@电脑名 ~ %

或者（Windows）：

PS C:\Users\用户名>

这就是命令行提示符，表示系统正在等待你的输入。现在，让我们开始正式的安装流程。

3.3 安装Node.js

Node.js是一个JavaScript运行环境，Claude Code的安装和运行依赖它。如果你的电脑上已经安装过Node.js，可以跳过这一步。

检查是否已安装：在终端中输入以下命令，然后按回车：

node --version

如果显示类似v24.13.0这样的版本号，说明已经安装好了，可以直接跳到下一节。如果提示"command not found"或者"不是内部或外部命令"，则需要安装。

下载安装包：用浏览器打开 https://nodejs.org/en/download/，网站会自动识别你的操作系统。直接点击下载按钮，下载对应的安装包即可。

• macOS用户下载.pkg文件
• Windows用户下载.msi文件

安装过程：下载完成后，双击安装包开始安装。安装向导会引导你完成整个过程，全部使用默认选项即可，不需要修改任何设置。安装完成后，关闭终端窗口再重新打开一个，然后用node --version命令验证安装是否成功。

3.4 Windows用户额外步骤：安装Git

Git是一个版本控制工具，在安装Skills的时候会用到。macOS和Linux系统通常自带Git，Windows用户需要单独安装。

下载：打开 https://git-scm.com/downloads/win，页面上会有多个下载选项。大多数用户应该选择"64-bit Git for Windows Setup"。

安装：同样是双击安装包，然后一路"Next"即可。Git的安装选项比较多，但对于我们的使用场景来说，默认配置完全够用，不需要做任何修改。

安装完成后，关闭并重新打开终端，输入git --version验证安装是否成功。

3.5 安装Claude Code

终于到了核心环节。Claude Code的安装其实只需要一条命令。

macOS / Linux用户，在终端中执行：

curl -fsSL https://claude.ai/install.sh | bash

Windows用户（使用PowerShell），执行：

irm https://claude.ai/install.ps1 | iex

命令执行后，安装脚本会自动下载并配置Claude Code。如果网络顺畅，大概一两分钟就能完成。

安装成功后，你会看到类似这样的提示：

Claude Code has been installed successfully!
Run 'claude' to get started.

3.6 Windows用户可能遇到的环境变量问题

部分Windows用户在安装完成后，可能会收到一个关于"环境变量"的提示。这是因为系统需要知道Claude Code安装在哪里，才能在任何位置调用它。

解决方法：

• 在Windows搜索框输入"环境变量"，点击"编辑系统环境变量"
• 在弹出的窗口中，点击下方的"环境变量"按钮
• 在"用户变量"区域，找到并选中"Path"，点击"编辑"
• 点击"新建"，然后输入终端提示的路径（通常是C:\Users\你的用户名\.local\bin）
• 点击"确定"保存所有更改

完成后，关闭当前的终端窗口，重新打开一个新的，然后输入：

claude --version

如果能看到版本号，说明一切正常。

3.7 首次启动Claude Code

在终端中输入claude并回车，你就进入了Claude Code的世界。

第一次启动时，会有一些初始设置选项：

主题选择：可以选择dark mode（暗色主题）或light mode（亮色主题）。用键盘上下箭头选择，按回车或空格确认。个人推荐dark mode，对眼睛友好。

账号登录：这里会提示你登录Claude账号或者配置API。先不要在这里操作，我们需要先配置好API，让Claude Code使用国产大模型来工作。按Ctrl+C退出当前界面，进入下一步的API配置。

四、配置国产大模型API：让Claude Code用上平价燃料

这一步是整个教程的关键。通过配置国产大模型的API，我们可以把Claude Code的使用成本降低到每月几十元甚至更低，同时获得相当不错的使用体验。

4.1 选择合适的大模型

目前对Claude Code兼容性较好的国产大模型主要有三个选择：

智谱GLM-4.7：智谱AI出品，在编程任务上表现优秀，有专门的Coding套餐，性价比很高。

MiniMax M2.1：MiniMax开源的模型，在多语言编程场景下表现突出，速度快、成本低。

Kimi K2：月之暗面推出的模型，思考能力强，适合复杂任务。

这几个模型各有特点，但对于大多数日常使用场景来说差别不大。我个人推荐从智谱开始，因为它的文档写得最清楚、配置最简单，而且经常有新用户优惠活动。

4.2 获取API密钥

以智谱为例，步骤如下：

• 打开智谱开放平台：https://bigmodel.cn
• 注册并登录账号
• 进入"API密钥管理"页面
• 点击"创建新的API密钥"
• 复制生成的密钥（一串长长的字符），保存到安全的地方

重要提示：API密钥只会显示一次，如果没有保存好就关闭了页面，需要重新创建一个。另外，API密钥相当于你账户的"钥匙"，不要分享给他人或者放在公开的地方。

如果你选择MiniMax，流程也类似，只是在 https://platform.minimaxi.com 进行操作。

4.3 修改配置文件

现在我们要告诉Claude Code使用国产大模型的API。这需要修改一个配置文件。

macOS / Linux用户：

在终端中执行：

open -e ~/.claude/settings.json

如果提示文件不存在，先执行这条命令创建它：

mkdir -p ~/.claude && echo "{}" > ~/.claude/settings.json && open -e ~/.claude/settings.json

Windows用户：

在PowerShell中执行：

notepad $HOME\.claude\settings.json

如果提示文件不存在，可以手动创建：先执行mkdir $HOME\.claude创建文件夹，再执行上面的notepad命令。

4.4 填写配置内容

在打开的编辑器中，把文件内容替换为以下格式（以智谱为例）：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的API密钥",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  }
}

把"你的API密钥"替换成你在上一步获取的真实密钥。

如果你使用的是MiniMax，配置稍有不同：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的API密钥",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
    "ANTHROPIC_MODEL": "MiniMax-M2.1",
    "ANTHROPIC_SMALL_FAST_MODEL": "MiniMax-M2.1",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M2.1",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "MiniMax-M2.1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-M2.1"
  }
}

保存文件（macOS按Command+S，Windows按Ctrl+S），关闭编辑器。

4.5 处理首次启动的登录问题

Windows用户可能会遇到一个小问题：即使配置好了settings.json，启动Claude Code时还是要求登录Claude账号。

解决方法是修改另一个配置文件。在PowerShell中执行：

notepad $HOME\.claude.json

在打开的文件中，添加或修改这一行：

{
  "hasCompletedOnboarding": true
}

保存并关闭。

4.6 验证配置是否成功

关闭终端，重新打开一个新的终端窗口。切换到一个你希望作为工作目录的文件夹（比如在桌面创建一个名为"ai-workspace"的文件夹），然后在终端中进入这个文件夹：

cd ~/Desktop/ai-workspace

接着输入claude启动Claude Code。

如果配置正确，你会直接进入对话界面，而不会再被要求登录。试着输入一个简单的问题，比如"你好，请介绍一下自己"，看看是否能正常回复。

如果能正常对话，恭喜你，Claude Code已经配置成功了！

五、实战Skills：让Claude Code从"通才"变"专家"

配置好基础环境后，我们来看看如何使用Skills来大幅提升Claude Code的实用性。

5.1 安装官方Skills市场

Anthropic官方维护了一个Skills仓库，里面包含了很多经过验证的高质量Skills。我们首先把这个市场添加到Claude Code中。

在Claude Code的对话界面中，执行：

/plugin add-marketplace anthropic-agent-skills https://github.com/anthropics/skills

添加成功后，可以安装官方提供的两个主要Skills包：

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

document-skills包含了处理各种文档格式的技能，包括：

• docx：Word文档的创建、编辑、格式化
• xlsx：Excel表格的处理，支持公式、图表等
• pdf：PDF的分页、合并、表单填写、文字提取
• pptx：PowerPoint演示文稿的制作

example-skills则包含了一些通用技能，比如：

• artifacts-builder：构建复杂的HTML/React界面
• mcp-server：创建MCP服务器
• webapp-testing：使用Playwright测试Web应用
• skill-creator：创建自定义Skills的指南

5.2 安装第三方Skills

除了官方Skills，社区贡献了大量实用的第三方Skills。安装方法也很简单。

比如，有一个很火的视频生成Skill叫remotion-best-practices，可以用一句话让Claude生成视频。安装命令是：

npx skills add https: