最近一段时间AI Agent圈子里的讨论热度几乎全被一个词带起来了skills。刷一下技术社区一边是“superpower skills 安装教程”、“claude code 怎么手动装 GitHub 上的 skills”另一边是“codex 好用的 skills”、“pi agent 官网”不明所以的人大概率会一脸懵skills 到底是个什么东西它和 agent 有什么区别为什么突然所有人都开始折腾技能包我个人的判断是skills 是 Agent 从“能聊天”走向“能干正经活”的那层关键台阶。它可以被理解成一份写给 Agent 的“标准作业包”——里面既写清楚了任务怎么做又塞了完成这个任务需要的脚本、模板、检查清单。Agent 拿到这个包之后不需要你反复教也不用每次重新解释需求直接照着一套成熟流程执行就行。这篇文章我就想用实际动手的视角把 skills 的概念、结构、安装、开发、排查一次性讲透尤其适合正在入门 Agent 开发、或者被 skills 安装和编写问题卡住的人。内容没有太多弯弯绕绕都是可以直接照着操作的实战路径。1. Skills 到底是什么先把它和 Agent、Harness 的关系捋清楚1.1 为什么大家突然都在聊 Skills先说个现象。2025 年之前大家聊 Agent 更多是在聊“框架”——怎么让模型循环调用工具、怎么管理上下文、怎么做规划。可到了最近几个月风向明显变了社区里冒出来一堆“技能库”“技能市场”大家讨论的颗粒度从框架层面下沉到了具体的“技能包”。这种转变的背后其实是一个很现实的问题框架只是骨架真正让 Agent 在某个领域发挥价值的是它掌握多少套高质量的执行方法。举个例子。同样一个 Claude Code你不会任何 skills 的时候让它帮你做前端重构它也能做但大概率是从零开始推理步骤和规范全凭模型当时的状态生成结果很不稳定。可如果你给它装了一个“前端开发 skills”里面写清了组件拆分的标准、样式命名规范、常见重构流程甚至附带一个自动检查脚本那它的输出质量和稳定性会立刻上一个大台阶。这就是 skills 走红的核心原因它把“一次性的聪明”变成了“可复用的标准化能力”。另外各大 Agent 工具从产品层面也在推波助澜。Claude Code 很早就支持在.claude/skills/目录下加载技能包Codex 也有自己的 skills 机制像 opencode 这类开源项目也在跟进类似设计还有 pi agent、hermes agent 这类带图形界面和技能市场的桌面端 Agent让普通用户也能像装 App 一样装技能。基础设施铺好了讨论自然就热了。1.2 Skill、Agent、Harness、Framework 这四个词的区别与联系很多新手容易把“Agent”“Skill”“Harness”“Framework”混在一起我在群里见过不只一个人问“agent 和 skills 到底哪个是哪个”。这里我用一个生活化的类比统一解释一下。Agent 是“干活的人”。它负责感知任务、做规划、调用工具、反思结果是整个系统的执行主体有推理能力也有记忆能力知道自己在干什么、下一步该干什么。Skill 是“这个人掌握的标准作业手册”。它本身不会主动干活但一旦 Agent 判断当前任务匹配某个技能就会把这个技能包里的方法、脚本、规范全部加载出来照着执行。Harness 是“工作台和操作间”。它提供 Agent 运行的环境包括模型接口、工具注册表、上下文窗口管理、安全限制、执行循环。换句话说Harness 决定了 Agent 能跑多稳、能碰哪些工具。Framework 是“搭建工作台的施工图纸”。它是用来构建 Agent 应用的基础库比如 LangChain、CrewAI 这些帮你把模型调用、工具调用、记忆存储这些底层模块组装起来。这四者的关系可以理解成你开发者用 Framework 搭了一个 Harness在 Harness 里跑了一个 Agent然后给 Agent 装了一批 Skills让它能在特定领域干得又快又好。很多时候大家争论“harness 和 agent 的区别”其实就是把运行环境和执行主体搞混了Harness 是舞台Agent 才是演员。1.3 一条人话解释 Skills 的设计动机Skills 的设计动机说到底就一句话把模型每一次都要重新“现想”的东西变成可以直接“查表”的固定资产。模型单次推理再强也是无状态的换一个会话它就忘记了上次你是怎么教它的。而 Skills 把方法论沉淀成了文件让 Agent 在每次面对同类任务时都能稳定复现同样的高质量流程。我刚接触这个思路的时候觉得它有点像后端开发里的“脚手架”或者“代码模板”只不过服务的对象不是人而是 AI。你写一套AI 能反复用而且每个用这个技能的人都能获得差不多的效果。这正是它和普通 Prompt 的核心区别Prompt 指导说话Skill 指导干活它能触达文件系统、能跑脚本、能调用外部工具是真正具备执行力的“技能”。2. Skills 的内部结构从 SKILL.md 到脚本依赖一个技能包是怎么组织的2.1 最简技能包长什么样一个标准的 Skills 技能包本质上就是一个有固定结构的目录。拿目前生态里最通用的规范来说一个技能包里至少要有一个SKILL.md文件。这个文件是技能的“门户”Agent 加载技能时第一眼看到的就是它里面用 YAML frontmatter 写元信息用 Markdown 写具体的执行说明。稍微复杂一点的技能包还会有辅助脚本、模板文件、依赖声明和示例数据。一个最简的技能包目录结构大概是这样的my-skill/ ├── SKILL.md ├── scripts/ │ └── check_format.py ├── templates/ │ └── report_template.md └── requirements.txt不用小看这个结构它其实暗含了一套非常合理的分工SKILL.md负责给 Agent“讲方法”scripts/里的脚本负责把方法变成“可执行的动作”templates/提供标准化的输出底稿requirements.txt则保证脚本运行时有正确的依赖环境。我在实际使用中最看重的原则是入口文件要足够清晰辅助内容宁缺毋滥。如果一个技能包里塞了几十个脚本Agent 光理解这个包的成本就很高反而拖慢任务执行。真正好用的技能往往是“说明精准 脚本可控 输出明确”的轻量组合。2.2 SKILL.md 的写法与 metadata 的作用SKILL.md是整个技能包的核心它的质量基本上决定了这个技能好不好用。先看一个标准的 frontmatter 示例--- name: latex-formatter description: 对 LaTeX 文档执行格式规范检查与自动修复。当用户需要排版、修改摘要、处理公式对齐或统一参考文献格式时使用。 ---name是技能的标识符description则承担着“检索命中”的重任也就是告诉 Agent“什么情况下该用我”。很多人在写 skill 的时候不重视 description随便写一句“这是一个 LaTeX 工具”结果就是 Agent 永远不知道该在什么时候加载它。为什么 description 这么重要原因在于Agent 的技能调用机制本质上是“按描述匹配”。模型拿到一个用户任务后会遍历所有已安装技能的 description评估匹配度命中之后才把整份 SKILL.md 注入上下文。如果你的 description 写得模糊Agent 就会错过这个技能反过来如果 description 里把触发场景、任务特征、常见变体都写清楚命中率就非常高。我个人的经验是写 description 要像写搜索引擎的索引词一样把用户最常用的话术放进去。如果这个技能是处理 LaTeX 排版的就写“当用户要求排版、论文格式调整、公式编号、参考文献格式化时使用”而不是写“这是一个 LaTeX 工具”。模型是语义匹配不是关键词匹配但具体、场景化的描述永远比抽象描述更容易被命中。2.3 辅助脚本、资源文件、依赖声明的协作方式SKILL.md 提供方法论脚本则负责把方法论中“可自动化”的部分变成确定的输出。好的技能设计会把“需要模型判断”和“需要机器执行”两部分做明确切分凡是能做确定性检查的都交给脚本凡是需要理解语义的留给模型推理。举例来说一个 LaTeX 排版技能里检查“代码块有没有闭合”这类问题适合交给脚本判断“这里的图表位置是否美观”则适合交给模型分析。我在开发技能时习惯先把任务拆成“规则检查”和“经验判断”两类然后给前者写脚本给后者在 SKILL.md 里写详细的判断标准和操作指引。依赖声明这块我也踩过坑。技能如果依赖第三方库一定要在包内显式声明最好附上版本号否则换个环境跑直接报错。你装技能的时候Agent 不会帮你检查依赖它只会尝试运行出错了才告诉你。这时候如果技能包里有 requirements.txt排查效率能高很多。2.4 为什么 description 写得好不好直接决定技能能不能被命中这一节值得单独拎出来强调。很多用户说“我装了技能但 Agent 根本不调用”八成问题不在代码而在 SKILL.md 的 description 写得不够好。模型加载技能的原则是“能不用就不用用之前先评估代价”因为每注入一份技能内容都要吃掉宝贵的上下文窗口。所以想提高技能命中率有两个方向一是把 description 写得极度精准把典型触发语句直接列出来二是把 SKILL.md 主体内容写得精炼让 Agent 觉得“加载它不亏”。一个动辄上万字的 SKILL.md就算命中Agent 也会因为上下文开销过大而犹豫是否真正遵守。我一般要求自己SKILL.md 正文控制在 300 行以内能用清单说明的绝不用大段散文能用脚本解决的绝不写冗长的步骤描述。这样技能既容易被命中执行效率也高。3. 从安装到使用用别人做好的 Skills 快速上手3.1 常用 Skills 来源与筛选标准对刚接触 skills 的人来说最快的学习方式不是自己写而是先装一批别人做好的高质量技能看它们怎么设计目录、怎么写说明、怎么组织脚本。目前社区里常见的几个来源我列一下自己的使用感受来源特点适合场景obra/superpowers工程风格浓厚覆盖 TDD、项目管理、代码审查等大而全的技能合集想系统学习技能设计、做软件工程类任务awesome-claude-skills 等汇总仓库收录大量社区技能分类清晰按需检索特定领域技能比如图片生成、前端开发hermes agent 技能商店带有 GUI 的技能市场下载安装一条龙不想折腾命令行的普通用户个人开发者 GitHub 仓库针对特定场景深度优化遇到某个具体痛点比如“华为杯建模比赛要用的 codex skills”筛选标准这件事我吃过亏必须多说两句。不是所有标了“skills”的仓库都值得装我一般用三个维度判断第一看维护活跃度最近一年内有 commit 的才考虑第二看 README 和 SKILL.md 的质量如果作者连自己的技能说明都写不清楚这个技能大概率也不好用第三看脚本复杂度依赖太多、代码太长的技能包往往是为了炫技而不是为了好用。3.2 手动安装 Skills 的标准步骤手动安装 skills 其实不复杂核心逻辑就一句话把技能包目录放到 Agent 能扫描到的 skills 路径下。以目前主流的 Claude Code 为例全局技能放在~/.claude/skills/项目级技能放在.claude/skills/Agent 启动时会自动扫描这些目录。从 GitHub 上手动安装一个技能的完整流程是# 1. 进入 skills 目录 cd ~/.claude/skills # 2. 克隆远程仓库到本地 git clone https://github.com/yourname/some-skill.git # 3. 检查目录结构是否符合规范 ls -la some-skill/ # 确认存在 SKILL.md 和必要的脚本文件 # 4. 重启 Agent让技能被扫描加载装完之后不一定要立刻重启有些框架支持热加载但为了稳妥我建议每次安装或者修改技能后都重启一次会话。项目级技能则要放到当前项目的.claude/skills/目录适合只在这个项目里生效的专用技能避免污染全局环境。如果你用的是带桌面端的工具比如 pi agent 或者 hermes agent安装就更傻瓜化了大部分都内置了一键安装和版本管理。这里有一个重要提醒手动 clone 仓库之后记得看一眼是不是装了多余的文件。有些技能仓库里会有.git目录、示例文件、文档图片这些不会影响功能但会让技能包变得臃肿。我习惯装完顺手清理只保留 SKILL.md、scripts、templates 这些运行时必需的内容。3.3 安装后怎么验证、怎么让 Agent 帮我干活技能安装完最怕的就是“并不知道它到底生效没有”。我的验证方法很简单直接用一个能触发该技能的小任务去试同时开启 Agent 的详细输出模式观察它是否加载了对应的 SKILL.md。比如我给 Agent 装了图片生成相关 skills就可以让它跑一个“帮我生成一张科技风格的 banner 图尺寸是 16:9”。然后通过日志确认它是不是读取了图片生成技能里的提示词模板和工具脚本。如果日志里完全没出现技能文件的路径那说明匹配失败回去改 description 或者换一个更直白的触发说法。技能生效之后日常工作方式会发生一个明显变化不需要再写繁琐的长 Prompt 了。以前让 AI 做图要做很多轮对话去调整提示词装了技能之后你只需要说“按技能里的默认风格给我出一套 AI 漫剧分镜”它就会自己调用技能包里的模板、参数和流程。这种感受是很有冲击力的你会瞬间理解 Skills 为什么是 Agent 实用性提升的关键。3.4 技能装多了怎么办Skills 清理经验装技能这事是有“上瘾期”的看到推荐就装结果一个月下来技能目录里躺了几十个包。然后你就会发现一个尴尬的事实Agent 并没有变得更好用反而变“笨”了。原因我在前面提过——技能越多模型每次做匹配决策时的噪声越大经常性出现“该用的没用上”或者“把不相关技能的内容当成参考”。社区里也有人专门分享过清理技能的方法我自己的做法概括成三步第一步每个月定期过一遍已安装技能列表用不到的直接删第二步把“可能以后用得上”的技能归档到一个单独的备份目录不放进 Agent 的扫描路径第三步同名或功能重叠的技能只保留质量最好的一个比如图片生成技能已经有一个很稳定的就不留三个备选。清理技能不只是为了硬盘空间更重要的是为了降低 Agent 决策的复杂度。真正高频使用的技能一个项目里有三五个完全够用了剩下的都是干扰项。到目前为止“少而精”依然是技能管理最有效的方法论。4. 自己开发 Skills从零做一个 LaTeX 排版技能的全过程4.1 想清楚边界什么任务适合做成 Skill很多人第一次动笔想写技能容易犯一个毛病恨不得把一个领域的所有知识都塞进去。我写第一个技能的时候就是这样立志要做一个“全能前端开发技能”写了大纲发现根本收不住最后只能砍掉重来。这件事给我的教训是技能的核心是“边界”不是“覆盖”。什么任务适合做成技能我的判断标准有三条。第一任务本身有稳定的执行流程而不是那种每次都需要大量创造力的开放式任务第二任务发生频率足够高值得为它沉淀一套方法第三任务中包含可以标准化的检查项或输出模板。用这三条标准来套LaTeX 排版就非常合适——流程稳定、学术写作高频、格式规范可以量化检查。反过来像“帮我想一个产品创意”这种任务就不适合做成技能因为它的价值恰恰在于每次都不一样做成技能反而会限制模型的发挥。把技能用在不该用的地方等于给 Agent 戴上了紧箍咒。4.2 设计技能包目录、元信息、调用流程确定要做 LaTeX 排版技能之后第一步不是写代码而是画清楚这个技能被调用时的工作流程。我的设计思路是这样的先把技能拆解成“可用脚本自动完成的检查”和“需要模型判断和执行的修改”两个层次然后规划调用流程。一个典型的使用场景是用户在聊天里甩过来一个.tex文件说“帮我按期刊模板改一下格式”。技能被触发后应该先运行脚本对源文件做规则检查找出格式问题然后把检查结果给模型由模型根据 SKILL.md 里的排版规范逐个处理最后再跑一次脚本做验证。这个流程把脚本的确定性和模型的灵活性结合在了一起。技能包的目录设计我做了精简latex-format-skill/ ├── SKILL.md ├── scripts/ │ ├── lint_latex.py │ └── fix_common.py └── templates/ └── paper_template.tex元信息部分我把 description 写成了包含大量具体触发场景的版本“当用户要求处理 LaTeX 文档、调整论文格式、统一参考文献格式、修复公式对齐、修改图表标题位置时使用。适用于学术论文、毕业设计、期刊投稿等场景。”写完之后我在心里模拟了各种用户说法确保大部分自然表达都能命中。4.3 写 SKILL.md 的提示词工程技巧SKILL.md 的正文部分本质上是一份写给模型的“标准作业指导书”。它和普通 Prompt 最大的区别是受众不是“通用模型”而是“正在执行任务的 Agent”所以语气要更指令化、结构化。我在写 SKILL.md 正文时会刻意做到以下三点。第一把执行步骤拆成明确的编号列表每一条都以“动词开头”比如“读取文档”“检查摘要格式”“统一参考文献引用格式”模型对这种指令的遵循度远高于模糊描述。第二给出“可接受/不可接受”的对照示例比如“公式编号必须右对齐不可居中在公式下方”“图表标题统一使用 10pt 字号不可加粗”。这些正反例能极大减少模型的自由发挥空间。第三也是最重要的在 SKILL.md 里写清楚“边界”和“兜底策略”。比如“如果发现文档存在无法自动判断的语义问题停下并向用户确认不要擅自修改内容”。没有边界约束的技能非常危险模型可能为了完成目标而大改原文造成不可逆的破坏。我见过有人用排版技能把整篇论文的结构都改乱了就是因为他没在技能说明里限制修改范围。4.4 实现辅助脚本把“描述规范”变成“可执行检查”SKILL.md 负责“讲规范”脚本负责“查规范”。我在开发 LaTeX 技能时写了一个简单的 lint 脚本用来检查文档里的常见格式问题比如是否有多余空行、公式环境是否正确闭合、参考文献条目是否符合格式。这里附一个简化版的核心逻辑#!/usr/bin/env python3 import re import sys def check_tex(path): with open(path, r, encodingutf-8) as f: content f.read() issues [] # 检查未闭合的数学公式环境 math_envs re.findall(r\\(begin|end)\{(equation|align|eqnarray)\}, content) stack [] for kw, env in math_envs: if kw begin: stack.append(env) else: if not stack or stack[-1] ! env: issues.append(f公式环境闭合异常: {env}) else: stack.pop() if stack: issues.append(f存在未闭合的公式环境: {stack}) # 检查图表标题是否包含加粗宏 caption_pattern re.compile(r\\caption\{(.?)\}) for m in caption_pattern.finditer(content): if \\textbf in m.group(1): issues.append(图表标题不应包含加粗文本) return issues if __name__ __main__: issues check_tex(sys.argv[1]) if issues: print(\n.join(issues)) sys.exit(1) print(检查通过)脚本不复杂但它承担了 SKILL.md 无法胜任的“确定性校验”工作。写脚本的时候我给自己定了一条原则脚本只做检查和建议不做自动修改。因为自动修改的风险太高LaTeX 文件的结构复杂性很容易让脚本改出错最佳方案是脚本发现问题模型根据 SKILL.md 的规范进行修改再由脚本复查形成闭环。4.5 测试与迭代先用小任务验证再放真实场景技能写完不是终点测试和迭代才见真功夫。我的习惯是先在一个沙箱目录里放几个测试用的小文件确保脚本逻辑没有问题然后再用一个真实的论文片段做全流程验证。这个阶段特别能发现“规范和现实脱节”的问题——你写在 SKILL.md 里的检查项可能在真实文件里根本不会出现而真实文件里的常见怪癖你的技能却没考虑到。迭代的方法也很简单每次用技能处理完一个真实任务后检查 Agent 的执行日志看看哪里浪费了时间、哪里理解偏了、哪些 user 说法没有命中技能然后针对性修改 SKILL.md 和脚本。技能包是“活”的不是写完就定稿。我那个 LaTeX 技能前后迭代了五六轮才勉强能说在各种论文格式下都表现稳定。这一节最后再多说一句开发技能的过程中最大的收获不是那个技能本身而是你理解了 Agent 的工作机制——它怎么读文件、怎么匹配技能、怎么执行脚本、怎么在上下文中权衡信息。这些理解是任何教程都教不会的。5. 生态速览Pi Agent、Hermes Agent、Codex、Opencode 都在怎么做 Skills5.1 各家 Skills 生态的差异Skills 并不是某一家公司的专利2025 年下半年开始主流 Agent 工具基本都在往“技能化”方向走。但各家实现思路有一定差异我用一个表格对比一下自己实际接触下来的感受工具/平台Skills 实现方式亮点上手门槛Claude Code本地目录.claude/skills/SKILL.md 规范成熟生态最完善文档齐全社区资源丰富低手动 clone 即可Codex内置技能机制支持命令行安装技能包对代码生成类任务优化明显有竞赛社群分享技能中需要熟悉 CLIopencode开源支持类似技能机制灵活可定制适合自己改源码中高需要懂点开发pi agent桌面端 技能市场安装可视化适合普通用户有聚合技能推荐低点按钮即可hermes agent独立 Agent自带中文界面和技能仓库中文场景友好社区模板多低各家都在做技能市场这件事本身就说明了一个趋势Agent 的竞争正从模型能力转向生态丰富度。模型决定 Agent 的“智商天花板”技能市场决定 Agent 的“能力下限”。一个配备了成熟技能市场的 Agent哪怕底层模型稍弱也能通过大量高质量技能弥补短板。5.2 跨平台复用把同一套 Skill 带到不同 Agent我自己最常被问的一个问题是在 Claude Code 里写的技能能不能拿到 Codex 或者别的 Agent 里用答案是可以但有条件。因为主流技能的底层规范都是“SKILL.md 辅助脚本”核心结构一致换平台时只需要重新检查 description 的格式是否符合目标平台的元信息要求以及脚本的依赖在当前环境里是否齐全。举一个实际例子我开发过一个前端代码审查技能核心逻辑是让 Agent 按一套规范检查组件代码并输出审查报告。这个技能在 Claude Code 里表现很好后来我把它复制到 Codex 的 skills 目录只改了个别字段格式和工具调用方式就能直接用了。跨平台复用的收益很明显一份投入多处生效。不过也要注意平台之间的生态差异。Claude Code 的 SKILL.md 里有相当多的写法是围绕 Claude 模型和本地命令行工具设计的换到另一个平台时那些工具可能并不存在。跨平台复用不是说直接复制粘贴而是复用“方法设计”和“脚本逻辑”针对目标平台做一轮适配。5.3 从 Skills 到 Agent 开发学习路线还有一个高频问题是“我想学 agent 开发到底应该从哪里开始”我的回答永远是从学会使用和编写 skills 开始。这条路径可能是目前最平缓的 Agent 入门路线。第一步只当用户装几个成熟技能包理解它们怎么工作。第二步打开技能包目录逐行读别人的 SKILL.md 和脚本分析作者为什么这么设计。第三步尝试改一个现成技能的小功能比如给 LaTeX 技能加一项新的检查规则你会在这个过程中理解技能的运行机制。第四步从零写一个足够小的技能覆盖自己的一个真实需求走完“设计—实现—测试—迭代”全流程。走完这四步你其实就建立了 Agent 开发的大部分基础认知。后面再去学 Agent 框架、记忆机制、评估方法都会顺很多。我在微信群里看到有人问“agent 开发学习路线”下面推荐了一堆框架源码和算法论文我觉得那是对新手的劝退。真正的学习路径应该从给自己写一个用得上的小技能开始先感受到价值再谈深度。6. 高频问题与排查报错、不生效、记忆、安全6.1 Agent execution terminated due to error这类报错怎么查用过 Agent 的人多少都见过agent execution terminated due to error.这类报错很多新手一看到就慌其实这个提示的价值非常有限它只是告诉你“某个环节挂了”但没告诉你哪里挂了。排查的思路应该是从日志入手。我的标准排查流程是这样的先打开 Agent 的详细日志模式找到报错前最后几步动作。如果错误出在技能脚本阶段通常是 Python 依赖缺失、路径不对或者脚本本身有 bug如果错误出在模型调用阶段可能是上下文超限或者上下文内容里混入了非法格式如果错误出在工具调用阶段则需要检查外部工具的权限和连接状态。这张表格可以帮你快速定位常见的执行错误错误表现大概率原因排查动作脚本报 ModuleNotFoundError缺少依赖安装 requirements.txt 里的依赖技能文件找不到路径配错检查技能目录是否为 Agent 扫描范围上下文超限SKILL.md 太长或加载技能过多精简技能内容减少不相关技能权限错误脚本没有执行权限检查文件权限和 Agent 的工作目录6.2 Skill 装好了但 Agent 没有调用怎么排查技能装好却不被调用这个问题的出现频率极高。我在 3.4 里提过原因大概率是 description 匹配不上。更具体的排查思路是先在对话里直接提到技能里写的关键词或场景看 Agent 是否命中如果还是不行就去检查描述里是不是用了太多模型无法理解的内部术语。比如我做过一个图片生成技能description 里一开始写了“使用 ComfyUI 工作流实现图片生成与风格迁移”但用户真正说出来的话是“帮我生成一张图”“画一个赛博朋克风格的概念图”。后来我把 description 改成更接近用户语言的版本命中率立刻高了很多。这个案例可以总结成一个方法把目标用户最可能说的话原样写进 description而不是写你想让用户说的话。此外还要留意一个细节很多 Agent 在加载技能时是有优先级排序的项目级技能往往优先于全局技能。如果你在项目级放了一个同名或相似功能的技能全局的那个就不会被触发。遇到“技能不生效”先检查有没有被更高级别的技能覆盖。6.3 Skills 与 Agent 记忆怎么配合新接触技能的人经常把“记忆”和“技能”混为一谈其实这是两个不同层面的东西。Agent 记忆负责存储“这件事的背景是什么、用户偏好是什么、历史对话里出现过哪些关键信息”技能负责提供“这类任务应该怎么做”。两者不冲突但需要配合。在实际应用中一个 Agent 可以长期记住用户的写作风格偏好然后在执行排版技能时把记忆里的偏好作为附加约束叠加到技能流程里。我平时用 Agent 处理文档时会先确认 Agent 已经掌握了项目背景和用户的格式偏好再触发排版技能这样它产出的结果就同时满足“规范”和“个人化”两个要求。很多 Agent 框架已经在尝试打通这两层比如让技能执行结果写入记忆让下次执行时更贴合上下文。但现阶段我的建议是不要让技能试图承担记忆功能不要在 SKILL.md 里写“你可以查询上次会话的记录”技能的状态应该是无状态的每次执行都从当前的输入和上下文出发。6.4 Agent 与 Skills 的安全边界最后聊一个很多人忽略但极其重要的话题技能的安全边界。因为技能本质上是一段“被模型信任并执行”的代码一旦装了一个恶意或者不靠谱的技能包后果可能比想象中严重。我给自己定了三条安全底线。第一绝不在生产环境里使用来路不明的技能包尤其是那些要执行网络请求、读写敏感目录的脚本使用前必须逐行审查。第二技能脚本的运行权限要做到最小化比如不要在技能里写“删除文件”“全局安装依赖”这类特权操作如果硬要支持必须放在显眼的确认环节。第三定期审计技能目录发现可疑的更新立刻处理。很多新手会问Agent 不是有安全限制吗怎么还会出问题实际上模型的自我保护机制面对“技能内脚本”时并不总是有效的因为模型天然倾向于信任已加载技能的内容。所以技能安全的第一责任人是开发者自己。这也是我在团队里要求所有 skill 代码必须 code review 的原因。Agent 的能力越强技能的安全红线就越要清晰。回到我自己的使用体验我认为 Skills 是 Agent 从“玩具”走向“生产力工具”最关键的一块拼图。刚入坑的时候我也觉得它挺麻烦要写目录、要调 description、要维护脚本。但用习惯之后再回头看那些没有技能加持的 Agent就像看到一个手艺很好的师傅却总是临时找工具能干但永远不够高效。如果你正准备入门 Agent 开发我建议你先别急着啃框架源码挑一个自己日常工作里重复过很多次的小任务动手写一个最简技能包。等这个技能真的帮你省下第一个小时的时候你自然就明白这一切为什么这么设计了。 AI Agent Skills完全指南：从概念、结构到安装开发实战
最近一段时间AI Agent圈子里的讨论热度几乎全被一个词带起来了skills。刷一下技术社区一边是“superpower skills 安装教程”、“claude code 怎么手动装 GitHub 上的 skills”另一边是“codex 好用的 skills”、“pi agent 官网”不明所以的人大概率会一脸懵skills 到底是个什么东西它和 agent 有什么区别为什么突然所有人都开始折腾技能包我个人的判断是skills 是 Agent 从“能聊天”走向“能干正经活”的那层关键台阶。它可以被理解成一份写给 Agent 的“标准作业包”——里面既写清楚了任务怎么做又塞了完成这个任务需要的脚本、模板、检查清单。Agent 拿到这个包之后不需要你反复教也不用每次重新解释需求直接照着一套成熟流程执行就行。这篇文章我就想用实际动手的视角把 skills 的概念、结构、安装、开发、排查一次性讲透尤其适合正在入门 Agent 开发、或者被 skills 安装和编写问题卡住的人。内容没有太多弯弯绕绕都是可以直接照着操作的实战路径。1. Skills 到底是什么先把它和 Agent、Harness 的关系捋清楚1.1 为什么大家突然都在聊 Skills先说个现象。2025 年之前大家聊 Agent 更多是在聊“框架”——怎么让模型循环调用工具、怎么管理上下文、怎么做规划。可到了最近几个月风向明显变了社区里冒出来一堆“技能库”“技能市场”大家讨论的颗粒度从框架层面下沉到了具体的“技能包”。这种转变的背后其实是一个很现实的问题框架只是骨架真正让 Agent 在某个领域发挥价值的是它掌握多少套高质量的执行方法。举个例子。同样一个 Claude Code你不会任何 skills 的时候让它帮你做前端重构它也能做但大概率是从零开始推理步骤和规范全凭模型当时的状态生成结果很不稳定。可如果你给它装了一个“前端开发 skills”里面写清了组件拆分的标准、样式命名规范、常见重构流程甚至附带一个自动检查脚本那它的输出质量和稳定性会立刻上一个大台阶。这就是 skills 走红的核心原因它把“一次性的聪明”变成了“可复用的标准化能力”。另外各大 Agent 工具从产品层面也在推波助澜。Claude Code 很早就支持在.claude/skills/目录下加载技能包Codex 也有自己的 skills 机制像 opencode 这类开源项目也在跟进类似设计还有 pi agent、hermes agent 这类带图形界面和技能市场的桌面端 Agent让普通用户也能像装 App 一样装技能。基础设施铺好了讨论自然就热了。1.2 Skill、Agent、Harness、Framework 这四个词的区别与联系很多新手容易把“Agent”“Skill”“Harness”“Framework”混在一起我在群里见过不只一个人问“agent 和 skills 到底哪个是哪个”。这里我用一个生活化的类比统一解释一下。Agent 是“干活的人”。它负责感知任务、做规划、调用工具、反思结果是整个系统的执行主体有推理能力也有记忆能力知道自己在干什么、下一步该干什么。Skill 是“这个人掌握的标准作业手册”。它本身不会主动干活但一旦 Agent 判断当前任务匹配某个技能就会把这个技能包里的方法、脚本、规范全部加载出来照着执行。Harness 是“工作台和操作间”。它提供 Agent 运行的环境包括模型接口、工具注册表、上下文窗口管理、安全限制、执行循环。换句话说Harness 决定了 Agent 能跑多稳、能碰哪些工具。Framework 是“搭建工作台的施工图纸”。它是用来构建 Agent 应用的基础库比如 LangChain、CrewAI 这些帮你把模型调用、工具调用、记忆存储这些底层模块组装起来。这四者的关系可以理解成你开发者用 Framework 搭了一个 Harness在 Harness 里跑了一个 Agent然后给 Agent 装了一批 Skills让它能在特定领域干得又快又好。很多时候大家争论“harness 和 agent 的区别”其实就是把运行环境和执行主体搞混了Harness 是舞台Agent 才是演员。1.3 一条人话解释 Skills 的设计动机Skills 的设计动机说到底就一句话把模型每一次都要重新“现想”的东西变成可以直接“查表”的固定资产。模型单次推理再强也是无状态的换一个会话它就忘记了上次你是怎么教它的。而 Skills 把方法论沉淀成了文件让 Agent 在每次面对同类任务时都能稳定复现同样的高质量流程。我刚接触这个思路的时候觉得它有点像后端开发里的“脚手架”或者“代码模板”只不过服务的对象不是人而是 AI。你写一套AI 能反复用而且每个用这个技能的人都能获得差不多的效果。这正是它和普通 Prompt 的核心区别Prompt 指导说话Skill 指导干活它能触达文件系统、能跑脚本、能调用外部工具是真正具备执行力的“技能”。2. Skills 的内部结构从 SKILL.md 到脚本依赖一个技能包是怎么组织的2.1 最简技能包长什么样一个标准的 Skills 技能包本质上就是一个有固定结构的目录。拿目前生态里最通用的规范来说一个技能包里至少要有一个SKILL.md文件。这个文件是技能的“门户”Agent 加载技能时第一眼看到的就是它里面用 YAML frontmatter 写元信息用 Markdown 写具体的执行说明。稍微复杂一点的技能包还会有辅助脚本、模板文件、依赖声明和示例数据。一个最简的技能包目录结构大概是这样的my-skill/ ├── SKILL.md ├── scripts/ │ └── check_format.py ├── templates/ │ └── report_template.md └── requirements.txt不用小看这个结构它其实暗含了一套非常合理的分工SKILL.md负责给 Agent“讲方法”scripts/里的脚本负责把方法变成“可执行的动作”templates/提供标准化的输出底稿requirements.txt则保证脚本运行时有正确的依赖环境。我在实际使用中最看重的原则是入口文件要足够清晰辅助内容宁缺毋滥。如果一个技能包里塞了几十个脚本Agent 光理解这个包的成本就很高反而拖慢任务执行。真正好用的技能往往是“说明精准 脚本可控 输出明确”的轻量组合。2.2 SKILL.md 的写法与 metadata 的作用SKILL.md是整个技能包的核心它的质量基本上决定了这个技能好不好用。先看一个标准的 frontmatter 示例--- name: latex-formatter description: 对 LaTeX 文档执行格式规范检查与自动修复。当用户需要排版、修改摘要、处理公式对齐或统一参考文献格式时使用。 ---name是技能的标识符description则承担着“检索命中”的重任也就是告诉 Agent“什么情况下该用我”。很多人在写 skill 的时候不重视 description随便写一句“这是一个 LaTeX 工具”结果就是 Agent 永远不知道该在什么时候加载它。为什么 description 这么重要原因在于Agent 的技能调用机制本质上是“按描述匹配”。模型拿到一个用户任务后会遍历所有已安装技能的 description评估匹配度命中之后才把整份 SKILL.md 注入上下文。如果你的 description 写得模糊Agent 就会错过这个技能反过来如果 description 里把触发场景、任务特征、常见变体都写清楚命中率就非常高。我个人的经验是写 description 要像写搜索引擎的索引词一样把用户最常用的话术放进去。如果这个技能是处理 LaTeX 排版的就写“当用户要求排版、论文格式调整、公式编号、参考文献格式化时使用”而不是写“这是一个 LaTeX 工具”。模型是语义匹配不是关键词匹配但具体、场景化的描述永远比抽象描述更容易被命中。2.3 辅助脚本、资源文件、依赖声明的协作方式SKILL.md 提供方法论脚本则负责把方法论中“可自动化”的部分变成确定的输出。好的技能设计会把“需要模型判断”和“需要机器执行”两部分做明确切分凡是能做确定性检查的都交给脚本凡是需要理解语义的留给模型推理。举例来说一个 LaTeX 排版技能里检查“代码块有没有闭合”这类问题适合交给脚本判断“这里的图表位置是否美观”则适合交给模型分析。我在开发技能时习惯先把任务拆成“规则检查”和“经验判断”两类然后给前者写脚本给后者在 SKILL.md 里写详细的判断标准和操作指引。依赖声明这块我也踩过坑。技能如果依赖第三方库一定要在包内显式声明最好附上版本号否则换个环境跑直接报错。你装技能的时候Agent 不会帮你检查依赖它只会尝试运行出错了才告诉你。这时候如果技能包里有 requirements.txt排查效率能高很多。2.4 为什么 description 写得好不好直接决定技能能不能被命中这一节值得单独拎出来强调。很多用户说“我装了技能但 Agent 根本不调用”八成问题不在代码而在 SKILL.md 的 description 写得不够好。模型加载技能的原则是“能不用就不用用之前先评估代价”因为每注入一份技能内容都要吃掉宝贵的上下文窗口。所以想提高技能命中率有两个方向一是把 description 写得极度精准把典型触发语句直接列出来二是把 SKILL.md 主体内容写得精炼让 Agent 觉得“加载它不亏”。一个动辄上万字的 SKILL.md就算命中Agent 也会因为上下文开销过大而犹豫是否真正遵守。我一般要求自己SKILL.md 正文控制在 300 行以内能用清单说明的绝不用大段散文能用脚本解决的绝不写冗长的步骤描述。这样技能既容易被命中执行效率也高。3. 从安装到使用用别人做好的 Skills 快速上手3.1 常用 Skills 来源与筛选标准对刚接触 skills 的人来说最快的学习方式不是自己写而是先装一批别人做好的高质量技能看它们怎么设计目录、怎么写说明、怎么组织脚本。目前社区里常见的几个来源我列一下自己的使用感受来源特点适合场景obra/superpowers工程风格浓厚覆盖 TDD、项目管理、代码审查等大而全的技能合集想系统学习技能设计、做软件工程类任务awesome-claude-skills 等汇总仓库收录大量社区技能分类清晰按需检索特定领域技能比如图片生成、前端开发hermes agent 技能商店带有 GUI 的技能市场下载安装一条龙不想折腾命令行的普通用户个人开发者 GitHub 仓库针对特定场景深度优化遇到某个具体痛点比如“华为杯建模比赛要用的 codex skills”筛选标准这件事我吃过亏必须多说两句。不是所有标了“skills”的仓库都值得装我一般用三个维度判断第一看维护活跃度最近一年内有 commit 的才考虑第二看 README 和 SKILL.md 的质量如果作者连自己的技能说明都写不清楚这个技能大概率也不好用第三看脚本复杂度依赖太多、代码太长的技能包往往是为了炫技而不是为了好用。3.2 手动安装 Skills 的标准步骤手动安装 skills 其实不复杂核心逻辑就一句话把技能包目录放到 Agent 能扫描到的 skills 路径下。以目前主流的 Claude Code 为例全局技能放在~/.claude/skills/项目级技能放在.claude/skills/Agent 启动时会自动扫描这些目录。从 GitHub 上手动安装一个技能的完整流程是# 1. 进入 skills 目录 cd ~/.claude/skills # 2. 克隆远程仓库到本地 git clone https://github.com/yourname/some-skill.git # 3. 检查目录结构是否符合规范 ls -la some-skill/ # 确认存在 SKILL.md 和必要的脚本文件 # 4. 重启 Agent让技能被扫描加载装完之后不一定要立刻重启有些框架支持热加载但为了稳妥我建议每次安装或者修改技能后都重启一次会话。项目级技能则要放到当前项目的.claude/skills/目录适合只在这个项目里生效的专用技能避免污染全局环境。如果你用的是带桌面端的工具比如 pi agent 或者 hermes agent安装就更傻瓜化了大部分都内置了一键安装和版本管理。这里有一个重要提醒手动 clone 仓库之后记得看一眼是不是装了多余的文件。有些技能仓库里会有.git目录、示例文件、文档图片这些不会影响功能但会让技能包变得臃肿。我习惯装完顺手清理只保留 SKILL.md、scripts、templates 这些运行时必需的内容。3.3 安装后怎么验证、怎么让 Agent 帮我干活技能安装完最怕的就是“并不知道它到底生效没有”。我的验证方法很简单直接用一个能触发该技能的小任务去试同时开启 Agent 的详细输出模式观察它是否加载了对应的 SKILL.md。比如我给 Agent 装了图片生成相关 skills就可以让它跑一个“帮我生成一张科技风格的 banner 图尺寸是 16:9”。然后通过日志确认它是不是读取了图片生成技能里的提示词模板和工具脚本。如果日志里完全没出现技能文件的路径那说明匹配失败回去改 description 或者换一个更直白的触发说法。技能生效之后日常工作方式会发生一个明显变化不需要再写繁琐的长 Prompt 了。以前让 AI 做图要做很多轮对话去调整提示词装了技能之后你只需要说“按技能里的默认风格给我出一套 AI 漫剧分镜”它就会自己调用技能包里的模板、参数和流程。这种感受是很有冲击力的你会瞬间理解 Skills 为什么是 Agent 实用性提升的关键。3.4 技能装多了怎么办Skills 清理经验装技能这事是有“上瘾期”的看到推荐就装结果一个月下来技能目录里躺了几十个包。然后你就会发现一个尴尬的事实Agent 并没有变得更好用反而变“笨”了。原因我在前面提过——技能越多模型每次做匹配决策时的噪声越大经常性出现“该用的没用上”或者“把不相关技能的内容当成参考”。社区里也有人专门分享过清理技能的方法我自己的做法概括成三步第一步每个月定期过一遍已安装技能列表用不到的直接删第二步把“可能以后用得上”的技能归档到一个单独的备份目录不放进 Agent 的扫描路径第三步同名或功能重叠的技能只保留质量最好的一个比如图片生成技能已经有一个很稳定的就不留三个备选。清理技能不只是为了硬盘空间更重要的是为了降低 Agent 决策的复杂度。真正高频使用的技能一个项目里有三五个完全够用了剩下的都是干扰项。到目前为止“少而精”依然是技能管理最有效的方法论。4. 自己开发 Skills从零做一个 LaTeX 排版技能的全过程4.1 想清楚边界什么任务适合做成 Skill很多人第一次动笔想写技能容易犯一个毛病恨不得把一个领域的所有知识都塞进去。我写第一个技能的时候就是这样立志要做一个“全能前端开发技能”写了大纲发现根本收不住最后只能砍掉重来。这件事给我的教训是技能的核心是“边界”不是“覆盖”。什么任务适合做成技能我的判断标准有三条。第一任务本身有稳定的执行流程而不是那种每次都需要大量创造力的开放式任务第二任务发生频率足够高值得为它沉淀一套方法第三任务中包含可以标准化的检查项或输出模板。用这三条标准来套LaTeX 排版就非常合适——流程稳定、学术写作高频、格式规范可以量化检查。反过来像“帮我想一个产品创意”这种任务就不适合做成技能因为它的价值恰恰在于每次都不一样做成技能反而会限制模型的发挥。把技能用在不该用的地方等于给 Agent 戴上了紧箍咒。4.2 设计技能包目录、元信息、调用流程确定要做 LaTeX 排版技能之后第一步不是写代码而是画清楚这个技能被调用时的工作流程。我的设计思路是这样的先把技能拆解成“可用脚本自动完成的检查”和“需要模型判断和执行的修改”两个层次然后规划调用流程。一个典型的使用场景是用户在聊天里甩过来一个.tex文件说“帮我按期刊模板改一下格式”。技能被触发后应该先运行脚本对源文件做规则检查找出格式问题然后把检查结果给模型由模型根据 SKILL.md 里的排版规范逐个处理最后再跑一次脚本做验证。这个流程把脚本的确定性和模型的灵活性结合在了一起。技能包的目录设计我做了精简latex-format-skill/ ├── SKILL.md ├── scripts/ │ ├── lint_latex.py │ └── fix_common.py └── templates/ └── paper_template.tex元信息部分我把 description 写成了包含大量具体触发场景的版本“当用户要求处理 LaTeX 文档、调整论文格式、统一参考文献格式、修复公式对齐、修改图表标题位置时使用。适用于学术论文、毕业设计、期刊投稿等场景。”写完之后我在心里模拟了各种用户说法确保大部分自然表达都能命中。4.3 写 SKILL.md 的提示词工程技巧SKILL.md 的正文部分本质上是一份写给模型的“标准作业指导书”。它和普通 Prompt 最大的区别是受众不是“通用模型”而是“正在执行任务的 Agent”所以语气要更指令化、结构化。我在写 SKILL.md 正文时会刻意做到以下三点。第一把执行步骤拆成明确的编号列表每一条都以“动词开头”比如“读取文档”“检查摘要格式”“统一参考文献引用格式”模型对这种指令的遵循度远高于模糊描述。第二给出“可接受/不可接受”的对照示例比如“公式编号必须右对齐不可居中在公式下方”“图表标题统一使用 10pt 字号不可加粗”。这些正反例能极大减少模型的自由发挥空间。第三也是最重要的在 SKILL.md 里写清楚“边界”和“兜底策略”。比如“如果发现文档存在无法自动判断的语义问题停下并向用户确认不要擅自修改内容”。没有边界约束的技能非常危险模型可能为了完成目标而大改原文造成不可逆的破坏。我见过有人用排版技能把整篇论文的结构都改乱了就是因为他没在技能说明里限制修改范围。4.4 实现辅助脚本把“描述规范”变成“可执行检查”SKILL.md 负责“讲规范”脚本负责“查规范”。我在开发 LaTeX 技能时写了一个简单的 lint 脚本用来检查文档里的常见格式问题比如是否有多余空行、公式环境是否正确闭合、参考文献条目是否符合格式。这里附一个简化版的核心逻辑#!/usr/bin/env python3 import re import sys def check_tex(path): with open(path, r, encodingutf-8) as f: content f.read() issues [] # 检查未闭合的数学公式环境 math_envs re.findall(r\\(begin|end)\{(equation|align|eqnarray)\}, content) stack [] for kw, env in math_envs: if kw begin: stack.append(env) else: if not stack or stack[-1] ! env: issues.append(f公式环境闭合异常: {env}) else: stack.pop() if stack: issues.append(f存在未闭合的公式环境: {stack}) # 检查图表标题是否包含加粗宏 caption_pattern re.compile(r\\caption\{(.?)\}) for m in caption_pattern.finditer(content): if \\textbf in m.group(1): issues.append(图表标题不应包含加粗文本) return issues if __name__ __main__: issues check_tex(sys.argv[1]) if issues: print(\n.join(issues)) sys.exit(1) print(检查通过)脚本不复杂但它承担了 SKILL.md 无法胜任的“确定性校验”工作。写脚本的时候我给自己定了一条原则脚本只做检查和建议不做自动修改。因为自动修改的风险太高LaTeX 文件的结构复杂性很容易让脚本改出错最佳方案是脚本发现问题模型根据 SKILL.md 的规范进行修改再由脚本复查形成闭环。4.5 测试与迭代先用小任务验证再放真实场景技能写完不是终点测试和迭代才见真功夫。我的习惯是先在一个沙箱目录里放几个测试用的小文件确保脚本逻辑没有问题然后再用一个真实的论文片段做全流程验证。这个阶段特别能发现“规范和现实脱节”的问题——你写在 SKILL.md 里的检查项可能在真实文件里根本不会出现而真实文件里的常见怪癖你的技能却没考虑到。迭代的方法也很简单每次用技能处理完一个真实任务后检查 Agent 的执行日志看看哪里浪费了时间、哪里理解偏了、哪些 user 说法没有命中技能然后针对性修改 SKILL.md 和脚本。技能包是“活”的不是写完就定稿。我那个 LaTeX 技能前后迭代了五六轮才勉强能说在各种论文格式下都表现稳定。这一节最后再多说一句开发技能的过程中最大的收获不是那个技能本身而是你理解了 Agent 的工作机制——它怎么读文件、怎么匹配技能、怎么执行脚本、怎么在上下文中权衡信息。这些理解是任何教程都教不会的。5. 生态速览Pi Agent、Hermes Agent、Codex、Opencode 都在怎么做 Skills5.1 各家 Skills 生态的差异Skills 并不是某一家公司的专利2025 年下半年开始主流 Agent 工具基本都在往“技能化”方向走。但各家实现思路有一定差异我用一个表格对比一下自己实际接触下来的感受工具/平台Skills 实现方式亮点上手门槛Claude Code本地目录.claude/skills/SKILL.md 规范成熟生态最完善文档齐全社区资源丰富低手动 clone 即可Codex内置技能机制支持命令行安装技能包对代码生成类任务优化明显有竞赛社群分享技能中需要熟悉 CLIopencode开源支持类似技能机制灵活可定制适合自己改源码中高需要懂点开发pi agent桌面端 技能市场安装可视化适合普通用户有聚合技能推荐低点按钮即可hermes agent独立 Agent自带中文界面和技能仓库中文场景友好社区模板多低各家都在做技能市场这件事本身就说明了一个趋势Agent 的竞争正从模型能力转向生态丰富度。模型决定 Agent 的“智商天花板”技能市场决定 Agent 的“能力下限”。一个配备了成熟技能市场的 Agent哪怕底层模型稍弱也能通过大量高质量技能弥补短板。5.2 跨平台复用把同一套 Skill 带到不同 Agent我自己最常被问的一个问题是在 Claude Code 里写的技能能不能拿到 Codex 或者别的 Agent 里用答案是可以但有条件。因为主流技能的底层规范都是“SKILL.md 辅助脚本”核心结构一致换平台时只需要重新检查 description 的格式是否符合目标平台的元信息要求以及脚本的依赖在当前环境里是否齐全。举一个实际例子我开发过一个前端代码审查技能核心逻辑是让 Agent 按一套规范检查组件代码并输出审查报告。这个技能在 Claude Code 里表现很好后来我把它复制到 Codex 的 skills 目录只改了个别字段格式和工具调用方式就能直接用了。跨平台复用的收益很明显一份投入多处生效。不过也要注意平台之间的生态差异。Claude Code 的 SKILL.md 里有相当多的写法是围绕 Claude 模型和本地命令行工具设计的换到另一个平台时那些工具可能并不存在。跨平台复用不是说直接复制粘贴而是复用“方法设计”和“脚本逻辑”针对目标平台做一轮适配。5.3 从 Skills 到 Agent 开发学习路线还有一个高频问题是“我想学 agent 开发到底应该从哪里开始”我的回答永远是从学会使用和编写 skills 开始。这条路径可能是目前最平缓的 Agent 入门路线。第一步只当用户装几个成熟技能包理解它们怎么工作。第二步打开技能包目录逐行读别人的 SKILL.md 和脚本分析作者为什么这么设计。第三步尝试改一个现成技能的小功能比如给 LaTeX 技能加一项新的检查规则你会在这个过程中理解技能的运行机制。第四步从零写一个足够小的技能覆盖自己的一个真实需求走完“设计—实现—测试—迭代”全流程。走完这四步你其实就建立了 Agent 开发的大部分基础认知。后面再去学 Agent 框架、记忆机制、评估方法都会顺很多。我在微信群里看到有人问“agent 开发学习路线”下面推荐了一堆框架源码和算法论文我觉得那是对新手的劝退。真正的学习路径应该从给自己写一个用得上的小技能开始先感受到价值再谈深度。6. 高频问题与排查报错、不生效、记忆、安全6.1 Agent execution terminated due to error这类报错怎么查用过 Agent 的人多少都见过agent execution terminated due to error.这类报错很多新手一看到就慌其实这个提示的价值非常有限它只是告诉你“某个环节挂了”但没告诉你哪里挂了。排查的思路应该是从日志入手。我的标准排查流程是这样的先打开 Agent 的详细日志模式找到报错前最后几步动作。如果错误出在技能脚本阶段通常是 Python 依赖缺失、路径不对或者脚本本身有 bug如果错误出在模型调用阶段可能是上下文超限或者上下文内容里混入了非法格式如果错误出在工具调用阶段则需要检查外部工具的权限和连接状态。这张表格可以帮你快速定位常见的执行错误错误表现大概率原因排查动作脚本报 ModuleNotFoundError缺少依赖安装 requirements.txt 里的依赖技能文件找不到路径配错检查技能目录是否为 Agent 扫描范围上下文超限SKILL.md 太长或加载技能过多精简技能内容减少不相关技能权限错误脚本没有执行权限检查文件权限和 Agent 的工作目录6.2 Skill 装好了但 Agent 没有调用怎么排查技能装好却不被调用这个问题的出现频率极高。我在 3.4 里提过原因大概率是 description 匹配不上。更具体的排查思路是先在对话里直接提到技能里写的关键词或场景看 Agent 是否命中如果还是不行就去检查描述里是不是用了太多模型无法理解的内部术语。比如我做过一个图片生成技能description 里一开始写了“使用 ComfyUI 工作流实现图片生成与风格迁移”但用户真正说出来的话是“帮我生成一张图”“画一个赛博朋克风格的概念图”。后来我把 description 改成更接近用户语言的版本命中率立刻高了很多。这个案例可以总结成一个方法把目标用户最可能说的话原样写进 description而不是写你想让用户说的话。此外还要留意一个细节很多 Agent 在加载技能时是有优先级排序的项目级技能往往优先于全局技能。如果你在项目级放了一个同名或相似功能的技能全局的那个就不会被触发。遇到“技能不生效”先检查有没有被更高级别的技能覆盖。6.3 Skills 与 Agent 记忆怎么配合新接触技能的人经常把“记忆”和“技能”混为一谈其实这是两个不同层面的东西。Agent 记忆负责存储“这件事的背景是什么、用户偏好是什么、历史对话里出现过哪些关键信息”技能负责提供“这类任务应该怎么做”。两者不冲突但需要配合。在实际应用中一个 Agent 可以长期记住用户的写作风格偏好然后在执行排版技能时把记忆里的偏好作为附加约束叠加到技能流程里。我平时用 Agent 处理文档时会先确认 Agent 已经掌握了项目背景和用户的格式偏好再触发排版技能这样它产出的结果就同时满足“规范”和“个人化”两个要求。很多 Agent 框架已经在尝试打通这两层比如让技能执行结果写入记忆让下次执行时更贴合上下文。但现阶段我的建议是不要让技能试图承担记忆功能不要在 SKILL.md 里写“你可以查询上次会话的记录”技能的状态应该是无状态的每次执行都从当前的输入和上下文出发。6.4 Agent 与 Skills 的安全边界最后聊一个很多人忽略但极其重要的话题技能的安全边界。因为技能本质上是一段“被模型信任并执行”的代码一旦装了一个恶意或者不靠谱的技能包后果可能比想象中严重。我给自己定了三条安全底线。第一绝不在生产环境里使用来路不明的技能包尤其是那些要执行网络请求、读写敏感目录的脚本使用前必须逐行审查。第二技能脚本的运行权限要做到最小化比如不要在技能里写“删除文件”“全局安装依赖”这类特权操作如果硬要支持必须放在显眼的确认环节。第三定期审计技能目录发现可疑的更新立刻处理。很多新手会问Agent 不是有安全限制吗怎么还会出问题实际上模型的自我保护机制面对“技能内脚本”时并不总是有效的因为模型天然倾向于信任已加载技能的内容。所以技能安全的第一责任人是开发者自己。这也是我在团队里要求所有 skill 代码必须 code review 的原因。Agent 的能力越强技能的安全红线就越要清晰。回到我自己的使用体验我认为 Skills 是 Agent 从“玩具”走向“生产力工具”最关键的一块拼图。刚入坑的时候我也觉得它挺麻烦要写目录、要调 description、要维护脚本。但用习惯之后再回头看那些没有技能加持的 Agent就像看到一个手艺很好的师傅却总是临时找工具能干但永远不够高效。如果你正准备入门 Agent 开发我建议你先别急着啃框架源码挑一个自己日常工作里重复过很多次的小任务动手写一个最简技能包。等这个技能真的帮你省下第一个小时的时候你自然就明白这一切为什么这么设计了。