企业官网建设流程全解析

最近两个月，我在Agent开发上花的时间比过去一年都多。倒不是因为模型本身变强了多少，而是因为“skills”这个概念突然把整条开发链路盘活了。做Agent的同行应该都有同感：模型推理能力再强，没有一套清晰可复用的技能体系，它也只能在通用对话里打转，一落到具体项目就各种拉胯。GitHub上冒出来一堆superpower skills、Claude Code skills、Codex skills仓库，Pi Agent桌面端也把“技能”做成了核心入口，连数学建模比赛的同学都在问有没有好用的Codex skill。这篇文章就把我这段时间折腾agent skills的经验整理出来，从概念拆解到安装使用，从自己写一个skill到排坑避雷，一次性讲清楚。

1. Skills到底是什么，为什么Agent突然离不开它

1.1 先看懂Agent的工作方式：模型不是万能的

要理解skills，先得说清楚Agent的工作循环。一个Agent本质上就是“模型出决策、工具去执行、结果再喂回来”的循环，业内常说的ReAct模式（Reason + Act）就是干这个的：模型根据当前状态想一想，然后调用工具、读取结果，再继续想，直到任务完成。

这个循环里最容易出问题的环节，不是模型的“想”，而是“怎么把想法变成规范动作”。比如你让Claude Code写一份中文LaTeX论文，模型确实知道LaTeX是什么，但它不知道你的编译链是XeLaTeX、不知道参考文献要用biblatex还是bibtex、不知道学校模板里字号和页边距的硬性要求。你每次都在prompt里长篇大论地交代这些规则，不仅费token，而且模型状态稍微一飘就会漏掉关键约束。

Skills就是来解决这个问题的。它把“在特定场景下应该怎么做”的完整方法，从对话提示词里抽出来，变成一份Agent可以稳定读取和执行的“操作手册”。GitHub上热度很高的pi agent、hermes agent这类项目，核心思路都是给Agent预装一组这样的技能，让它上岗前就“会干活”，而不是等用户现场教。

这里还要顺手澄清两个经常被问混的概念：skill和agent的区别，以及harness和agent的区别。Agent是干活的主体，它负责理解任务、拆解步骤、调度工具；Skill是Agent可以调用的“干法”，相当于岗位说明书里的一节操作规范。而Harness是承载Agent运行的框架外壳，负责管理上下文、工具注册、权限控制这些底层机制。你可以这样类比：Agent是厨师，Skill是菜谱，Harness是厨房。厨师要靠菜谱才知道怎么做菜，但必须在厨房里才能开火。

1.2 Skill不是插件，而是一套“操作手册”

很多人第一次接触skills，容易把它理解成传统软件里的“插件”——以为装上之后就多了一个功能按钮。实际上完全不是。一个skill的核心，通常是一个名为SKILL.md的Markdown文件，里面用结构化语言写清楚：这个技能什么时候用、前置条件是什么、执行步骤是什么、如何验证结果是否正确。

拿一个标准的latex排版skill举例，它的文件头会长这样：

--- name: latex-report description: 使用XeLaTeX排版中文论文。适用于需要生成PDF格式论文、报告的场景。 --- ## 使用前提 - 系统已安装TeX Live或MacTeX - 需要编译的主文件为report.tex ## 执行步骤 1. 检查report.tex是否存在，若不存在则终止 2. 运行 xelatex -interaction=nonstopmode report.tex 3. 检查日志文件是否报错，若有错误则根据报错修正 4. 重复编译两次，确保参考文献和目录正确 5. 确认生成的PDF页数在预期范围内

看到没有，这就是一份给Agent看的“交接文档”。它不需要解释LaTeX是什么、为什么要用XeLaTeX，它只需要告诉模型：遇到这个场景，按这几步走，每一步可验证，做完怎么检查。

这种设计有三个显而易见的好处。第一是省token，规则不再重复塞进对话里，Agent按需读取Skill文件就行。第二是可控，收敛了模型在执行过程中的自由发挥空间，减少“跑偏”的概率。第三是可复用，同一个Skill可以在不同项目、不同Agent之间迁移，写一次到处用。

2. 主流生态盘点：有哪些Skills值得装，怎么装

2.1 Claude Code Skills：起步早、生态最全

目前Skills生态最成熟的，当属Claude Code。原因很简单：Claude Code是最早把skills做成正式功能的终端Agent工具之一，社区沉淀了大量可直接下载的skills包，安装路径也非常规整。

