Agent Skills 完全指南：从安装到自定义技能开发

Agent Skills 最近热度很高围绕它的讨论集中在“能不能让 Claude 按我的方式干活”和“怎么把我常用的脚本变成 Agent 的肌肉记忆”。如果你已经用过 Claude Code但每次还要反复粘贴同样的说明、反复定义工具函数那这篇文章能直接帮你把重复劳动干掉。先给结论Agent Skills 本质上是一套“结构化的技能包”用 Markdown 描述技能用法用脚本实现具体动作。它和普通提示词最大的区别在于提示词是每次都要说一遍的“临时指令”而 Skill 是写进 Agent 工作流里的“长期能力”。本文会从概念、安装、测试、自己开发 Skill、批量任务、性能观察、踩坑排查一条龙讲完目标是让你从“能用”变成“会造”。1. Agent Skills 核心能力速览能力项说明项目类型Agent 技能扩展机制属于 Claude 生态的官方 Skill 能力核心功能让 Agent 按 SKILL.md 结构调用预设技能配合脚本完成任务主要载体Claude Code、Claude 桌面版等支持 Agent Skills 的客户端技能组成SKILL.md技能说明 scripts可执行脚本 辅助资源是否需要 GPU不需要Skills 本身不直接跑模型显存占用本地侧没有额外显存开销实际取决于模型接入方式是否支持批量任务可以配合 CLI 或 API 做批量调度具体以官方接口为准是否支持 API官方接口是否直接暴露 Skill 参数需要查对应文档通常通过 Agent 客户端加载启动方式启动 Claude Code 或 Claude 桌面版后自动加载对应目录下的 Skills适合用户开发、研究、文档处理、自动化流程建设者从这张表可以看出Agent Skills 更偏“工程化能力编排”不是一个新的模型也不依赖独立服务。重点关注的是怎么组织技能、怎么让 Agent 在合适的时候调用它。2. Agent Skills 与普通 Prompt、子代理的区别先对比一下容易混淆的三样东西普通提示词、子代理和 Agent Skill。维度普通 Prompt子代理Agent Skills存在方式对话中的文字描述独立的 Agent 进程结构化技能目录复用性每次重复粘贴可配置但通常较重量一次安装多场景复用执行方式全凭模型理解多轮推理循环按 SKILL.md 触发可跑脚本是否包含代码一般不含可能包含通常包含 scripts适合场景临时提问复杂任务拆解高频、确定性高的操作自动化这里的关键是“可执行”。写普通提示词时模型只是在生成文字有没有真正执行外部脚本取决于工具是否有对应功能。而一个合格 Skill 会把自己的使用说明、触发条件、脚本路径、参数示例全部写在 SKILL.md 里Agent 读完之后能像查说明书一样去调用脚本。所以“会用到”和“会造”差距很大。会用的人只是从别人那里装一个 Skill 进去会造的人清楚 SKILL.md 的 frontmatter 怎么写、脚本的输入输出怎么设计、怎么在测试时快速确认 Agent 真的调用了技能。这也是本文重点要讲的。3. Agent Skills 适用场景与使用边界3.1 适合什么场景Agent Skills 适合任何“有明确步骤、可脚本化、需要反复执行”的任务典型包括代码开发代码规范检查、自动化补丁生成、项目脚手架创建。文档处理批量转 Markdown、表格抽取、PDF 内容整理。数据分析固定格式的报表生成、数据清洗模板。学术研究和写作辅助文献整理、摘要生成、结构化笔记但必须遵守学术规范和引用要求。日常自动化会议纪要模板、邮件草稿、任务清单拆分。这些场景的共同特点是步骤固定、输出格式可预期、需要频繁复用。3.2 使用边界与合规提醒Agent Skills 不是万能自律程序它有明确边界不能替代人工审查。生成代码、文档或数据分析结论后一定要人工复核。涉及人脸、声音、身份信息、版权素材时必须确认授权。例如做肖像处理、音色克隆相关 Skill 时没有授权就不允许输入相关素材。不要把 API Key、密码、Token 写进 Skill 的公开目录或提交到代码仓库。学术写作场景下用 Skill 做辅助整理可以但要明确区分 AI 生成内容遵守期刊和学校的规范。如果 Skill 要安装第三方脚本先检查脚本源码避免运行来源不明的代码。4. 环境准备与前置条件Agent Skills 不挑显卡也不需要复杂的 Python 环境核心前置条件是能运行支持 Agent Skills 的客户端。4.1 基础环境Claude 账号需要能访问支持 Agent Skills 的服务。Claude Code推荐使用官方 CLI 版本便于测试和批量调用。Node.js / npm如果你通过 npm 安装 Claude Code需要 Node.js 环境。具体版本要求以官方文档为准。Git用于从 GitHub 拉取第三方 Skills 仓库。终端工具Windows 可以用 PowerShell 或 Windows TerminalmacOS/Linux 用系统终端。4.2 Skills 目录位置Agent Skills 通常从两个位置加载用户级目录~/.claude/skills/项目级目录.claude/skills/用户级目录下的技能对所有项目生效项目级目录只对当前项目生效。实际路径可能随客户端版本变化建议在 Claude Code 中执行help或查看官方文档确认。4.3 磁盘和网络要求磁盘占用很小每个 Skill 一般只有几千字节到几 MB主要是脚本和文档。网络方面要求能正常访问 Claude 的服务端接口不要让请求超时。5. 安装部署与启动方式从零安装 Claude Skills这一节演示一种通用安装思路具体命令以你的客户端版本为准。5.1 准备 Claude Code常见安装方式是通过 npm 全局安装命令类似npm install -g anthropic-ai/claude-code安装完成后在终端确认版本claude --version如果提示找不到命令检查 npm 全局 bin 目录是否在 PATH 中。5.2 创建 Skills 目录先验证目录是否存在不存在就创建mkdir -p ~/.claude/skills cd ~/.claude/skills项目级 Skills 同理在项目根目录执行mkdir -p .claude/skills5.3 安装现成 Skill从 GitHub 或官方示例仓库复制一个 Skill 进去。示例# 进入你的用户级 Skills 目录 cd ~/.claude/skills # 克隆一个 Skill 仓库以官方或可信第三方仓库为例 git clone https://github.com/example/your-skill-repo.git your-skill-name # 删除其中的 .git 目录避免嵌套仓库 rm -rf your-skill-name/.git注意上面的地址是占位示例实际安装时请用你确认过的仓库地址安装前先看仓库说明和源码。5.4 验证 Skill 是否被加载启动 Claude Codeclaude在对话中直接问你现在加载了哪些 Skill如果安装正确Agent 会列出对应的技能名称和用途。如果没看到检查目录结构是否是标准的skills/skill-name/SKILL.md。5.5 目录结构示例一个标准的 Skill 目录大概长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── run.py │ └── config.json └── assets/ └── template.mdSKILL.md是入口文件其他的脚本、配置、模板都服务于这个技能。6. 功能测试与效果验证装完 Skill 之后最重要的是确认 Agent 真的会调用它而不是假装理解。6.1 测试用例触发技能给 Agent 一个任务明确指向该技能的应用范围。例如你安装了一个“PDF 转 Markdown”的 Skill可以这样输入请把 ./docs/sample.pdf 转成 Markdown输出到 ./output/sample.md使用 PDF 转换技能。预期结果Agent 调用了对应 Skill 的脚本生成了 Markdown 文件并在输出中说明它使用了哪个技能。6.2 判断标准判断是否成功主要看三点Agent 是否在推理过程中提到加载或使用某个技能。是否执行了技能目录下的脚本而不是自己“假装转换”。输出文件是否真实存在并且格式符合 SKILL.md 中的描述。如果任务确实生成了文件但 Agent 根本没引用技能说明技能描述写得不够清晰或当前模型版本对 Skill 的感知较弱。6.3 常用验证维度验证维度操作通过标准技能加载询问 Agent 当前可用技能能列出 Skill 名称和用途触发调用输入与技能相关的任务Agent 主动使用技能错误处理给一份错误格式的输入Agent 能根据 SKILL.md 给出提示多轮复用连续执行两次同类任务第二次不再重复解释步骤脚本兼容使用不同操作系统执行脚本无路径或权限报错6.4 常见失败原因目录名和 SKILL.md 中的 name 不一致。SKILL.md 没有写清楚触发条件Agent 不知道什么时候该用。脚本缺少执行权限Linux/macOS 下需要chmod x。脚本依赖的 Python 包或 Node 模块没有安装。7. 如何自己开发一个 Agent Skill从会用到会造自己造一个 Skill 并不难核心是写好 SKILL.md 和配套脚本。7.1 定义目标先想清楚这个 Skill 要解决什么问题输入是什么输出是什么尽量避免做“万能技能”一个 Skill 只干一件事效果最好。例如做一个“批量 Git 提交信息生成”的技能。输入是一段 git diff 统计输出是符合规范的中文提交信息。7.2 创建 SKILL.mdSKILL.md 一般由 frontmatter 和正文组成。frontmatter 里至少包含技能名称和描述正文则写清楚使用方式和示例。下面是一个通用模板--- name: git-commit-helper description: 根据 git diff 文件列表生成规范化的提交信息用于代码提交前提供建议。 --- # Git Commit Helper ## 功能说明 读取用户提供的 diff 概述或文件列表输出符合 Conventional Commits 风格的提交信息。 ## 使用方式 当用户要求“生成提交信息”时执行以下步骤 1. 获取 git 状态和 diff 摘要。 2. 分析变更类型feat、fix、docs、refactor 等。 3. 输出一条或多条提交信息建议。 ## 示例 输入 调用 git diff --stat 得到结果。 输出 feat(api): 增加用户批量查询接口 fix(auth): 修复 token 刷新失败问题描述不要写空话比如“这个技能很强大”不适合写在这里而是要写清楚“什么时候触发、该怎么用、有什么输入输出约束”。7.3 添加可执行脚本如果技能包含脚本scripts/run.py可以接收命令行参数并输出结果。示例#!/usr/bin/env python3 import sys def main(): diff_summary sys.stdin.read() if not diff_summary.strip(): print(没有读取到 diff 内容) return 1 print(生成的提交信息示例) print(feat: 更新核心模块) if __name__ __main__: main()在 SKILL.md 中说明脚本调用方式## 脚本调用方式 执行 python scripts/run.py通过标准输入传入 diff 内容。这样 Agent 在需要时可以直接运行脚本而不是自己“脑补”结果。7.4 测试技能开发完成后把它放到刚才的 skills 目录中cd ~/.claude/skills mkdir -p git-commit-helper/scripts cp run.py git-commit-helper/scripts/ cp SKILL.md git-commit-helper/SKILL.md然后启动 Claude Code用真实任务触发帮我看看当前仓库的改动建议几条提交信息。观察是否真正调用了这个技能并根据结果迭代 SKILL.md 的描述。7.5 发布与复用如果你想让团队或社区复用这个 Skill可以建立 Git 仓库写明依赖和安装方式。发布前检查不包含任何密钥、内网地址、私人路径。脚本有清晰的入口参数。SKILL.md 里有安装和调用说明。第三方依赖在 requirements.txt 或 package.json 中声明。8. 批量任务与自动化调用Agent Skills 很适合批量任务和自动化流程。最常见的做法不是手动开一个对话然后慢慢等而是把任务列表交给脚本配合 Claude Code CLI 执行。8.1 批量任务设计推荐用一个 JSON 文件维护任务清单{ tasks: [ { id: task-001, input: ./inputs/doc1.pdf, output: ./outputs/doc1.md, skill: pdf-to-markdown }, { id: task-002, input: ./inputs/doc2.pdf, output: ./outputs/doc2.md, skill: pdf-to-markdown } ] }然后写一个调度脚本遍历任务并调用 Claude Code。下面是通用 Python 示例具体命令需要按实际客户端接口调整import json import subprocess import time with open(tasks.json, r, encodingutf-8) as f: config json.load(f) for task in config[tasks]: print(f开始处理: {task[id]}) command ( claude -p f\使用 {task[skill]} 技能将 {task[input]} f转换为 {task[output]}\ ) try: result subprocess.run( command, shellTrue, capture_outputTrue, textTrue, timeout600 ) print(result.stdout[-500:]) if result.returncode ! 0: print(f任务 {task[id]} 失败: {result.stderr[-500:]}) except subprocess.TimeoutExpired: print(f任务 {task[id]} 超时) time.sleep(1)注意这里的claude -p是一种常见的命令式调用方式具体参数以你安装的版本为准。实际使用时建议先跑一个任务验证命令格式。8.2 失败重试与日志批量任务必须有日志和重试机制。日志至少记录任务 ID、开始时间、结束时间、返回码、输出摘要。重试时建议限制次数避免死循环。for attempt in range(3): result run_task(task) if result[success]: break print(f第 {attempt 1} 次重试)8.3 定时触发如果任务是周期性的例如每天生成报表可以在 CI 中配置 cron或在服务器上使用 crontab。注意控制并发避免同一时间发起大量请求导致限流。# crontab 示例每天凌晨 2 点执行批量任务 0 2 * * * cd /path/to/project python batch_runner.py logs/batch.log 219. 资源占用与性能观察Agent Skills 本身不会直接跑大模型所以没有所谓的本地显存占用。性能开销主要看两点Agent 调用外部脚本的耗时以及模型处理技能描述时消耗的上下文。9.1 上下文 Token 开销SKILL.md 会作为上下文的一部分被模型读取。如果 SKILL.md 写得太长每次加载都会增加 Token 消耗。建议把描述控制在几百行以内把高频信息放在前面把完整实现细节放进脚本或单独文档。9.2 脚本执行耗时脚本的执行时间是主要瓶颈。如果 Skill 执行的是 PDF 解析、图片处理、网络请求耗时可能从几秒到几分钟。批量任务时要设置合理超时时间比如单任务 600 秒。9.3 如何降低开销减少 SKILL.md 篇幅只保留核心调用规则。将常用数据缓存到本地避免重复请求。批量任务限制并发数。任务失败时第一时间看日志不要让错误任务反复空转。如果后续你自己接入了本地模型或其他推理后端才需要关注 GPU 显存。那时显存占用取决于模型大小和推理参数和 Skills 机制没有直接关系。10. Agent Skills 常见问题与排查方法问题现象可能原因排查方式解决方案启动后看不到 Skills目录路径不对或版本不支持检查~/.claude/skills和项目.claude/skills按官方文档调整目录Agent 不调用技能SKILL.md 描述不清晰观察 Agent 输出确认是否提到技能重写 description加上触发条件脚本执行失败缺少依赖或权限不足手动运行脚本看报错安装依赖、chmod x、修复路径中文路径报错路径编码问题检查脚本是否使用 UTF-8代码中统一用 UTF-8 处理路径API 调用被限流并发过高查看错误码和日志降低并发增加重试间隔Skill 目录被当成仓库没有删除.git检查目录内是否包含.git克隆后删除.git批量任务卡住超时时间设置过短或脚本等待输入查看进程状态和日志增加超时时间让脚本支持非交互模式输出质量不稳定技能描述太宽泛给更多示例和约束条件在 SKILL.md 中加入输入输出示例排查思路永远是一层层往下拆先看 Skill 有没有被加载再看 SKILL.md 描述是否清楚最后看脚本本身能不能独立运行。把这三层测通大部分问题都能解决。11. Agent Skills 最佳实践与使用建议11.1 从高频小任务开始不要一上来就写一个“万能检查助手”。先挑一个你每周都会手动做三次以上的任务比如整理会议纪要、生成周报、格式化代码。把它做成 Skill验证整个流程跑通再逐步扩展。11.2 写清楚“什么时候用”SKILL.md 的 description 是 Agent 判断是否调用技能的关键。要用“当用户需要……时”这种句式而不是“本技能用于……”这种空泛描述。示例description: 当用户需要将 Markdown 批量转换为 Word 文档时使用。11.3 保持脚本独立可测Skill 内的脚本不依赖 Agent 也能运行。把输入输出设计成命令行参数或标准输入这样你可以先手动跑通脚本再接入 Skill排错成本会低很多。11.4 版本管理Skills 目录应该纳入 Git 管理特别是项目级.claude/skills。每次修改 SKILL.md 或脚本后生成一个新的版本方便回滚。11.5 安全合规技能仓库中禁止出现密钥、Token 和私人路径。如果 Skill 处理他人数据先确认数据源合法。人脸、声音等敏感内容必须获得明确授权。生成用于论文、报告或公开内容的文字时要遵守学术规范不能直接用 AI 输出当原创成果。11.6 关注官方更新Agent Skills 这一块迭代比较快目录格式、加载方式、配置项都可能变化。建议定期查看官方文档并在版本升级后重新跑一遍最小验证用例。12. 总结与下一步Agent Skills 最有价值的地方是把“提示词”变成了“可复用的技能包”。你不需要反复把上下文粘贴给 Claude也不需要自己维护一堆零散脚本只需要把每个高频任务整理成 SKILL.md scripts 的结构Agent 就能在合适的时候自己调用。第一步建议先装一个现成 Skill 感受整个流程再把你最近重复做过三次以上的任务挑出来写一个最简单的 SKILL.md配一个 20 行以内的脚本跑通一次验证。最容易踩的坑有两个一个是 SKILL.md 描述不够明确Agent 根本不触发另一个是脚本写死了本机路径换台机器就崩。避开这两个坑Agent Skills 的学习曲线会平缓很多。后续可以继续往这几个方向扩展把 Skill 接到 CI 里做自动检查、结合外部知识库做资料检索、把多个 Skill 串联成一个复杂工作流。建议先把本文提到的“一个技能只干一件事”原则记住然后去建自己的第一个技能目录。如果这篇文章对你有帮助建议收藏备用。下次需要批量处理任务时直接打开照着做就行。