Agent Skills 和 Claude Skills 是最近 AI Agent 方向里讨论热度上升很快的一类能力。简单说它解决的不是“让模型背更多知识”而是“把高频、重复、需要特定操作流程的任务固化成 Agent 可以直接调用的技能包”。这篇文章不从概念堆砌开始直接按“先搞懂它是什么再上手安装最后自己造一个”的顺序走目标是让看完的人能独立完成从使用 Claude Code 的现成 Skills 到创建自定义 Agent Skill 的完整闭环。这次内容不止讲原理会覆盖几个关键问题Agent 和 Skills 到底是什么关系、Claude Skills 安装在哪里、SKILL.md 怎么写、如何把一个技能接入真实工作流、批量任务怎么处理、以及最容易被卡住的排错点。如果你正在做 Agent 应用、研究 Claude Code 或准备把 AI 接入论文写作、代码审查、数据处理这类具体任务这篇建议直接收藏。1. 核心能力速览能力项说明项目类型AI Agent 技能机制 / 提示工程实践核心概念Agent Skills、Claude Skills、技能包、SKILL.md主要功能让 Agent 按固定流程完成代码审查、写作辅助、数据处理、结构化输出等任务运行环境同一套技能机制可覆盖 Claude Code 等 Agent 场景是否需要 GPU不需要云端模型服务即可安装方式现成技能包复制到 Skills 目录自定义技能按模板创建扩展能力支持接口集成、批量任务、按场景拆分的多技能管理适用人群使用 Claude Code 的开发者、AI 应用研究者、需要 Agent 自动化工作流的效率工具使用者使用边界输出质量依赖模型版本、任务复杂度敏感数据需注意隐私合规2. 理解 Agent SkillsAgent 与 Skills 的区别先把最容易混淆的概念理清楚。Agent智能体是一个能感知环境、做出决策、调用工具并执行多步任务的系统。它可以理解用户意图规划步骤然后一步步调用工具完成目标。真正让 Agent 区别于普通聊天机器人的是“自主执行”这个能力。Skills技能是什么它是一个可复用的能力模块通常由一组指令、示例脚本、参考文档和元数据组成。它不负责规划负责的是“在正确的时候提供正确的方法”。用一句话概括Agent 是大脑和身体Skills 是身体里的专项技能包。Agent 负责判断什么时候该用哪个技能Skills 负责告诉 Agent 具体怎么做。再看一个常见问题AI Skills 和 Agent 有什么区别Agent 是完整的执行实体有目标、有计划、有工具调用能力。Skill 是 Agent 的能力组件可以被加载、被卸载、被复用。如果把 Agent 类比成一个员工Skills 就是这个员工的岗位技能认证。员工本人不会因为多拿一个认证就换一个人但他能处理的事情范围会明显扩大。另一个容易混淆的概念是 MCPModel Context Protocol。MCP 解决的是 Agent 与外部工具之间的通信协议问题偏向“连接外部资源”Skills 解决的是“任务操作方法”问题偏向“告诉 Agent 怎么一步步做”。实际项目里两者可以配合使用MCP 负责访问外部系统Skill 负责把访问到的数据按固定流程加工成目标结果。3. Agent Skills 的使用场景与合规边界从搜索热词里可以看到几个典型场景好用的 Claude Code Skills 安装、Agent Skills 赋能人文社科混合研究方法论文写作、AI Agent Skills 推荐、AI Skills 和 Agent 的区别。这些场景基本覆盖了 Agent Skills 的主战场。3.1 适合的场景代码相关的技能是最成熟的。你可以给 Claude Code 安装一个“代码审查技能”让它按团队规范检查 PR也可以装一个“单元测试生成技能”让它按指定框架生成测试用例。文档处理场景也很实用。把“读取 PDF - 提取关键信息 - 输出结构化 Markdown”这个流程固化成 Skill之后所有同类文档处理任务都可以直接触发不需要每次重复写提示词。研究写作场景。部分热词提到“Agent Skills 赋能人文社科混合研究方法论文写作”本质上是用 Skill 把“文献检索 - 方法选择 - 数据整理 - 论文结构生成 - 引用规范检查”这类长流程标准化。这里必须强调AI 辅助写作不等于代写使用时应遵守学术诚信规范论文的论点、实验和最终审核必须由研究者本人负责。批量任务场景。Agent Skills 配合 Claude Code 的会话能力可以对一批文件执行同样的处理流程例如批量整理日记、批量生成数据报表说明、批量检查文档格式。3.2 不适合的场景需要严格实时数据或精确计算的任务Skill 本身不保证结果绝对正确需要人工复核。涉及核心业务决策、法律文书、医疗建议的场景不能把 Skill 的输出当最终结论。需要在本地离线跑的任务由于依赖云端模型服务离线场景无法使用。3.3 合规边界使用第三方现成 Skills 时先看技能包的来源和内容避免把包含敏感操作指令的技能直接放进生产环境。涉及公司内部代码、用户隐私数据、未公开论文材料时要考虑数据是否会发送到第三方 API必要时先脱敏再处理。涉及肖像、声音、版权材料的内容必须确认授权。任何自动化操作都要保证在授权范围内执行。4. Claude Code 环境准备Claude Code 是运行 Agent Skills 最直接的入口。它的本质是命令行 AI 编程助手可以在终端里通过对话方式让 AI 读代码、改代码、跑命令。Skills 功能能让它在特定任务上表现得更稳定。4.1 环境依赖检查项要求操作系统Windows / macOS / Linux 均可Windows 建议提前装好 Git Bash 或 PowerShell 环境Node.js建议安装当前 LTS 版本Claude Code 通过 npm 分发npm 访问需要能正常访问 npm 仓库Claude 账号需要能访问 Claude 服务的账号或用 API Key 方式网络能正常访问 Claude API 域名4.2 安装 Claude Code安装命令以官方 npm 包为准通常是这样npm install -g anthropic-ai/claude-code安装完成后执行版本检查claude --version如果命令不存在检查 npm 全局 bin 目录是否加入了系统 PATH。Windows 下有时需要重新打开终端才会生效。4.3 登录与鉴权Claude Code 支持两种常见方式一种是订阅账号登录模式安装后直接执行claude按提示完成浏览器授权适合个人日常使用。另一种是通过 API Key 模式把 Anthropic API Key 设置到环境变量里export ANTHROPIC_API_KEYsk-ant-xxxxWindows PowerShell 下写法$env:ANTHROPIC_API_KEYsk-ant-xxxx注意 API Key 属于敏感信息不要写进公开脚本或提交到代码仓库。建议用系统环境变量或密钥管理工具维护。5. Claude Skills 安装路径与加载原理Claude Code 的 Skills 不是一个需要“运行”的程序它是一组需要被 Agent 读取的文件。安装的本质是把技能包放到指定目录让 Claude Code 启动时能扫描到。5.1 Skills 目录结构一个典型的 Skills 目录结构如下~/.claude/ └── skills/ └── code-review/ ├── SKILL.md └── reference/ └── review-checklist.mdSKILL.md 是技能的核心文件写清楚技能名称、触发条件和操作步骤Agent 会根据这个文件决定是否调用技能。reference 目录用来放参考材料。5.2 安装现成 Skills从仓库或社区下载技能包后复制到技能目录即可。例如要安装一个名为 code-review 的技能# 创建技能目录 mkdir -p ~/.claude/skills/code-review # 复制技能文件路径按实际下载位置调整 cp -r ./downloaded-skill/* ~/.claude/skills/code-review/复制完成后重启 Claude Code或者在会话里让 Agent 重新扫描技能目录。5.3 验证 Skill 是否被加载在 Claude Code 会话中输入与技能相关的任务描述看模型是否主动调用该技能。比如装好 code-review 技能后对 AI 说请审查当前项目的 src/main.py如果输出里出现类似“使用 code-review 技能”“按审查清单逐项检查”的内容说明技能已生效。5.4 SKILL.md 基本格式SKILL.md 通常包含 frontmatter 元数据和正文两部分。元数据里声明技能名称与描述正文给出详细操作指令。一个标准模板如下--- name: code-review description: 按团队规范审查代码检查逻辑缺陷、安全问题和风格一致性。 --- # Code Review Skill 当用户要求审查代码时按以下步骤执行 1. 读取目标文件。 2. 检查函数边界与错误处理。 3. 对照 reference/review-checklist.md 逐项检查。 4. 输出问题清单标注严重级别。这里的设计逻辑是描述要让模型能判断“什么时候用这个技能”正文要让模型能判断“用了之后第一步干什么、第二步干什么”。6 创建一个自定义 Agent Skill从会用到会造“从会用到会造”是这套教程的核心目标。使用别人的技能只是第一步真正提升效率的关键是根据自己的任务习惯创建技能。下面用一个例子说明如何从零创建一个技能。场景是“把一段非结构化的会议记录整理成结构化报告”。6.1 设计任务流程先想清楚这个任务的标准操作流程读取原始会议记录文本。提取参会人员、时间、议题、决议。按固定模板输出 Markdown 报告。标出待办事项和负责人。6.2 创建技能目录和文件mkdir -p ~/.claude/skills/meeting-notes6.3 编写 SKILL.md--- name: meeting-notes description: 将非结构化会议记录整理为结构化 Markdown 报告提取议题、决议和待办事项。 --- # Meeting Notes Skill 当用户提供会议记录文本时按以下模板整理。 ## 输出模板 ### 会议基本信息 - 会议时间 - 参会人员 ### 议题与讨论 - 议题 1 - 讨论要点 - 结论 ### 决议 - 决议 1 ### 待办事项 | 事项 | 负责人 | 截止时间 | | --- | --- | --- | ## 处理规则 - 原文内容不足的字段留空不编造。 - 待办事项必须对应明确负责人。6.4 测试自定义技能在 Claude Code 中输入请用 meeting-notes 技能整理以下会议记录 “3月2日会议参加人有张伟、李娜。讨论了新功能上线计划决定下周四发布张伟负责前端李娜负责后端。数据库迁移问题下次再谈。”预期输出一份带有会议信息、议题结论、待办事项表格的 Markdown 报告。如果输出没有触发模板检查技能目录路径是否正确、描述是否清晰。6.5 技能设计要点技能的描述比正文重要。模型通过描述决定是否调用技能描述写得模糊技能就会经常被漏掉描述写得太泛又会在不合适的场景被误调用。正文里的步骤必须可执行尽量减少“根据情况灵活处理”这类模糊表述改用明确动作。7. Agent Skills 实战场景详细演示7.1 代码审查技能实战先给 Claude Code 装一个代码审查 Skill然后准备一个简单 Python 文件def calculate_avg(nums): total 0 for n in nums: total n return total / len(nums)在 Claude Code 中发起审查请求预期输出包含空列表会导致除零异常、建议添加防御性判断、命名规范是否一致、是否需要类型注解。这类技能适合接入到 CI 工作流中做“提交前检查”。做法是把 Claude Code 的命令封装成脚本在 git commit 之前自动对变更文件执行代码审查。7.2 文档批量处理技能实战批量任务在 Agent Skills 场景里很常见。可以把“读取文件 - 提取核心观点 - 生成摘要卡片”固化成 Skill然后对多个文件循环执行。一个通用做法是定时任务加技能触发# 批量处理 inputs 目录下的所有文稿 for file in ./inputs/*.md; do echo Process file: $file claude -p 请调用 summarize-skill 处理文件 $file输出摘要到 outputs/ 目录 done-p表示非交互式一次性执行。不同版本的 Claude Code 参数可能不同使用前查看本机帮助claude --help批量任务要注意文件数量较多时会依次调用模型接口耗时和费用都会上升建议分批处理并给每个文件加独立的输出日志。7.3 人文社科论文写作辅助技能实战论文写作辅助是热词里提到较多的方向。典型做法是创建一个 mixed-methods-research Skill把混合研究方法论文的写作流程固化为研究问题拆解、文献综述结构、定性数据组织、定量数据组织、方法交叉分析、结论与局限。这类技能在建立时尤其要注意学术伦理。它可以帮助整理思路、检查结构、生成初稿框架但数据真实性、实验设计、最终结论仍由研究者掌握。提交论文前必须完成独立验证不能直接使用未复核的 AI 生成文本。8. 接口集成与批量任务设计Claude Skills 不只是终端里的玩具。如果希望把技能能力接入自己的业务系统可以通过 API 或调用封装好的脚本实现。8.1 通过 API 封装技能调用Skill 本身不直接暴露 API它起作用的方式是“把特定任务的提示词流程固定下来”。因此封装 API 时需要把 Skill 的逻辑放进请求上下文。用 Python 调用的思路如下实际请求地址、请求头、参数名须按你所用的模型服务文档调整import requests API_URL https://api.example.com/v1/messages API_KEY your-api-key headers { x-api-key: API_KEY, anthropic-version: 2023-06-01, content-type: application/json, } payload { model: claude-model-name, max_tokens: 1024, messages: [ { role: user, content: 请使用 code-review 技能审查以下代码\npython\ndef add(a, b):\n return a b\n } ] } response requests.post(API_URL, headersheaders, jsonpayload, timeout120) print(response.json())这个示例只用于说明思路。真实项目中应使用官方 SDK并优先调用你所用服务的官方接口文档。8.2 批量任务队列设计多个 Skill 场景下建议按以下结构组织批量任务inputs/ # 原始输入文件 file-01.md file-02.md outputs/ # 处理结果 file-01.md.summary.md logs/ # 任务日志 batch-20260301.log skills/ # 自定义技能 code-review/ meeting-notes/批量脚本要加两层保护一是处理前检查文件格式二是每个文件单独捕获异常避免一个失败导致整个队列中断。8.3 失败重试建议调用模型服务时可能遇到超时、限流、结果截断。建议采用以下策略每个任务记录状态成功写入 outputs失败写入 failed 列表。对超时任务做指数退避重试例如第 1 次等待 5 秒第 2 次等待 20 秒。设置单任务最大重试次数防止死循环。输出结果如被截断可设置更大的 max_tokens或要求模型分段输出。9. 资源占用与性能观察Agent Skills 的运行主要在模型侧本地几乎不占显存也不需要 GPU。它占用的是“模型推理的 token 消耗”和“执行动作产生的工具调用时间”。9.1 如何观察成本加入技能后每次任务会把 SKILL.md 的内容作为上下文发送给模型相当于增加了一部分输入 token。技能包越大、参考文档越详细输入 token 越高。设计技能时要注意SKILL.md 正文尽量精简只保留必要步骤。大段参考资料放到 reference 目录仅在需要时按需读取。避免把整个手册塞进 SKILL.md。9.2 影响响应速度的因素Skill 描述是否精确描述模糊时模型可能多次判断是否调用。任务复杂度步骤越多模型调用工具的轮数越多。参考文档大小Agent 读取大文件会显著增加耗时。网络延迟模型服务在远端时接口延迟直接影响体验。9.3 降低开销的方法一个技能只解决一个问题。把多步骤任务拆成多个技能按需调用而不是设计一个巨型技能。对高频简单任务可以把输出格式直接写死在技能里减少模型自由发挥空间。10. 常见问题与排查方法问题现象可能原因排查方式解决方案claude 命令找不到npm 全局目录不在 PATH执行npm config get prefix查看全局目录将目录加入 PATH 后重开终端登录时无法授权网络不通或账号异常检查账号状态和网络重试授权流程必要时清除登录缓存API Key 无效环境变量未生效在当前终端执行echo $ANTHROPIC_API_KEY重新设置环境变量并重启终端Skill 被调用但没按模板输出SKILL.md 描述不清晰查看模型输出是否提到技能名重写 description明确触发条件Skill 根本没有被加载目录路径错误检查 ~/.claude/skills 下的目录名修正技能目录路径和 SKILL.md 文件名批量任务某个文件失败文件格式异常或内容过长查看日志文件中的错误信息单独处理失败文件调整分批逻辑API 调用超时网络波动或任务过重观察具体超时环节增加超时时间拆小任务加退避重试输出结果被截断max_tokens 设置过小观察输出是否在句中断开调大 max_tokens或让模型分段输出模型频繁误调用技能description 写得太泛检查每次调用时模型判断依据缩小 description 中的触发条件范围更新技能后不生效Agent 缓存旧文件重启 Claude Code清空会话后重新加载其中最容易踩的坑有两个。第一个是 SKILL.md 的文件名必须完全一致大小写也不能错Agent 按固定名称扫描。第二个是 description 写得像广告而不是触发条件导致模型在错误场景频繁调用或完全不调用。11. 最佳实践与使用建议11.1 第一优先验证单技能最小闭环不要一上来就设计复杂技能。先装一个现成技能跑通一个任务确认它能被识别和调用。再创建一个最简单模板技能确认自己创建的也能被调用。最小闭环跑通后再逐步增加复杂度。11.2 保持技能可维护技能是代码需要版本管理。把所有技能放进 Git 仓库SKILL.md 变更要有提交记录。技能描述和正文都使用英文或统一语言避免模型理解偏差。每个技能配一个 example.md 示例说明输入和预期输出。11.3 控制上下文长度技能越多Agent 启动时的扫描开销和上下文占用越高。不需要每次会话使用的技能就不要常驻可以按项目拆分技能目录或者用临时目录加载特定技能。11.4 安全与授权不把包含敏感信息的文件直接交给第三方模型处理先脱敏。不加载来源不明的 Skill尤其是不明脚本防止恶意指令注入。批量任务和自动化操作仅在授权范围内执行。涉及人脸、声音、版权素材时必须确认授权。论文写作场景中AI 只做辅助学术诚信由研究者负责。12. 总结与下一步Agent Skills 是一个比大多数人想象的更轻量的能力提升方式。它不改变模型本身而是通过“给 Agent 一份更清晰的操作手册”来提升结果稳定性。安装一个 Skill 本质上是把一段可复用的提示词和流程打包放进 Agent 能读取的目录。这套体系最值得先验证的是一个能解决你高频重复任务的技能是否能明显减少你每次重复描述需求的时间。如果答案是能说明你的场景适合继续扩展。通过这套流程你可以先从社区找 2 到 3 个现成 Skills 装上实际跑几天感受触发效果。然后挑一个自己每天都在做的重复任务按 SKILL.md 模板做一个简化版技能跑通后再逐步完善。容易被忽略的一点是Skills 的价值不取决于数量而取决于“在正确的时候被正确调用”。把 skill 目录梳理清楚保持描述简洁比收藏很多技能更管用。下一阶段可以继续研究如何把同一套技能接入更复杂的 Agent 编排流程或者把它封装成内部工具服务配合 MCP 连接更多外部系统。 Agent Skills 完全指南：从安装 Claude Skills 到创建自定义技能包
Agent Skills 和 Claude Skills 是最近 AI Agent 方向里讨论热度上升很快的一类能力。简单说它解决的不是“让模型背更多知识”而是“把高频、重复、需要特定操作流程的任务固化成 Agent 可以直接调用的技能包”。这篇文章不从概念堆砌开始直接按“先搞懂它是什么再上手安装最后自己造一个”的顺序走目标是让看完的人能独立完成从使用 Claude Code 的现成 Skills 到创建自定义 Agent Skill 的完整闭环。这次内容不止讲原理会覆盖几个关键问题Agent 和 Skills 到底是什么关系、Claude Skills 安装在哪里、SKILL.md 怎么写、如何把一个技能接入真实工作流、批量任务怎么处理、以及最容易被卡住的排错点。如果你正在做 Agent 应用、研究 Claude Code 或准备把 AI 接入论文写作、代码审查、数据处理这类具体任务这篇建议直接收藏。1. 核心能力速览能力项说明项目类型AI Agent 技能机制 / 提示工程实践核心概念Agent Skills、Claude Skills、技能包、SKILL.md主要功能让 Agent 按固定流程完成代码审查、写作辅助、数据处理、结构化输出等任务运行环境同一套技能机制可覆盖 Claude Code 等 Agent 场景是否需要 GPU不需要云端模型服务即可安装方式现成技能包复制到 Skills 目录自定义技能按模板创建扩展能力支持接口集成、批量任务、按场景拆分的多技能管理适用人群使用 Claude Code 的开发者、AI 应用研究者、需要 Agent 自动化工作流的效率工具使用者使用边界输出质量依赖模型版本、任务复杂度敏感数据需注意隐私合规2. 理解 Agent SkillsAgent 与 Skills 的区别先把最容易混淆的概念理清楚。Agent智能体是一个能感知环境、做出决策、调用工具并执行多步任务的系统。它可以理解用户意图规划步骤然后一步步调用工具完成目标。真正让 Agent 区别于普通聊天机器人的是“自主执行”这个能力。Skills技能是什么它是一个可复用的能力模块通常由一组指令、示例脚本、参考文档和元数据组成。它不负责规划负责的是“在正确的时候提供正确的方法”。用一句话概括Agent 是大脑和身体Skills 是身体里的专项技能包。Agent 负责判断什么时候该用哪个技能Skills 负责告诉 Agent 具体怎么做。再看一个常见问题AI Skills 和 Agent 有什么区别Agent 是完整的执行实体有目标、有计划、有工具调用能力。Skill 是 Agent 的能力组件可以被加载、被卸载、被复用。如果把 Agent 类比成一个员工Skills 就是这个员工的岗位技能认证。员工本人不会因为多拿一个认证就换一个人但他能处理的事情范围会明显扩大。另一个容易混淆的概念是 MCPModel Context Protocol。MCP 解决的是 Agent 与外部工具之间的通信协议问题偏向“连接外部资源”Skills 解决的是“任务操作方法”问题偏向“告诉 Agent 怎么一步步做”。实际项目里两者可以配合使用MCP 负责访问外部系统Skill 负责把访问到的数据按固定流程加工成目标结果。3. Agent Skills 的使用场景与合规边界从搜索热词里可以看到几个典型场景好用的 Claude Code Skills 安装、Agent Skills 赋能人文社科混合研究方法论文写作、AI Agent Skills 推荐、AI Skills 和 Agent 的区别。这些场景基本覆盖了 Agent Skills 的主战场。3.1 适合的场景代码相关的技能是最成熟的。你可以给 Claude Code 安装一个“代码审查技能”让它按团队规范检查 PR也可以装一个“单元测试生成技能”让它按指定框架生成测试用例。文档处理场景也很实用。把“读取 PDF - 提取关键信息 - 输出结构化 Markdown”这个流程固化成 Skill之后所有同类文档处理任务都可以直接触发不需要每次重复写提示词。研究写作场景。部分热词提到“Agent Skills 赋能人文社科混合研究方法论文写作”本质上是用 Skill 把“文献检索 - 方法选择 - 数据整理 - 论文结构生成 - 引用规范检查”这类长流程标准化。这里必须强调AI 辅助写作不等于代写使用时应遵守学术诚信规范论文的论点、实验和最终审核必须由研究者本人负责。批量任务场景。Agent Skills 配合 Claude Code 的会话能力可以对一批文件执行同样的处理流程例如批量整理日记、批量生成数据报表说明、批量检查文档格式。3.2 不适合的场景需要严格实时数据或精确计算的任务Skill 本身不保证结果绝对正确需要人工复核。涉及核心业务决策、法律文书、医疗建议的场景不能把 Skill 的输出当最终结论。需要在本地离线跑的任务由于依赖云端模型服务离线场景无法使用。3.3 合规边界使用第三方现成 Skills 时先看技能包的来源和内容避免把包含敏感操作指令的技能直接放进生产环境。涉及公司内部代码、用户隐私数据、未公开论文材料时要考虑数据是否会发送到第三方 API必要时先脱敏再处理。涉及肖像、声音、版权材料的内容必须确认授权。任何自动化操作都要保证在授权范围内执行。4. Claude Code 环境准备Claude Code 是运行 Agent Skills 最直接的入口。它的本质是命令行 AI 编程助手可以在终端里通过对话方式让 AI 读代码、改代码、跑命令。Skills 功能能让它在特定任务上表现得更稳定。4.1 环境依赖检查项要求操作系统Windows / macOS / Linux 均可Windows 建议提前装好 Git Bash 或 PowerShell 环境Node.js建议安装当前 LTS 版本Claude Code 通过 npm 分发npm 访问需要能正常访问 npm 仓库Claude 账号需要能访问 Claude 服务的账号或用 API Key 方式网络能正常访问 Claude API 域名4.2 安装 Claude Code安装命令以官方 npm 包为准通常是这样npm install -g anthropic-ai/claude-code安装完成后执行版本检查claude --version如果命令不存在检查 npm 全局 bin 目录是否加入了系统 PATH。Windows 下有时需要重新打开终端才会生效。4.3 登录与鉴权Claude Code 支持两种常见方式一种是订阅账号登录模式安装后直接执行claude按提示完成浏览器授权适合个人日常使用。另一种是通过 API Key 模式把 Anthropic API Key 设置到环境变量里export ANTHROPIC_API_KEYsk-ant-xxxxWindows PowerShell 下写法$env:ANTHROPIC_API_KEYsk-ant-xxxx注意 API Key 属于敏感信息不要写进公开脚本或提交到代码仓库。建议用系统环境变量或密钥管理工具维护。5. Claude Skills 安装路径与加载原理Claude Code 的 Skills 不是一个需要“运行”的程序它是一组需要被 Agent 读取的文件。安装的本质是把技能包放到指定目录让 Claude Code 启动时能扫描到。5.1 Skills 目录结构一个典型的 Skills 目录结构如下~/.claude/ └── skills/ └── code-review/ ├── SKILL.md └── reference/ └── review-checklist.mdSKILL.md 是技能的核心文件写清楚技能名称、触发条件和操作步骤Agent 会根据这个文件决定是否调用技能。reference 目录用来放参考材料。5.2 安装现成 Skills从仓库或社区下载技能包后复制到技能目录即可。例如要安装一个名为 code-review 的技能# 创建技能目录 mkdir -p ~/.claude/skills/code-review # 复制技能文件路径按实际下载位置调整 cp -r ./downloaded-skill/* ~/.claude/skills/code-review/复制完成后重启 Claude Code或者在会话里让 Agent 重新扫描技能目录。5.3 验证 Skill 是否被加载在 Claude Code 会话中输入与技能相关的任务描述看模型是否主动调用该技能。比如装好 code-review 技能后对 AI 说请审查当前项目的 src/main.py如果输出里出现类似“使用 code-review 技能”“按审查清单逐项检查”的内容说明技能已生效。5.4 SKILL.md 基本格式SKILL.md 通常包含 frontmatter 元数据和正文两部分。元数据里声明技能名称与描述正文给出详细操作指令。一个标准模板如下--- name: code-review description: 按团队规范审查代码检查逻辑缺陷、安全问题和风格一致性。 --- # Code Review Skill 当用户要求审查代码时按以下步骤执行 1. 读取目标文件。 2. 检查函数边界与错误处理。 3. 对照 reference/review-checklist.md 逐项检查。 4. 输出问题清单标注严重级别。这里的设计逻辑是描述要让模型能判断“什么时候用这个技能”正文要让模型能判断“用了之后第一步干什么、第二步干什么”。6 创建一个自定义 Agent Skill从会用到会造“从会用到会造”是这套教程的核心目标。使用别人的技能只是第一步真正提升效率的关键是根据自己的任务习惯创建技能。下面用一个例子说明如何从零创建一个技能。场景是“把一段非结构化的会议记录整理成结构化报告”。6.1 设计任务流程先想清楚这个任务的标准操作流程读取原始会议记录文本。提取参会人员、时间、议题、决议。按固定模板输出 Markdown 报告。标出待办事项和负责人。6.2 创建技能目录和文件mkdir -p ~/.claude/skills/meeting-notes6.3 编写 SKILL.md--- name: meeting-notes description: 将非结构化会议记录整理为结构化 Markdown 报告提取议题、决议和待办事项。 --- # Meeting Notes Skill 当用户提供会议记录文本时按以下模板整理。 ## 输出模板 ### 会议基本信息 - 会议时间 - 参会人员 ### 议题与讨论 - 议题 1 - 讨论要点 - 结论 ### 决议 - 决议 1 ### 待办事项 | 事项 | 负责人 | 截止时间 | | --- | --- | --- | ## 处理规则 - 原文内容不足的字段留空不编造。 - 待办事项必须对应明确负责人。6.4 测试自定义技能在 Claude Code 中输入请用 meeting-notes 技能整理以下会议记录 “3月2日会议参加人有张伟、李娜。讨论了新功能上线计划决定下周四发布张伟负责前端李娜负责后端。数据库迁移问题下次再谈。”预期输出一份带有会议信息、议题结论、待办事项表格的 Markdown 报告。如果输出没有触发模板检查技能目录路径是否正确、描述是否清晰。6.5 技能设计要点技能的描述比正文重要。模型通过描述决定是否调用技能描述写得模糊技能就会经常被漏掉描述写得太泛又会在不合适的场景被误调用。正文里的步骤必须可执行尽量减少“根据情况灵活处理”这类模糊表述改用明确动作。7. Agent Skills 实战场景详细演示7.1 代码审查技能实战先给 Claude Code 装一个代码审查 Skill然后准备一个简单 Python 文件def calculate_avg(nums): total 0 for n in nums: total n return total / len(nums)在 Claude Code 中发起审查请求预期输出包含空列表会导致除零异常、建议添加防御性判断、命名规范是否一致、是否需要类型注解。这类技能适合接入到 CI 工作流中做“提交前检查”。做法是把 Claude Code 的命令封装成脚本在 git commit 之前自动对变更文件执行代码审查。7.2 文档批量处理技能实战批量任务在 Agent Skills 场景里很常见。可以把“读取文件 - 提取核心观点 - 生成摘要卡片”固化成 Skill然后对多个文件循环执行。一个通用做法是定时任务加技能触发# 批量处理 inputs 目录下的所有文稿 for file in ./inputs/*.md; do echo Process file: $file claude -p 请调用 summarize-skill 处理文件 $file输出摘要到 outputs/ 目录 done-p表示非交互式一次性执行。不同版本的 Claude Code 参数可能不同使用前查看本机帮助claude --help批量任务要注意文件数量较多时会依次调用模型接口耗时和费用都会上升建议分批处理并给每个文件加独立的输出日志。7.3 人文社科论文写作辅助技能实战论文写作辅助是热词里提到较多的方向。典型做法是创建一个 mixed-methods-research Skill把混合研究方法论文的写作流程固化为研究问题拆解、文献综述结构、定性数据组织、定量数据组织、方法交叉分析、结论与局限。这类技能在建立时尤其要注意学术伦理。它可以帮助整理思路、检查结构、生成初稿框架但数据真实性、实验设计、最终结论仍由研究者掌握。提交论文前必须完成独立验证不能直接使用未复核的 AI 生成文本。8. 接口集成与批量任务设计Claude Skills 不只是终端里的玩具。如果希望把技能能力接入自己的业务系统可以通过 API 或调用封装好的脚本实现。8.1 通过 API 封装技能调用Skill 本身不直接暴露 API它起作用的方式是“把特定任务的提示词流程固定下来”。因此封装 API 时需要把 Skill 的逻辑放进请求上下文。用 Python 调用的思路如下实际请求地址、请求头、参数名须按你所用的模型服务文档调整import requests API_URL https://api.example.com/v1/messages API_KEY your-api-key headers { x-api-key: API_KEY, anthropic-version: 2023-06-01, content-type: application/json, } payload { model: claude-model-name, max_tokens: 1024, messages: [ { role: user, content: 请使用 code-review 技能审查以下代码\npython\ndef add(a, b):\n return a b\n } ] } response requests.post(API_URL, headersheaders, jsonpayload, timeout120) print(response.json())这个示例只用于说明思路。真实项目中应使用官方 SDK并优先调用你所用服务的官方接口文档。8.2 批量任务队列设计多个 Skill 场景下建议按以下结构组织批量任务inputs/ # 原始输入文件 file-01.md file-02.md outputs/ # 处理结果 file-01.md.summary.md logs/ # 任务日志 batch-20260301.log skills/ # 自定义技能 code-review/ meeting-notes/批量脚本要加两层保护一是处理前检查文件格式二是每个文件单独捕获异常避免一个失败导致整个队列中断。8.3 失败重试建议调用模型服务时可能遇到超时、限流、结果截断。建议采用以下策略每个任务记录状态成功写入 outputs失败写入 failed 列表。对超时任务做指数退避重试例如第 1 次等待 5 秒第 2 次等待 20 秒。设置单任务最大重试次数防止死循环。输出结果如被截断可设置更大的 max_tokens或要求模型分段输出。9. 资源占用与性能观察Agent Skills 的运行主要在模型侧本地几乎不占显存也不需要 GPU。它占用的是“模型推理的 token 消耗”和“执行动作产生的工具调用时间”。9.1 如何观察成本加入技能后每次任务会把 SKILL.md 的内容作为上下文发送给模型相当于增加了一部分输入 token。技能包越大、参考文档越详细输入 token 越高。设计技能时要注意SKILL.md 正文尽量精简只保留必要步骤。大段参考资料放到 reference 目录仅在需要时按需读取。避免把整个手册塞进 SKILL.md。9.2 影响响应速度的因素Skill 描述是否精确描述模糊时模型可能多次判断是否调用。任务复杂度步骤越多模型调用工具的轮数越多。参考文档大小Agent 读取大文件会显著增加耗时。网络延迟模型服务在远端时接口延迟直接影响体验。9.3 降低开销的方法一个技能只解决一个问题。把多步骤任务拆成多个技能按需调用而不是设计一个巨型技能。对高频简单任务可以把输出格式直接写死在技能里减少模型自由发挥空间。10. 常见问题与排查方法问题现象可能原因排查方式解决方案claude 命令找不到npm 全局目录不在 PATH执行npm config get prefix查看全局目录将目录加入 PATH 后重开终端登录时无法授权网络不通或账号异常检查账号状态和网络重试授权流程必要时清除登录缓存API Key 无效环境变量未生效在当前终端执行echo $ANTHROPIC_API_KEY重新设置环境变量并重启终端Skill 被调用但没按模板输出SKILL.md 描述不清晰查看模型输出是否提到技能名重写 description明确触发条件Skill 根本没有被加载目录路径错误检查 ~/.claude/skills 下的目录名修正技能目录路径和 SKILL.md 文件名批量任务某个文件失败文件格式异常或内容过长查看日志文件中的错误信息单独处理失败文件调整分批逻辑API 调用超时网络波动或任务过重观察具体超时环节增加超时时间拆小任务加退避重试输出结果被截断max_tokens 设置过小观察输出是否在句中断开调大 max_tokens或让模型分段输出模型频繁误调用技能description 写得太泛检查每次调用时模型判断依据缩小 description 中的触发条件范围更新技能后不生效Agent 缓存旧文件重启 Claude Code清空会话后重新加载其中最容易踩的坑有两个。第一个是 SKILL.md 的文件名必须完全一致大小写也不能错Agent 按固定名称扫描。第二个是 description 写得像广告而不是触发条件导致模型在错误场景频繁调用或完全不调用。11. 最佳实践与使用建议11.1 第一优先验证单技能最小闭环不要一上来就设计复杂技能。先装一个现成技能跑通一个任务确认它能被识别和调用。再创建一个最简单模板技能确认自己创建的也能被调用。最小闭环跑通后再逐步增加复杂度。11.2 保持技能可维护技能是代码需要版本管理。把所有技能放进 Git 仓库SKILL.md 变更要有提交记录。技能描述和正文都使用英文或统一语言避免模型理解偏差。每个技能配一个 example.md 示例说明输入和预期输出。11.3 控制上下文长度技能越多Agent 启动时的扫描开销和上下文占用越高。不需要每次会话使用的技能就不要常驻可以按项目拆分技能目录或者用临时目录加载特定技能。11.4 安全与授权不把包含敏感信息的文件直接交给第三方模型处理先脱敏。不加载来源不明的 Skill尤其是不明脚本防止恶意指令注入。批量任务和自动化操作仅在授权范围内执行。涉及人脸、声音、版权素材时必须确认授权。论文写作场景中AI 只做辅助学术诚信由研究者负责。12. 总结与下一步Agent Skills 是一个比大多数人想象的更轻量的能力提升方式。它不改变模型本身而是通过“给 Agent 一份更清晰的操作手册”来提升结果稳定性。安装一个 Skill 本质上是把一段可复用的提示词和流程打包放进 Agent 能读取的目录。这套体系最值得先验证的是一个能解决你高频重复任务的技能是否能明显减少你每次重复描述需求的时间。如果答案是能说明你的场景适合继续扩展。通过这套流程你可以先从社区找 2 到 3 个现成 Skills 装上实际跑几天感受触发效果。然后挑一个自己每天都在做的重复任务按 SKILL.md 模板做一个简化版技能跑通后再逐步完善。容易被忽略的一点是Skills 的价值不取决于数量而取决于“在正确的时候被正确调用”。把 skill 目录梳理清楚保持描述简洁比收藏很多技能更管用。下一阶段可以继续研究如何把同一套技能接入更复杂的 Agent 编排流程或者把它封装成内部工具服务配合 MCP 连接更多外部系统。