最近半个月我一直在折腾 Claude Code 的 Agent Skills这套东西给我的感觉是它终于把 AI 编程助手里那种“你问我答”的通用模式升级成了“按套路出牌”的专家模式。吴恩达最近专门用一整套课程讲了 Agent Skills 的底层逻辑核心观点我印象很深Agent 的能力上限往往不是模型本身而是它有没有针对某个领域的“专家级操作手册”。换句话说想让 Claude Code 成为某个场景下的专家最直接的办法就是给它装上一套定义良好的 Agent Skills 模块。这篇文章我不打算讲概念车我直接记录一遍自己从 0 到 1 的完整过程Claude Code 怎么装、Agent Skills 的目录规范长什么样、SKILL.md 怎么才能写得让 Claude Code “一学就会”以及我在实操中踩过的坑和排查办法。不管你是刚听说 Agent Skills 的新手还是已经在用 Claude Code 但觉得它“不够听话”的老玩家这篇应该都能给你一个可以直接抄作业的路线。1. 先想清楚Agent Skills 解决的到底是什么问题1.1 Agent 的边界取决于 Skills 的边界我先说一个很朴素的观点一个刚毕业的全能型新人和一位有十年经验的行业专家差距在哪里不在于智商而在于面对具体任务时的“反应方式”。新人遇到问题会泛泛而谈专家会立刻判断“这属于什么场景、先做什么、再做什么、输出物长什么样、有哪些坑要提前规避”。Agent Skills 做的事情正是把这套专家反应方式沉淀下来让 Claude Code 在对应场景里照着执行。在没接触 Agent Skills 之前我和 Claude Code 协作的体验是它很强但它像一位“什么都懂一点但没有固定立场”的顾问。我让它做个 PPT 大纲它能做但每次的框架都不一样有的偏营销、有的偏教学、有的偏汇报发挥很不稳定。有时候我必须在提示词里反复强调结构把流程一步步喂给它才能拿到我想要的结果非常累。而 Agent Skills 的核心价值就在这儿它把“某个领域的一套专业方法论”固化成文件让 Claude Code 在识别到对应任务时自动加载并严格执行不再每次从零“自由发挥”。用一句话概括Agent 的边界取决于 Skills 的边界。模型能力决定了下限而技能库的质量决定了上限。这一点也是我这次踩了一圈之后体会最深的地方——真正花时间的不是装环境而是如何把一个领域内“专家做事的步骤”写成 Claude Code 能读懂的指令。1.2 Claude Code 为什么适合这套玩法现在市面上的 AI 编程工具不少Codex、Cursor、GitHub Copilot 各有各的拥趸。为什么我一直拿 Claude Code 来做 Agent Skills 的试验田因为我实际对比下来Claude Code 天生是干 Agent 活的料。第一它是终端形态的 CLI 工具可以直接访问本地文件系统、执行 shell 命令、读取项目目录这意味着技能里可以包含“读文件→执行命令→修改代码→运行测试”这类完整闭环的操作流而不只是在聊天框里生成一段代码。第二Claude Code 对上下文的管理很自然同一个会话里它能记住技能引用关系不会用着用着就“忘了”。第三它的 Skills 目录机制非常简单你往~/.claude/skills里放一个文件夹里面写一份SKILL.mdClaude Code 就能在合适的时候自动加载。我自己的体验是Claude Code 经常被拿来和 Codex 对比但两者思路不太一样。Codex 更偏向在独立会话里完成任务Claude Code 则更像一个常驻的“结对工程师”适合把一整套项目操作流程交给他。而 Agent Skills 这个概念恰好能把 Claude Code 的工程化能力再推上一层——你不仅能用它写代码还能把某个规范、某套流程、某类输出标准都变成“可重复调用”的模块。1.3 技能、插件、MCP 到底有什么不一样聊 Agent Skills 的时候很多人会把它和 MCP、插件混为一谈。我自己一开始也懵了一下后来想清楚了一个简单的划分方式它们解决的是不同层级的问题。概念本质解决什么问题典型场景Agent Skills团队知识与操作流程的文档化让 Agent “知道怎么做”按固定流程生成 PPT 大纲、按规范处理文档、按标准审查代码MCPModel Context Protocol让 Agent 连接外部工具与数据源的协议让 Agent “能做什么”读取数据库、调用内部 API、操作浏览器插件/扩展宿主工具提供的扩展点改变交互方式或补足 UI 能力IDE 插件、终端主题、自动化脚本我这样理解的MCP 决定的是能力边界——让 Agent 能访问数据库能调用外部服务Agent Skills 决定的是行为边界——告诉 Agent 面对具体任务时要按照哪个专家流程来做。打个比方MCP 是给医生配上 CT 机和检验科权限Agent Skills 则是给医生一本科室标准诊疗手册什么症状走什么检查、什么结果用什么方案、病历怎么写、结论怎么给。做技术选型的时候我的习惯是如果任务核心是“和外部系统交互”优先考虑 MCP如果核心是“把既定流程执行到位”优先写一个 Skill如果只是想在编辑器里换个交互方式才考虑插件。三者不冲突可以配合使用但不要在需要 Skill 的场景硬塞一个 MCP那样反而复杂化了。2. 装好基础环境Claude Code 的安装与初始配置2.1 官方推荐的安装方式与前置环境先说安装。Claude Code 作为一个 npm 包发布最直接的安装方式是通过 Node.js 的 npm。前置条件只有一条Node.js 版本不要太老官方建议 18 以上。你可以在终端里先确认一下node -v npm -v如果 Node.js 没有装先去官网装一个 LTS 版本再继续往下走。装好之后执行npm install -g anthropic-ai/claude-code国内网络环境下npm 默认源下载速度通常不太理想甚至会超时。这里强烈建议先把 npm 镜像源配好再执行安装可以省掉不少等待时间npm config set registry https://registry.npmmirror.com npm install -g anthropic-ai/claude-code如果你不想装 Node.js官方也提供了 curl 安装脚本的方式curl -fsSL https://claude.ai/install.sh | bash安装完成之后跑一下claude --version能输出版本号就说明装好了。然后直接在终端输入claude回车第一次运行会引导你完成登录认证一般是跳转浏览器授权之后就能进入交互式对话界面。2.2 安装后必做的三项初始设置装好只是第一步。我建议你进入claude之后先花两分钟做三件事能避免后面很多麻烦。第一确认配置文件目录结构。Claude Code 的全局配置会生成放在用户目录下常见的是~/.claude.json、~/.claude/目录以及我们后面要重点用的~/.claude/skills/。你可以退出对话后执行ls -la ~/.claude/如果还没有skills文件夹手动建一个就行Claude Code 不会自动生成但它会自动识别mkdir -p ~/.claude/skills第二把终端主题和通知方式调整成自己舒服的状态。在 Claude Code 对话界面里可以直接用斜杠命令配置比如我习惯把主题设置成深色通知推送到终端而不是弹系统通知claude config set -g theme dark claude config set -g preferredNotifChannel terminal第三确认一下你登录使用的账号类型。Claude Code 支持订阅登录和 API Key 两种方式二者的额度模型不一样。如果你走的是 API建议把 API Key 放到环境变量里不要在对话中明文输入避免不小心写进日志。细节后面“高频问题”部分我再展开。2.3 VS Code 集成与本地模型接入Claude Code 原生是终端工具但其实和 VS Code 配合使用非常顺手。最简单的方式就是在 VS Code 里直接打开内置终端然后运行claude这样你写代码的时候Claude Code 就在同一个工作区里能直接感知当前项目的文件结构。热词里经常出现“vscode配置claude code”其实不需要额外装什么插件用内置终端就够了。如果你的编辑器里有多个终端面板我建议把 Claude Code 单独放到一个命名终端里这样项目日志、git 命令和 Claude Code 的输出不会混在一起。我实际操作中会把claude终端固定在最右侧左边写代码右边和 AI 助手协作体验非常接近“结对编程”。再来说本地模型接入。很多人想省钱或者希望数据不出本机会选择用 Ollama 跑本地模型然后让 Claude Code 指向本地 API 端点。配合 cc-switch一个快速切换 Claude Code API 配置的小工具和 Ollama可以实现“官方模型和本地模型之间一键切换”。配置方式大体是在 Ollama 启动对应模型给 Claude Code 设置环境变量让它的 API base 指向http://localhost:11434之类的本地地址。不过我要给个实在的建议本地模型跑 Claude Code 在规则型任务上表现尚可但复杂指令的理解和多步推理能力明显弱于官方模型尤其是涉及 Agent Skills 这种多文件流程的场景新手很容易被各种兼容性问题劝退。建议先把官方模型下的 Skills 流程跑通再回头折腾本地化这样你能分清问题是模型能力限制还是环境配置问题。3. 从 0 创建第一个 Agent Skill完整实操3.1 Skill 的目录结构与 SKILL.md 规范环境准备好了接下来就是重头戏创建第一个 Agent Skill。Claude Code 的 Agent Skills 采用了一套严格但不复杂的文件结构核心就是一个 SKILL.md 文件配合可选的辅助文件。一个标准的技能目录长这样~/.claude/skills/ └── ppt-outline-expert/ ├── SKILL.md └── examples/ └── demo-outline.mdSKILL.md是灵魂文件它决定了 Claude Code 什么时候调用这个技能、调用后按什么流程做事。它的格式是 YAML frontmatter 加 Markdown 正文frontmatter 里必填name和description正文则是详细的执行指令。--- name: ppt-outline-expert description: 专业 PPT 大纲策划。当用户提到做 PPT、做演示文稿、需要页面框架、需要大纲规划时使用。用户给出主题后本技能输出结构完整、逻辑清晰、可直接转化为幻灯片的页面级大纲。 ---frontmatter 里有两个地方特别关键。第一个是name它是技能的全局唯一标识相当于 ID命名要短、要准确、最好一眼能看出是干嘛的。第二个是description它是模型判断是否启用这个技能的“说明书”决定了模型在什么场景下会主动加载它。description 写得太泛模型会在不该用的时候强行套用写得太窄模型又会漏掉它。正文部分就是你要交付给模型的“专家手册”。我写正文时参考的是官方文档推荐的“渐进式披露”原则主文件只写主干流程和关键规则细节放到子文件里按需引用避免上下文被无关信息占满。3.2 写一个“PPT 大纲策划专家”技能光说概念容易飘我直接放一个我实际用的技能模板。下面这个是我日常工作中最常用的一个叫ppt-outline-expert作用是让 Claude Code 在用户提出做 PPT 需求时按专家级流程输出大纲。先建目录和文件mkdir -p ~/.claude/skills/ppt-outline-expert/examples touch ~/.claude/skills/ppt-outline-expert/SKILL.mdSKILL.md 的完整内容大概是这样的--- name: ppt-outline-expert description: 专业 PPT 大纲策划。当用户提到做 PPT、做演示文稿、需要页面框架、需要大纲规划、需要准备一份汇报材料的结构时使用。用户给出主题后本技能输出结构完整、逻辑清晰、可直接转化为幻灯片的页面级大纲。 --- # PPT 大纲策划专家 你是拥有十年咨询与演示设计经验的策略顾问。你的任务是帮用户把模糊的主题转化为结构化、可执行的 PPT 大纲。 ## 第一步收集必要信息 在输出大纲之前先检查用户是否提供了以下信息。缺失时主动询问但不要一次问太多优先问最影响结构的两项 1. 受众给谁讲例如高管、客户、同学、投资人。默认按“向上级汇报”处理。 2. 时长或页数讲多久对应多少页。默认按 15 分钟、10~12 页处理。 3. 目的说服、汇报、教学还是启动讨论默认按“汇报进展并争取资源”处理。 ## 第二步确定核心信息与叙事线 用不超过三句话写下这页 PPT 的核心信息。叙事线优先选择以下结构之一 - 问题 → 原因 → 方案 → 价值 - 现状 → 目标 → 差距 → 路径 - 案例 → 方法 → 应用 → 展望 ## 第三步生成页面级大纲 每一页用下面的格式逐页输出 - 页面标题一句话说清本页主旨 - 页面要点3 到 5 个关键点每条不超过 15 个字 - 演讲提示本页讲解时的过渡句或重点强调内容 - 可视化建议建议用图表、示意图还是纯文字排版 封面页和结尾页按以下固定结构输出封面页必须包含主题、汇报人占位、日期占位结尾页必须包含行动建议或待确认事项。 ## 第四步输出格式 完整输出第一版后在文末附上一段“用户需要调整时可提供的信息”清单引导用户做增量修改而不是推倒重来。写完之后我建议再补一个示例文件放到examples/demo-outline.md。示例的价值在于给模型一个“标准答案”尤其是输出格式层面模型在模仿示例时通常比读一百条规则更靠谱。示例里就是一份完整的大纲案例主题可以是“公司季度产品复盘”之类的通用场景。这个技能的逻辑很简单信息收集、叙事线选择、页面展开、格式规范。训练模型时我们会发现越是流程明确的技能Claude Code 执行得越稳定反之如果连你自己都不知道专家是怎么干的写出来的 Skill 也是一团浆糊。3.3 让 Claude Code 每次自动加载技能的两种方式技能文件写好之后Claude Code 怎么知道什么时候用它这里有两种加载机制我分别试过简单分享下体会。第一种是“用户主动触发”也是最稳的方式。在对话里直接提到技能名比如“用 ppt-outline-expert 帮我规划一份产品发布会的 PPT”。Claude Code 读到技能名后会去 skills 目录里加载对应文件。这种方式适合你已经明确知道要用哪个技能的场景可控性最强。第二种是“描述自动匹配”是更接近 Agent 理想状态的用法。你正常说“帮我做个 PPT”Claude Code 会根据所有技能里的description文本判断当前意图和哪个技能匹配然后自动加载。这个方式很爽但对 description 的写作质量要求很高写得太模糊就容易匹配错。我的经验是description 里一定要包含用户最常说的口语化表达比如“做个PPT”“写个方案”“弄个汇报”这样匹配命中率会大幅提升。除了全局技能目录Claude Code 还支持项目级技能。你可以在项目根目录下建一个.claude/skills/文件夹里面的技能只对这个项目生效。我在不同项目里就是这么区别对待的行政类项目放文档模板技能开发类项目放代码审查技能互不干扰。4. 实操心得让技能真正“好用”的几个原则4.1 卡片信息要克制触发词要精准先说 memory 层面的经验。很多人第一次写 Skill会不自觉地想把所有东西都塞进 description 里觉得描述写得越详细模型越懂。这是个误区。description 的本质是“给模型的搜索引擎索引”不是“培训文档”。它只需要让模型知道什么时候用这个技能、用了之后能得到什么。我一般控制在三到五句话包含触发场景、前置条件、输出物类型就够了。触发词的选择我建议从真实用户的表达里提取。比如你观察自己和同事平时说“做 PPT”而不是“生成演示文稿”那就把“做 PPT”放进去。如果团队内部习惯说“出个片子”“整一版方案”也要一并写进去。这样模型匹配的准确率会直接上一个台阶。我在一个技能里塞过 20 个触发词实测下来精度反而下降后来精简到 6 个核心表达效果明显好了。4.2 “渐进式披露”比长说明书管用这一点是我最想强调的。初学 Agent Skills 的时候我写过一个异常完整的技能文件把某个工作流的所有细节、所有例外、所有高级技巧全部写进去总共两千多字。结果 Claude Code 执行时经常“读不完”或者“抓不住重点”输出反而更差。后来我看了官方文档才明白Agent Skills 采用的是渐进式披露机制模型先读到的是 SKILL.md 概括性的主流程只有当它发现某个环节需要更细的指导时才会去加载引用的子文件。这和人类专家的工作方式是一样的老医生带学生不会先让背完整本内科学而是先讲首诊流程遇到具体症状再翻诊断细则。所以现在我的写法是SKILL.md 只放主流程和核心规则涉及具体案例、模板、规范细节的放到examples/或者references/目录下在正文中用相对路径引用。这样既保留了技能的指导性又不会灌爆上下文。4.3 示例给足Claude Code 才能输出稳定给 AI 写技能本质上是在和“模糊性”做对抗。规则写得再细模型也可能在边界场景上自由发挥而示例可以把这种自由发挥的空间压缩到最小。我强烈建议每个技能至少配一个完整示例并且示例要覆盖到“标准输出格式”。比如我在ppt-outline-expert的示例文件里就完整展示了从封面页到结尾页的逐页大纲模型照着示例模仿出来的结果在格式层面几乎不会跑偏。另外有条件的话加一两个“反例”也很有用。你可以在技能正文里明确写“不要做成什么样”。比如“不要在封面页直接放三行小字封面应使用大标题加一句副标题。”反例的作用是给模型划定禁区告诉它哪些做法是外行表现。我实测下来正反例结合的效果比只给正面示例好很多。4.4 技能命名与目录规划经验技能多了之后命名和目录规划就成了大问题。我的命名习惯是业务对象 场景 类型。比如“ppt-outline-expert、code-review-engineer”、“doc-standard-checker”。一眼能看出用途而且在 description 里引用时也不会搞混。目录层面建议技能文件夹的名字和 SKILL.md 里的name字段保持一致。Claude Code 在加载时主要靠 name 字段做标识如果文件夹名和 name 不一致排查问题时容易懵。我一开始吃过这个亏文件夹叫ppt-v1内部 name 写的是presentation-master结果 Claude Code 报技能找不到排查了很久才发现是对不上。技能积累到一定量之后我建议把整个~/.claude/skills/目录纳入 Git 管理。这样你的专家模块就成了一个可版本化的资产换新电脑之后一条git clone就能把所有技能同步过来还能回溯每个技能的迭代历史。我现在已经把这套技能库当成自己最重要的“数字资产”之一在维护。5. 高频问题与排查实录5.1 安装在 PowerShell 上报错的排查Windows 上用 PowerShell 装 Claude Code最常见的报错是执行策略限制比如出现“无法加载文件因为在此系统上禁止运行脚本”这类提示。解决办法是给当前用户开放远程脚本执行权限Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser执行后会弹确认提示输入 Y 回车即可。如果这一步也报错或提示没有管理员权限可以换到“以管理员身份运行”的 PowerShell 里操作。另一个高发问题是 npm 安装卡在下载步骤或者报网络错误。这种基本是 npm 源访问国外服务器太慢导致换镜像源就能解决我在前面安装部分已经写了命令。还有种情况是安装完成后claude命令找不到一般是 npm 全局包的目录没有加入 PATH。可以先执行npm bin -g查看全局包路径再把对应路径加到系统环境变量里。5.2 界面乱码与控制台编码问题Windows 终端下打开 Claude Code 出现中文乱码这个问题很常见但通常不是 Claude Code 本身的问题而是控制台的代码页设置不对导致 UTF-8 输出显示成了乱码。最直接的解决方式是在 PowerShell 里把代码页切到 UTF-8chcp 65001如果你觉得每次手动切太麻烦还可以把 Windows Terminal 设为终端并把默认代码页和字体调好。我把 Windows Terminal 的配置文件里默认字体设置为支持中文的字体后乱码基本绝迹了。另外如果你的系统区域设置里开启了“使用 Unicode UTF-8 提供全球语言支持”记得重启系统后再测它对所有命令行工具的编码兼容性都有帮助。值得一提的是如果你在 VS Code 内置终端里跑 claude还需要确认 VS Code 终端的程序是 PowerShell 还是 Cmd二者在编码处理上略有差异。我用下来 PowerShell Windows Terminal 的组合最稳。5.3 提示模型版本无法识别的处理有次我在配置里把模型指定成第三方模型启动 Claude Code 后直接报错提示类似glm-5.2 is not a model this version of claude code recognizes。这个报错的意思是当前 Claude Code 版本不认识你配置里写的模型名导致自动补全和部分功能不可用。排查思路分三步。第一步检查 Claude Code 版本是不是最新版本太旧可能不支持某些新模型claude --version npm update -g anthropic-ai/claude-code第二步检查 API 配置里的模型名是否拼写正确。这里容易踩坑的是第三方服务商可能在 API 入口上做了模型名映射官方叫 A服务商叫 B你得按服务商提供的名字来填。第三步如果模型名没问题但版本太旧仍然是报错可以在 Claude Code 里输入/model查看当前可用的模型列表手动选一个避免自动识别出错。我实际踩过这个坑之后的感受是第三方模型接入 Claude Code 虽然可行但始终存在兼容性摩擦小版本更新都可能让模型名失效。如果你不是有充分的成本或隐私诉求主力场景还是用官方支持的模型最省心。5.4 关于每周限额提示与 token 消耗的思考很多人在使用过程中会遇到类似“your limits are temporarily boosted. your weekly claude code limit is 50% hi”的提示。第一次看到时我也愣了一下后来研究明白这是官方对账号额度的管理通知意思是你的每周用量达到了某个阈值或者当前配额有临时调整并不是报错。它通常在订阅账号的用量管理中比较常见作为提示出现在会话中。遇到这种提示时我的处理方式是把批量任务拆成小段执行不要在同一个会话里堆积太多长文本输入。另外把重复性高、模板化的工作用 Agent Skills 固化能让模型减少对上下文背景的反复读取从根上节省 token。比如你每周都要生成周报与其每次都贴一遍周报要求不如写一个weekly-report-expert技能让模型自动按模板输出。关于“Claude Code 如何用省 token”我总结了一句话能写进技能里的就别写进对话里。技能文件相当于模型的“参考文献”会话只是“临时工作记忆”。让固定知识沉淀在技能里会话就能保持轻盈token 消耗自然降下来。6. 写在最后这套玩法还能怎么延伸折腾了一整圈 Agent Skills我最大的感受是它最大的难度不在技术而在“结构化表达”。你需要把自己脑子里那些模糊的、凭经验的做事方法一步步拆成机器能理解的流程。这个过程本身就很值——它逼着我把很多藏在大脑里的工作套路变成了可见、可复用、可迭代的文档。如果你也想动手我建议从一个小技能开始不要一上来就搞“全能专家”。选一个自己每天都在做的重复性任务比如写周报、做会议纪要、整理代码提交说明把它写成一个简单的 SKILL.md跑通再说。等流程顺了再逐步加复杂规则和示例文件。另外我最近在尝试的一个方向是把同一套技能库同时用于不同项目然后根据反馈不断迭代描述和流程。比如ppt-outline-expert在我这里已经迭代了四个版本每一版都是因为在真实使用中发现触发不准、格式不符或流程缺失才更新的。这个持续演进的过程才是 Agent Skills 真正的价值所在——它不是一个静态的配置而是你个人或团队知识资产的滚动积累。