以Claude Code Skills为例，安装目录一般是你用户目录下的隐藏文件夹：

# 创建一个skill的标准目录结构 mkdir -p ~/.claude/skills/my-skill # 核心文件必须叫SKILL.md touch ~/.claude/skills/my-skill/SKILL.md

社区里最出名的要数superpower skills大礼包，它把大量常用技能打包成一个仓库，cloning下来之后直接放进skills目录就能用。我实测过里面包含的代码审查、Git操作、文档生成等技能，识别准确率确实不错。另外有个叫tibo的开发者分享过一套清理skills的方法，核心思路就是“定期删掉一个月没被动用过的技能”，避免技能目录越来越臃肿，这个我后面详细说。

安装第三方skills时，我强烈建议你先看一眼仓库更新时间。那些两年没动的老旧仓库，里面的skill文件往往还停留在早期格式，和当前版本的Agent工具对不上，装上去报错的概率非常高。

2.2 Codex、OpenCode与Pi Agent的Skills玩法

Claude Code在skill生态上跑得快，但其他Agent工具也都在快速跟进。OpenAI的Codex提供了skills能力，你可以把常用的开发流程（代码审查规范、测试用例生成方法、Git提交信息格式）写成skill文件，Codex在执行任务时会自动识别并应用。安装逻辑和Claude Code大同小异，基本都是把skill放到指定目录，然后在Agent配置里声明启用。

OpenCode作为开源Agent终端工具，对skills的支持也很积极，社区维护了不少实用的opencode skills源。Pi Agent把技能做成了桌面端入口，界面上直接能看到已安装技能列表，点开就是对应的操作面板，对不熟悉命令行的新手友好很多。还有hermes agent，它主打的是可编程执行，skill的粒度更细，适合做复杂任务流编排。

我个人的实验结论是：不同工具对skill格式的解析细节有差异，比如frontmatter里必填字段、是否支持子目录引用等，但核心逻辑是完全一致的——都是“SKILL.md文件 + 附加参考文件”的目录结构。所以你写好一份合格的SKILL.md，迁移成本其实非常低。

2.3 从哪找靠谱的Skills源

现在找skills的地方不少，但质量鱼龙混杂。我常用的几个来源：

判断一个skill是否值得装，我有一套自己的标准。首先看更新频率，三个月内有commit的优先；其次看SKILL.md的写法，真正好的skill会写清楚适用条件、边界和验证方式，而不是含糊的“帮助用户完成任务”；最后看引用量，如果README里敢放其它项目的测试结果，说明作者真的有在维护场景兼容性。

3. 自己动手写一个Skill：从需求到落地

3.1 好Skill的三要素：场景窄、步骤明、校验强

很多初次写skill的人容易犯一个毛病：想把一个skill写得“万能”。比如写一个“代码生成skill”，什么语言都想覆盖，结果模型读完之后根本不知道现在到底该干什么，等于没写。

我做了大半年skill开发，总结下来好skill有三个硬性标准。

第一，场景要窄。一个skill最好只解决一类具体问题。“帮用户写Python代码”不是好场景，“生成符合PEP8规范的Python数据处理脚本并完成单元测试”才是。场景越窄，写法越具体，模型执行越稳定。

第二，步骤要明。Skill里的每一步都应该是可执行的描述，而不是泛泛的提醒。比如“整理好代码格式”这种表述就太模糊，应该写成“在提交前运行black --check .，若格式检查失败则先运行black .自动格式化”。

第三，校验要强。这是最容易被忽略的。一个好的skill，要告诉模型“怎么判断自己做成功”了。没有校验环节的skill，Agent做完就完事，出了错也不会发现。以图片生成为例，校验环节就是检查输出文件是否存在、文件大小是否大于0、图片分辨率是否符合预期。

3.2 手把手写一个“图片生成”Skill

这里我以“图片生成skill”为例，带大家一步步写出来。这类skill在素材创作、海报制作场景非常常用，也是热搜里问得比较多的方向。

先看目录结构：

my-image-skill/ ├── SKILL.md └── references/ └── prompt-templates.md

再看SKILL.md的内容：

