Agent Skills实战指南：从安装、编写到排错

最近在折腾 Agent 项目的时候发现一个特别有意思的现象不管是 Claude Code、Codex、OpenCode 还是 Pi Agent大家的关注点已经从“怎么让模型变聪明”转移到了“怎么把能力做成可复用的技能包”。这个技能包就是今天要聊的 agent-skills。Agent Skills 说到底就是一整套“给 Agent 加外挂”的标准化方案。你可以把它理解成模型的插件、工具集、或者一份结构化的操作手册让大模型在特定场景下不用从零推理而是直接调用你写好的流程、脚本和示例。这篇内容适合两类人一类是刚开始接触 Agent 开发想知道 Skills 怎么装怎么用另一类是已经在写 Agent 工作流想把手头重复性工作沉淀成标准技能的开发者。我会从概念、安装、编写到排错把整套流程里值得注意的细节一次讲清楚。1. Agent Skills 到底是个什么东西1.1 Skill、Agent、Harness三者到底是什么关系很多朋友一上来就被 “Agent” 和 “Skill” 这两个词绕晕了更别提还有一个叫 “Harness” 的东西。我尽量用大白话把这几个概念拆开。Agent 是决策者它的核心任务是理解用户意图、拆解任务、决定下一步调用什么工具。Skills 是能力包是“一段描述 若干脚本 示例”的组合相当于告诉 Agent当遇到某类任务时可以按这个流程执行可以调用这些脚本。Harness 则是运行环境或者说执行骨架它负责调度 Agent 的循环接收消息、调用工具、处理结果、把上下文反馈给模型然后继续下一轮。用一个开餐厅的例子来类比Agent 是主厨负责判断客人想要什么菜、决定怎么做Harness 是厨房提供灶台、厨具、上菜流程Skills 就是菜谱和预处理好的半成品。主厨不可能把所有菜谱都背在脑子里他需要的时候从架子上拿下来照着步骤操作就行。这里特别要区分一下 Skill 和 Memory。Memory 是 Agent 对历史对话和用户偏好的持久化记忆解决的是“记不记得你是谁”的问题Skill 是能力模块解决的是“会不会做某件事”的问题。很多项目把这两者混着用结果要么记忆越堆越乱要么技能包越写越像聊天记录。1.2 为什么突然大家都在聊 Skills两三年前我们做大模型应用流行的是把所有指令、示例、上下文全部塞进一个超级 Prompt 里。说实话那种方式在 demo 阶段很爽一到真实项目就崩。原因很简单任务一旦复杂Prompt 里的指令会互相冲突上下文长度也撑不住而且你没法把一套好用的方法复制到另一个项目里。Skills 之所以在最近火起来是因为大家发现与其让模型在每次对话里重新“理解”一遍流程不如把流程直接封装成可复用的模块。比如你想让 Agent 帮你生成 LaTeX 排版文档如果你不在 Skills 里写明模板位置、编译命令、常见错误处理模型大概率会给你一段残缺的 LaTeX 代码然后告诉你“请自行编译”。而挂上对应的 Skill 之后它会自动读取模板、调用编译脚本、检查输出文件最后把 PDF 路径返回给你。还有一层原因是 Agent 开发已经从“跑通一个 Demo”进入“团队协作”阶段。项目里多 Agent 协作每个 Agent 负责不同职责如果没有标准化的技能包每个人写的工具调用方式都不一样代码根本没法维护。Skills 提供了一种通用接口让不同框架、不同模型之间能够共享能力。1.3 Skill 的典型形态与运行机制目前主流 Agent 框架里的 Skill 大同小异一般都包含两个核心部分描述文件和可执行脚本。描述文件通常是 SKILL.md里面写了这个 Skill 的用途、适用场景、触发条件、使用步骤、参数说明、示例等。Agent 在收到用户任务后会先读取当前可用的 Skill 列表然后根据描述文件判断该不该调用、怎么调用。用专业一点的话说SKILL.md 是给大模型看的“API 文档”。可执行脚本则是 Skill 落地的主体可能是 Python、Shell、Node.js 或者其他任何能被 Agent 调用的程序。这些脚本接收输入参数执行具体操作然后把结果返回给 Agent。一个 Skill 可以包含多个脚本比如一个负责数据抓取一个负责清洗一个负责生成报告它们之间通过描述文件串联起来。运行机制上Agent 框架通常会在系统提示词里注入可用 Skills 的概览或者提供一个类似 list_skills 的工具让 Agent 在需要时主动查询。触发以后框架会按照 SKILL.md 里的 instructions 加载脚本设置好工作目录和参数然后把脚本输出作为工具结果交给 Agent 做下一步决策。2. 怎么快速用上现成的 Skills2.1 去哪找靠谱的 Skills 源先用现成的别一上来就自己造轮子。目前 Skills 的资源生态已经比我预想的丰富很多GitHub 上有不少组织在维护高质量技能库比如 anthropics/skills官方示例和规范、obra/superpowers社区里非常火的 Superpowers 系列覆盖全流程开发提效以及各类 Awesome Agent Skills 清单。除了 GitHub 仓库一些 Agent 框架自带的社区市场也值得逛比如 OpenCode 社区里有人专门分享 codex 好用的 skillsClaude Code 的用户则习惯在 GitHub 上搜 “claude skills” 或 “claude code skills”。另外某些垂直场景的技能包比如 AI 漫剧、图片生成、LaTeX 排版、数学建模往往在相关的创作者社区里传播得更快多留意项目 README 和 issue 区能挖到不少好东西。需要提醒一句任何人下载的第三方 Skill 都要当心安全性。Skills 的本质是代码运行在你的本机上权限和你的用户一致。建议先从官方仓库和星标数高的项目开始安装前打开脚本目录扫一眼确认没有奇怪的网络请求或者删除操作再放进 Agent 配置目录。2.2 手动安装 GitHub 上的 Skills以 Claude Code 为例很多人问“Claude Code 怎么手动装 GitHub 上的 Skills”其实原理很简单把 Skill 目录复制到 Agent 的 skills 目录下然后重启会话。Claude Code 会扫描两个位置用户级别的~/.claude/skills/和项目级别的.claude/skills/。用户级对所有项目生效项目级只对当前项目生效。假设你想安装一个叫latex-helper的 Skill具体操作大概是# 进入技能目录 mkdir -p ~/.claude/skills cd ~/.claude/skills # 方式一直接把仓库克隆进来 git clone https://github.com/example/latex-helper.git # 方式二如果只需要某个子目录可以只拷贝对应文件夹 cp -r /path/to/downloaded/repo/skills/latex-helper ~/.claude/skills/装完之后检查一下目录结构是否正确。一个合法的 Skill 目录里至少要有SKILL.md~/.claude/skills/ └── latex-helper/ ├── SKILL.md ├── scripts/ │ ├── compile.py │ └── fix_errors.py └── assets/ └── template.texCodex 和 OpenCode 的逻辑几乎一模一样只是配置目录不同。Codex 通常放在~/.codex/skills/OpenCode 一般放在~/.config/opencode/skills/或者项目.opencode/skills/。如果你用的是 Pi Agent 这类桌面端工具一般在设置界面里都能找到“技能”或“Skills”的入口直接指向某个本地目录即可。2.3 那些值得先装一发的 Skills我平时装 Skills 的原则是“按场景选不贪多”。下面这张表是我目前觉得实用度比较高的几类Skill 类别代表项目/思路适用场景全流程开发提效superpower skills需求拆解、任务规划、代码审查、测试生成文档处理office 文档转 Markdown、PDF 解析从非结构化文档中提取信息LaTeX 排版latex-helper论文、报告、简历排版编译图片生成图片生成 skill 安装包海报、分镜、漫剧素材生成数学建模辅助codex 数学建模 skills建模比赛中的数据处理、公式推导、文档输出数据分析可视化pandas 辅助、图表生成快速做探索性分析和出图这里单独说一下“AI 漫剧常用 skills”。这类技能通常不是一个大而全的模块而是把图片生成、角色一致性、多帧分镜和配音字幕等功能拆成好几个小 Skills 串联起来。比如先加载角色描述生成技能生成基础人物图再调用分镜脚本把脚本拆成多帧提示词最后用图片拼接脚本合成漫画页面。装这类 Skills 的时候多留意它依赖了什么模型接口和图片处理库提前装好环境免得运行时才发现缺包。2.4 装完怎么验证 Skill 生效安装完成后第一步是确认 Agent 识别到了这个 Skill。Claude Code 里可以用斜杠命令预览# 在 Claude Code 交互界面中执行 /skills如果输出里出现了你新装的名字说明扫描成功。Codex 里可以运行codex --list-skills或者在会话里问一句“你现在有哪些技能”不过更稳定的方式还是看配置目录。OpenCode 一般会在启动日志里打印加载的 Skill 列表。第二步是实际触发一次。你不用直接说“使用 xxx 技能”而是描述一个该技能覆盖的真实问题。比如装了 LaTeX 排版技能以后你可以说“帮我用 LaTeX 生成一份包含摘要和参考文献的论文模板”看它是否主动去读取脚本和模板。如果它只是像普通聊天一样给你一段代码而不执行那说明技能没有被正确触发这时候要回头检查 SKILL.md 的描述质量和触发条件是否明确。3. 手写一个 Skill从需求到落地3.1 Skill 目录结构不要随便塞文件自己写 Skill 之前先建立一个清晰的目录结构。别看这只是文件摆放问题实际上决定了 Agent 能不能稳定地找到脚本、加载资源。一个标准结构大概是这样的my-skill/ ├── SKILL.md ├── scripts/ │ ├── main.py │ └── utils.py ├── prompts/ │ └── few_shot_examples.txt ├── assets/ │ └── templates/ └── requirements.txtSKILL.md是入口agent 会优先读取它scripts放可执行脚本prompts放示例或者补充指令方便在描述里引用assets放模板、静态资源。不要把脚本散落在目录根部也不要把大文件一股脑塞进 assets否则 Agent 在检索资源的时候会消耗大量 token。命名上目录名最好用小写中划线例如pdf-to-markdown而不是PdfToMarkdown或者pdf_to_markdown。这主要是为了兼容不同 Agent 框架的文件路径解析规则也避免大小写问题导致的“技能找不到”情况。3.2 把 SKILL.md 写到让 Agent 一眼就懂SKILL.md 是这个技能的灵魂它决定了大模型什么时候触发、怎么调用、调用之后如何组织答案。写它的时候心里要时刻记住这不是给人看的文档而是给一个“有点笨但很听话”的 AI 助理看的操作手册。我自己常用的 SKILL.md 模板是--- name: latex-helper description: 将 Markdown 或纯文本内容转换为 LaTeX 文档并编译为 PDF。适用于论文、简历、实验报告等需要规范排版的场景。当用户提到“LaTeX”、“论文排版”、“简历模板”、“编译 PDF”时使用。 --- # LaTeX 排版助手 ## 功能 - 根据用户提供的文本内容生成完整的 LaTeX 文件。 - 调用 xelatex 编译并自动处理常见编译错误。 ## 使用步骤 1. 读取用户输入确认需要生成的文档类型。 2. 读取 assets/templates/article.tex 作为主模板。 3. 将用户内容填充到模板中。 4. 在 scripts/ 目录下执行: python3 compile.py --input output.tex --engine xelatex 5. 将生成的 output.pdf 路径返回给用户。 ## 注意事项 - 如果编译失败读取日志中的错误信息调用 scripts/fix_errors.py 尝试修复。 - 不要直接修改用户的原始内容除非用户明确要求。写 description 的时候一定要把触发场景写清楚最好列出几个典型说法。比如“用户提到 LaTeX、论文排版、简历模板、编译 PDF 时使用”这样 Agent 在意图识别阶段就能快速匹配。不要写“处理任何排版问题”太泛了容易在使用其他技能时产生冲突。Instructions 部分要按步骤编号每步尽量具体到“读取哪个文件、执行哪个命令、参数是什么”。Agent 对模糊表述的容错率很低你写“运行编译脚本”它可能不知道该传什么参数你写“运行python3 compile.py --input output.tex --engine xelatex”它就能准确执行。3.3 背后的脚本怎么设计才不容易翻车SKILL.md 是给模型看的脚本则是真正干活的。脚本设计的核心原则是输入输出都要结构化行为要可预测。以 Python 脚本为例我一般会在入口处加参数解析并且给足默认值#!/usr/bin/env python3 import argparse import subprocess import sys from pathlib import Path def main(): parser argparse.ArgumentParser(descriptionCompile LaTeX file) parser.add_argument(--input, requiredTrue, helpInput .tex file) parser.add_argument(--engine, defaultxelatex, helpLaTeX engine) parser.add_argument(--output-dir, default./output, helpOutput directory) args parser.parse_args() input_path Path(args.input) if not input_path.exists(): print(fERROR: input file {args.input} not found, filesys.stderr) sys.exit(1) # 确保输出目录存在 Path(args.output_dir).mkdir(parentsTrue, exist_okTrue) result subprocess.run( [args.engine, -interactionnonstopmode, args.input], capture_outputTrue, textTrue, ) if result.returncode ! 0: print(fCOMPILE_ERROR: {result.stderr[-500:]}, filesys.stderr) sys.exit(2) print(fSUCCESS: {Path(args.output_dir) / (input_path.stem .pdf)}) sys.exit(0) if __name__ __main__: main()这里面有几个契而不舍的细节用capture_outputTrue捕获编译日志避免一大坨输出刷屏只用stderr的尾部错误信息减少 token 消耗返回值非零时给出明确错误码方便 Agent 判断是不是需要调用修复脚本输出路径用绝对路径或者相对 Agent 工作目录的稳定路径避免“文件明明生成了却找不到”。还要注意不要在这个脚本里做任何需要交互确认的操作Agent 无法实时应答不要把 API Key 或数据库密码写进脚本必要的时候从环境变量读取不要让脚本无限等待外部命令能加超时就加超时。3.4 从 0 到 1 写一个“图片生成” Skill 的思路热词里频繁出现“图片生成 skills 安装包”和“AI 漫剧常用 skills”这里我展开说说图片生成类 Skill 的写法。这类 Skill 通常不是让 Agent 直接画图而是把“提示词的构造、图像生成接口的调用、结果的保存与管理”封装在一起。基本思路是接受用户的场景描述比如“一个古风少女在月光下弹琴国漫风格”。通过一个 Python 脚本把场景描述扩展成适合图像生成模型的完整提示词加入画风、镜头、光线、质量标签。调用本地 Stable Diffusion 或云端图片生成 API返回图片路径或者 URL。将图片保存到指定目录并把 Markdown 格式的结果返回给 Agent。如果是做漫画分镜可以在 Skill 里写一个类似这样的流程step1: 把用户提供的剧本按 scene 切分。 step2: 对每个 scene提取角色、动作、背景、对白。 step3: 调用 character_design.py 生成角色一致性描述。 step4: 调用 generate_frame.py 逐帧生成图片。 step5: 调用 montage.py 将帧图按顺序拼接成漫画页面。每个 step 对应一个独立脚本保证任意一步失败都不影响其他步骤。这里有个很重要的经验图片生成类 Skill 的输出不要直接用二进制文件糊给 Agent而是返回文件路径和缩略图预览。否则上下文里塞满 Base64 图片Chat 窗口直接卡死。4. 实战中的坑与排查技巧4.1 agent execution terminated due to error. 大概率是这几个原因这个报错我在刚上手 Skills 的时候几乎天天见。字面意思是“Agent 执行因错误而终止”但真正原因通常不在提示词而在底层链路。我排查下来出现频率最高的是这几类第一类脚本权限不足。从 GitHub 上 clone 下来的脚本默认没有可执行权限尤其.sh文件。如果你在 SKILL.md 里直接写./fix_errors.shAgent 执行时会报警Permission denied。解决办法是统一改用bash fix_errors.sh或python3 xxx.py方式调用不依赖可执行位。第二类路径写死导致找不到文件。很多人写脚本时用os.getcwd()拿当前目录可 Agent 的工作目录未必是 Skill 所在目录。经验之谈是脚本入口统一用Path(__file__).resolve().parent定位自己的目录再拼接相对路径这样无论从哪个目录被调用都不会迷路。第三类脚本内部崩溃但错误信息不友好。比如 LaTeX 编译中途报错Python 脚本没捕获异常直接吐出堆栈信息。Agent 看到乱糟糟的 stack trace不知道该怎么处理就会判定执行失败。在脚本里加上try/except把错误收敛成一行提示会让情况好很多。第四类上下文超限或者输出格式异常。脚本如果打印了一批超长日志Agent 处理不过来也可能触发终止。我在脚本里一般只输出三种内容错误摘要、成功路径、关键状态其余一律写入日志文件。排查这类问题时先看 Agent 框架的日志再手动跑到对应脚本目录执行一遍命令通常很快就能定位。4.2 Skill 没被触发先从 description 和触发词查比执行报错更隐蔽的是“Skill 根本没被调用”。Agent 接到用户需求后直接像个普通聊天机器人一样回答完全绕过了你的技能包。这种问题八成出在SKILL.md的 description 上。模型选择技能靠的是语义匹配如果你的 description 写得太窄比如只写“处理 PDF”而用户说的是“把文件转换一下”模型可能就联想不到这个技能。我的经验是把 description 写成“多个触发名词/动词 场景 效果”的组合。比如description: 将 PDF、DOCX、扫描件等文档转换为结构化 Markdown。适用于论文、合同、书籍、资料整理等场景当用户提到“提取 PDF 内容”、“文档转 Markdown”、“表格识别”、“OCR”时使用。这样覆盖了更多可能的说法。还有一个小技巧在描述文件中明确写一句“当用户意图符合以上场景时必须使用本 Skill不要直接回答”虽然模型不一定每次都听但确实能提高命中率。另外检查一下是否有多个 Skill 的 description 高度相似。如果两个 Skill 都说自己能 “处理 PDF”模型就会困惑该用哪个。尽量让技能的职责边界清晰避免重复覆盖。4.3 Skills 的清理和版本管理Skills 装多了以后你会发现一个问题目录里堆了几十个技能但每天真正在用的可能只有五六个。 Skill 太多不仅浪费启动扫描时间还会给 Agent 的意图选择带来噪音。我在清理 Skills 时一般按照 “使用频率”“稳定程度”“是否冲突” 三个维度来筛。使用频率低的先移出常用目录放到备份目录还在迭代中的 Skills 不放进全局目录只在对应项目的.claude/skills里临时挂载两个功能重叠的技能保留能力更清晰的那个删除或合并另一个。如果你用的是 Git 管理项目建议顺手把 Skills 也纳入版本管理。我的做法是建一个skills-curated私有仓库里面按类别整理好所有正式启用的 Skills然后用软链接把它们映射到各 Agent 配置目录ln -s ~/workspace/skills-curated/latex-helper ~/.claude/skills/latex-helper这样每次更新技能只需要在源仓库git pull所有软链接会自动指向新版。比逐个复制粘贴要高效得多也方便团队共享。4.4 Agent 安全第三方 Skill 的隐藏风险最后说一个很多人忽略的点Agent 的安全问题往往出在 Skill 上。你给 Agent 挂载了一个技能包就相当于给了它一个可以在本机执行任意代码的入口。如果这个 Skill 来自不可靠的仓库里面的脚本可能会读取你的 SSH 密钥、上传文件到远程服务器、或者在后台执行其他操作。所以安装第三方 Skill 之前我建议至少做三件事看 Star 数和近期更新情况冷门且无人维护的仓库谨慎使用。打开SKILL.md和scripts/下的代码重点搜索有没有request、curl、os.system、subprocess、rm -rf这类敏感调用。在隔离目录或虚拟机里先跑一次确认输出行为再放入正式环境。自己写 Skill 的时候也要克制权限范围。脚本能读取指定文件就只读指定文件能用普通用户权限就不要使用 sudo能接受环境变量注入密钥就不要在代码里写死。Agent 的能力越强技能包的权限边界就越要收紧。你在 Skill 上省下的每一份审查功夫都会变成未来某一天的安全隐患。我现在基本上把 Skills 当成一种轻量级插件来维护每个项目自带.claude/skills团队内部也建了共享库。最后分享一个小经验与其追求装很多花哨的 Skills不如先把手头重复性最高的三件事做成三个稳定 Skills比如文档转换、编译构建、数据清洗。等到这几个技能表现稳定了再逐步扩充你会发现 Agent 的可靠性和效率会有质的提升。