--- name: image-generation description: 根据需求生成高质量图片。适用于海报制作、插画生成、产品配图等场景。 --- ## 适用条件 - 用户需要生成一张新图片 - 用户描述的图片风格、主题清晰可执行 ## 执行步骤 1. 解析用户需求，提取图片主题、风格、尺寸、配色倾向 2. 在references/prompt-templates.md中选择合适的提示词模板 3. 参考模板和用户需求，组装完整英文提示词 4. 调用图片生成工具（如DALL-E、Stable Diffusion API）提交任务 5. 检查返回结果，确认图片下载成功后，将图片路径返回给用户 6. 如果生成失败，调整提示词中主体描述，最多重试2次 ## 校验方式 - 生成的图片文件存在且字节数大于0 - 图片尺寸与用户要求一致 - 图片主体内容与用户主题匹配，若明显不符，需要重新生成

关键点在于“提示词模板”这个引用文件。图片生成任务里，提示词写得好不好直接决定结果质量。我把常用风格、构图方式、负面提示词这些沉淀在单独的模板文件里，让Agent不需要每次重新“发明”提示词，直接参考现成套路组装，出图成功率会高很多。

3.3 本地调试与评估（Evals）

写完一个skill，别急着拿去生产环境用，先在本地跑一轮调试。调试的核心思路是准备几组典型的测试用例，让Agent在受控环境里执行，看输出是否符合预期。这个过程业内通常叫Evals，也就是评估测试集。

拿图片生成skill举例，我会准备三组用例：一组是“生成一张科技感海报，主色调蓝色”，一组是“生成一张产品配图，产品是无线耳机”，还有一组是模糊需求“生成一张好看的图”。前两组验证正常场景，第三组验证边界情况——模糊需求应该触发技能里的“追问澄清”逻辑，而不是硬着头皮生成。

调试过程中最常遇到的一个报错就是agent execution terminated due to error。出现这个提示，我第一反应是去看Skill文件的路径有没有对、依赖的工具是否在环境中正常注册。这次排查经历后面细讲。反正记住一个原则：先检查环境，再检查skill内容。八成以上“不生效”的问题，都不是skill写错了，而是环境没接上。

4. 实战避坑：我用了大半年Skills的教训

4.1 装了Skills没生效，问题出在哪

Skills不生效，是我在社区答疑时被问到最多的问题。归纳起来，基本跳不出这四类原因。

第一类，目录结构不对。有些工具要求skill必须放在指定的skills根目录下，且每个skill一个独立子目录，子目录里必须有一个SKILL.md文件。你如果直接把多个个skill文件平铺在一个文件夹里，Agent扫描时无法识别，自然不生效。

第二类，命名问题。SKILL.md里frontmatter的name字段，最好和目录名保持一致。我有一次把name写成“image-making”，目录名却是“image-gen”，结果Agent在能力匹配时经常找不到正确的skill。

第三类，frontmatter格式错误。description字段写得太长、YAML解析错误、字段缺失，都会导致skill被静默跳过。这类错误之所以难排查，是因为Agent不会给你报错，只是看起来“没反应”。

第四类，权限问题。尤其是在Linux服务器上部署Agent时，如果SKILL.md文件没有读权限，Agent会发现文件但读不了。用chmod命令扫一遍权限，这些问题一分钟就搞定。

4.2 别让Skills变成“毒药”

安全这一节，我必须单独拎出来讲。Skills机制给Agent带来的能力提升是巨大的，但同时也引入了一个新的攻击面：恶意skills。

什么样叫恶意skills？我曾经在一个“热门skill源”里下载过一份清理工具类的skill，乍一看SKILL.md写得很规范，但仔细翻它的执行步骤，里面藏了一个命令：把当前目录下的所有文件打包上传到某个远程服务器。这种命令人眼扫一遍可能发现不了，但一旦Agent执行起来，数据泄露就是分分钟的事。

所以我对第三方skills的态度是：信任但验证。安装前必须做两件事。第一，通读SKILL.md全文，重点看命令部分有没有看不懂的操作；第二，在隔离环境里先跑一遍，确认行为完全可控再进入正式环境。

另外，给Agent配置权限时要遵循最小权限原则。Agent能跑的shell命令、能访问的文件目录、能调用的API，都按需开放。不要因为“懒”就给Agent开一个全权账号，那是给未来埋雷。

4.3 不是越多越好：我的推荐清单与清理方法

Skills装多了，你会发现一个反直觉的现象：越多的skills，Agent的表现可能越差。因为Agent在决策时要读的“手册”变多了，反而不知道该用哪一个。而且目录里堆了几十个skill之后，扫描和匹配的时间也会变长。

我现在常用的skills不超过十五个。这里分享一份个人推荐清单，只列我实测下来高频且稳定的：