企业官网建设流程全解析

1. 为什么"Skills"突然成了Agent开发圈的高频词

最近无论在哪个Agent交流群还是技术社区，你都会发现"Skills"出现的频率高得吓人。从Claude Code、Codex到各种新冒出来的Agent框架，大家讨论的话题从"今天又调通了哪个API"变成了"这个Skills怎么装""那个Skills好不好用"。我自己的感觉是，这轮Agent开发的范式正在经历一次明显的转向，而Skills恰好站在了这次转向的中心。

先说说最核心的观察。过去一年里，大家玩Agent的方式基本是写System Prompt、堆上下文、不断调优few-shot示例。这种方式最大的问题是：每换一个项目，所有积累全部作废；每换一个Agent框架，心智模型又要重来一遍。而Skills这套设计带来的变化是——把一次性的提示词工程变成可复用的能力包。一个Skills装好之后，你在Claude Code里能用，在Codex里能装，在别的兼容框架里也能跑，就像给Agent塞进了一个独立的能力模块。

另一个让人明显感受到变化的是：skills这个词已经不再只是Anthropic文档里的一个技术概念，而是变成了一个生态现象。你看这些热搜词里，有"superpower skills 安装""codex好用的skills""结构图skills""图片生成skills安装包""怎么做一个latex排版skills"，这说明大家已经不满足于"知道"这个概念，而是真的想上手用、想自己造。有人甚至把Skills比作是Agent时代的"插件市场"——早期是浏览器插件，后来是VS Code插件，现在轮到了Agent Skills。

更值得注意的是，很多人在搜"harness和agent区别""skill和agent的区别"，这说明大家在使用这些工具时产生了明显的概念混淆。说实话这不能怪使用者，因为不同的框架对同一套概念往往起了不同的名字，有的叫Skill、有的叫Command、有的叫Capability，底层逻辑相似但边界并不统一。所以才有了这篇文章的动机：我想把Skills这摊事从头到尾捋一遍——它到底是什么，怎么装，怎么用，怎么自己写一个，以及有哪些坑我替你先踩过了。

如果你现在是这么几类人，这篇文章应该会对你有用：

• 想给Claude Code、Codex这类编码Agent装上各种实用Skills的开发者；
• 在纠结Agent、Harness、Skill这些概念边界，想搞清楚架构选型的人；
• 想自己开发一个Skills（不管是为了LaTeX排版、画结构图、还是更垂直的生产技能）并发布给别人用的人；
• 以及单纯好奇"Skills凭什么这么火"的旁观者。

我会尽量把每个环节都讲透，从概念到实操，从安装到调试，最后还附上一些我实际使用中积累的避坑经验。

2. Skill、Agent、Harness：这三个概念先别混着用

你如果去翻论坛，会发现一大批"求助帖"其实都是概念没对齐导致的。所以我想先花一整节把几个基础概念捋清楚。这不是学院派较真，而是因为你如果没搞懂它们各自的职责边界，后面做架构设计、写Skills、排查问题的时候会非常痛苦。

2.1 三者各自的职责边界

先给一个最朴素的定义：

• Agent：负责"决定做什么"的主体。它接收用户的目标，拆解任务，调用不同的工具，最后给用户交付结果。你可以把它理解成一个大模型驱动的"大脑"。
• Harness：Agent运行时的"外壳"或"脚手架"。它负责模型的循环调度、工具调用的分发、上下文的组织、指令的执行边界。通俗地说，Harness决定了Agent怎么"活着"——用什么规则跑、每轮循环能调用什么、上下文满了怎么办。
• Skill：Agent可以学会/加载的"特定能力单元"。一个Skill通常包含使用说明、参考知识和可执行的代码/脚本，是Agent在某类具体任务上的"业务能力"。

这三个概念对应到实际工程里，就像是一个"员工、工位、工具箱"的关系：Agent是员工，负责判断该干什么；Harness是工位，规定了工作流程和能接触的资源边界；Skill是放在手边的工具箱，解决具体问题的时候打开对应的那个就好。

2.2 用一张表和几个例子说清边界

为了更直观，我做了一个对比表：

很多人混淆Skill和Agent，其实是因为一些框架把Skill做得太重、看起来像个"小Agent"。比如说有些Agent框架允许你在一个Skill里嵌套多步决策和工具调用，这时候Skill的行为确实已经接近Agent了。但有个关键差异仍然是清晰的：Agent站在"用户目标"这一侧，Skill站在"任务能力"这一侧。一个LaTeX排版Skills，它不需要判断用户今天该干什么，它只负责在用户决定要写论文、做简历、排报告的时候，把排版这件事做得又快又好。

2.3 为什么这个概念搞不清楚会直接影响开发

我见过不止一个项目团队在讨论"要不要把某个功能做成一个Skill"的时候吵起来，最后发现争论的本质是大家对于Skill和Agent的粒度理解不一致。把决策粒度放进了Skills里，就会导致你根本没法复用——因为Skill一旦承担了"决策"职责，它的输入输出就必然绑定到具体的业务场景，换个项目就用不了了。

反过来说，把能力粒度全部塞进Agent（System Prompt）里，又会让主流程变得臃肿不堪——每加一个能力都要动主Prompt，上下文窗口的压力、调试的复杂度都会跟着涨。

正确的做法是：决策逻辑尽量留在Agent（或Harness）层，业务能力放进Skills里。这样Agent保持轻量，能力自由组合。你写一个"结构图Skills"，既能配给Claude Code用，也能在别的兼容框架里复用，这就是把概念边界搞清楚的直接收益。

3. 主流生态里的Skills：Claude Code、Codex、Pi Agent、Hermes一网打尽

讲完概念，接下来该上手了。目前市面上的Agent工具已经出现了一批成熟的Skills生态，不同框架的实现思路和安装方式各有差异。这一节我会按工具逐个拆解，覆盖最主流的几个，让你能快速判断"我的环境适合用哪个生态的Skills"。

3.1 Claude Code：Skills的成熟蓝本

Claude Code是Anthropic推出的命令行编码Agent，也是目前对Skills支持最完善的工具之一。它的Skills存放在~/.claude/skills/目录下，每个Skill是一个独立目录，里面包含一个核心的SKILL.md文件，以及可选的脚本和资源文件。

安装方式非常直接：把skills目录克隆或复制到~/.claude/skills/下面，重新启动Claude Code，它就能通过SKILL.md里的描述自动识别和调用。如果想手动指定，也可以直接在对话里说"用xx skill来做这件事"。

社区里最受欢迎的Claude Code skills列表每隔几周就会换一波，但我观察下来，有几类长期稳定：

• 代码重构类：比如"agent legacy modernizer"这种，专门把老项目逐步现代化，降低大规模迁移的心智负担；
• 文档排版类：LaTeX排版、Markdown规范化、报告生成，这类Skills特别适合写论文和做技术文档的人；
• 画图与图表类：结构图Skills、架构图生成、流程图绘制，这类通常结合SVG或Mermaid实现。

3.2 Codex：OpenAI生态的Skills路线

OpenAI的Codex也在走类似路线。Codex Skills的安装方式和Claude Code略有不同，通常是把skills放在Codex指定的配置目录下。安装完以后，Codex会自动发现这些Skills并在合适的时候启用。社区里很多"codex好用的skills"推荐帖，顶在榜首的多半是跟测试生成、代码审查、正则表达式生成相关的技能——这也符合OpenAI系工具在编程场景里更偏"生成-验证"循环的调性。

有一点值得注意：Codex对Skills的描述质量非常敏感。如果你的Skills描述写得很模糊，Codex经常不会自动触发。我在后面讲"自己写Skill"的时候会专门说这个 description 的写法，那几乎是决定一个Skill成败的最关键因素。

3.3 Pi Agent：桌面端的新玩家

Pi Agent最近热度上升很快，因为它有桌面端应用，交互体验比纯命令行的Agent友好太多。很多人搜"pi agent桌面端"其实就是想试试在GUI环境里跑Agent和Skills。Pi Agent对Skills的抽象叫做"能力插件"，安装时可以通过它的应用内市场搜索，也可以手动导入本地目录。

实测下来，Pi Agent的优势是图形化的管理界面，你能清楚地看到当前加载了哪些Skills、哪些没有被触发、触发次数是多少。这个对"想搞清楚Skill到底有没有被调用"的新手来说非常实用。

3.4 Hermes Agent与Agentscope：开源框架里的参考实现

如果你想从框架层面理解Skills的底层实现，Hermes Agent是个挺好的参考项目。它完全开源，代码里可以清晰地看到：Skills是如何被解析进System Prompt的、Skill目录里的文件结构是什么、Skill执行时的隔离边界在哪。对想二次开发或自研Agent的人来说，读一遍Hermes的skills相关源码，比看文档有用得多。

另外一个值得注意的是Agentscope，它里头有个skills demo，把多Agent协作和Skill组合的用法演示得非常明白。它特别适合做"多个Skill按流程组合"的场景——比如先用"数据分析Skill"处理数据，再用"结构图Skill"把结果画出来。

3.5 Superpower Skills：社区热度最高的Skill合集

我不想用太多篇幅讲某一个具体资料包，但"superpower skills"确实是搜索热度极高的一个词。它本质上是一个社区整理的Skills集合，把很多常用能力打包成了一个仓库，用户可以一键安装多组Skills。

实用性上，我建议不要"全家桶式"安装。装一堆用不上的Skills反而会让Agent的调用决策变慢、变混乱——因为每次触发判断都要把所有Skills的description过一遍，Skills越多，误触发概率也越高。最好的做法是：装三五个你自己真实高频使用的，用一阵子，觉得不够再加。

4. 动手写一个自己的Skills：以LaTeX排版Skills为例

前面讲的都是怎么"消费"别人的Skills，但真正好玩的是自己写一个。这一节我以一个完整的"LaTeX排版Skills"为例，把从目录结构到核心文件编写、再到测试和迭代的整个过程过一遍。

4.1 Skill的基本目录结构与文件作用

一个标准的Skills目录一般长这样：

latex-typesetting-skill/ ├── SKILL.md ├── scripts/ │ ├── compile_latex.py │ └── extract_metadata.py ├── references/ │ ├── template.tex │ └── package_map.md └── assets/ └── example_output.pdf

各文件职责很清晰：

• SKILL.md：Skills的"身份证"，里面有YAML格式的元信息（name、description），以及给Agent看的完整使用说明。这是Agent决定"要不要用这个Skill""怎么用这个Skill"的主要依据。
• scripts/：可执行的脚本目录。Skill不是光靠文本知识就能办成所有事的，真正的高价值能力往往体现为脚本——比如编译LaTeX、批量处理图片、生成SVG结构图。
• references/：参考资料。注意这里不是给人类看的文档，而是给LLM看的"短时记忆补充"——当Agent需要某类细节时，它能在这个目录里找到对应参考。
• assets/：输出物或模板资源。

4.2 SKILL.md 的写法：触发、步骤与知识分离

先看一个精简但完整的SKILL.md例子（只展示核心结构，YAML头略作简化）：

--- name: latex-typesetting description: 使用XeLaTeX/LaTeX进行文档排版。适用于用户需要生成PDF论文、简历、技术报告、学位论文等场景。当检测到用户提到"排版"、"LaTeX"、"论文格式"、"简历PDF"等关键词时自动触发。 --- # LaTeX排版助手 ## 前置条件 - 确保环境中已安装 TeX Live 或 MacTeX - 需要编译时，优先使用 scripts/compile_latex.py 脚本 ## 工作流程 1. 从用户输入中提取排版意图（论文/简历/报告）和必要元信息 2. 查询 references/template.tex 选取最接近的模板 3. 填充正文内容，调整样式参数 4. 调用 scripts/compile_latex.py 编译生成PDF 5. 将PDF路径返回给用户，并附上编译日志的摘要 ## 注意事项 - 中文排版必须用 XeLaTeX，并引入 ctex 宏包 - ……

这里的核心有两点：description 负责"触发判断"，正文部分负责"执行步骤"。Anthropic的官方设计里，SKILL.md应该只描述流程和边界，不塞大段样例——比如不要把一份完整的LaTeX模板全文写进SKILL.md，而是放在references里，需要时按路径去读。这能显著减少上下文占用。

4.3 为什么要单独写一个编译脚本

很多人会问：直接用自然语言告诉Agent怎么在终端编译不就行了？实测下来不行。LaTeX编译有一个很头疼的特性——要跑两遍甚至三遍（第一遍生成aux，第二遍解析交叉引用，第三遍确保目录稳定），而且中途报错的位置信息非常反直觉。如果靠模型临场发挥，经常在"该重跑一遍"的时候没跑，或者一遇到警告就误判。

所以我在Skill里加了一个compile_latex.py脚本，固定执行"xelatex -> xelatex -> 选择性再跑一遍"的编译链，在脚本层面就解决编译重数问题。同时捕获错误日志里的关键行，过滤掉无用警告。这样Agent拿到手的编译结果永远是"已确认稳定后再生成的PDF"，而不是它自己猜着跑的产物。

$ python scripts/compile_latex.py main.tex [INFO] 第一次编译完成 [INFO] 检测到交叉引用变化，重新编译 [INFO] 交叉引用已稳定 [INFO] 输出 PDF: build/main.pdf

写这个脚本有一个额外好处：Skill的调试和回归变得非常简单——换了新的模板、修改了中文字体配置，只要跑一遍脚本看几个样例输入，就能确认改动没有破坏原有功能，完全不需要依赖Agent二次临场发挥。

4.4 接一个"图片生成Skills"时的高频雷区

顺着LaTeX这个案例，第二个常见的需求是"图片生成Skills"。很多人以为图片生成Skills就是给Agent一个"画图提示词模板"，但实际并非如此。你去看那些"图片生成skills安装包"下载量高的，几乎都是通过程序化手段生成图片，而不是调用外部图像生成模型。

目前主流方案有几种：

1. SVG生成：让Agent直接生成SVG代码，再用渲染脚本转成PNG/SVG文件。适合画架构图、流程图、图标，因为SVG是文本，LLM生成它的掌控度很高。
2. Mermaid中转：Agent输出Mermaid语法，通过mermaid-cli渲染成图。适合时序图、流程图、状态机图。需要提醒的是，这依赖Node环境和Puppeteer，安装时会遇到大量国内镜像问题，最好提前配好。
3. HTML转图片：先让Agent生成一张HTML页面（布局可控性最强），然后用无头浏览器截图。适合生成社交媒体卡片、海报、简历预览这类"页面型图片"。

我实测下来最稳的是SVG方案。原因很简单：它对环境依赖最小、渲染结果确定性最高，而且生成的图片可以被后续步骤继续编辑。缺点是LLM对复杂SVG路径的理解偶尔会出错，所以脚本里最好加一步"打开SVG检查尺寸和文本溢出"的逻辑，或者至少在输出前用正则做一次基础校验。

因为这一类Skill和"结构图Skills"高度重叠，所以如果你看到有人推荐结构图Skills，大概率底层走的也是上面三种方案之一。

4.5 测试Skill：比你想的更讲究

Skills写完之后，测试不能只靠"和Agent聊一句看看它调不调用"。更靠谱的做法是直接看日志：几乎所有Agent框架都会打印"当前步骤调用了哪个Skill""Skill用了哪些文件""走了哪个分支"。拿Claude Code举例，用--verbose或--log开启详细日志之后，你能看到系统在每一轮都评估了哪些Skills以及为什么选了这个Skill。如果它没触发你的新Skill，多半是description写得不对。

另一个更系统的方法是把Skill丢进Agent Evals里跑。搜索词里"skills怎么测评"对应的就是这个问题。做法很简单：给Skill准备一组真实的高质量输入（比如20份不同类型的排版要求），预期输出是"生成了合法PDF、内容完整性达90%以上"，然后批量跑一遍，统计成功率。这个流程虽然不是必须做，但如果你想发布一个给别人用的Skills，强烈建议要做。我自己见过太多"作者自认为很好用、别人一装就废"的Skills，几乎都栽在测试样本太少、太单一这同一个坑上。

5. 安装和使用Skills的几个隐藏大坑

前三节偏"正面建设"，这一节我想换个角度，聊聊那些我实际踩过、以及看群里人反复踩的坑。安装一个Skills看起来只是"复制文件夹到指定目录"，但真正跑起来之后，问题往往出在你想象不到的地方。

5.1 别把"提示词碎片"当成Skills装进系统

现在社区里冒出来很多所谓"skills"，点开一看，其实就是一段Markdown提示词。不是说提示词没用，而是提示词与Skills的差别在于"可执行性"。一个真正的Skills应该有三个组成部分：触发机制（description）、知识或指令（markdown正文）、执行能力（脚本或命令）。如果没有第三部分，这个Skills本质上只是把System Prompt挪了个位置，很难带来质的提升。

所以我在安装别人写的Skills时，会先检查目录里有没有scripts子目录、有没有实际可执行的逻辑。如果没有，直接pass。下载"图片生成skills安装包"之类的东西时尤其要警惕——很多包装得很满，实际效果就是把一堆提示词模板堆在一块。

5.2 上下文空间的隐性占用

每个Skill加载进Agent以后，它的描述信息会占据一定的上下文窗口。装50个Skills，哪怕每个只占几百个token，加在一起也会挤占模型真正干活的空间。而且每次模型决定"要不要调用Skill"的时候，都要把候选项扫一遍，Skill数量越多，判断越慢、误触发率越高。

因此我个人的建议是：Skills数量控制在10个以内，而且每个Skill的SKILL.md不要冗长。如果你做的东西很复杂，应该用"摘要放在SKILL.md、细节放在references"的方式把上下文消耗压低。

5.3 脚本依赖是最大的不稳定因素

Skills一旦涉及执行脚本，就绕不开依赖问题。最常见的翻车现场是：

• 脚本依赖某个Node版本，结果用户只有Python环境；
• LaTeX排版Skills要求TeX Live，但用户电脑上只装了TinyTeX；
• 用了Puppeteer相关脚本，但本机没有安装对应浏览器内核。

解决办法有两种，按推荐程度排序：一是尽量用"系统自带能力 + 标准库"实现，比如Python的subprocess、pathlib这些，少依赖第三方包；二是实在要依赖，就在Skills里附带一个setup.sh或者requirements.txt，装Skill的时候顺手执行一遍，把环境准备好。我自己发布Skills时一定会写清依赖，而且尽量用Python标准库。

5.4 安全问题：Skills会执行任意代码

这是目前讨论得最少、但最致命的问题。一个Skill的脚本，本质上是让Agent在用户机器上执行任意代码。如果你从网上下载了一个来历不明的Skills，又没有仔细审查里面的脚本，等于把钥匙交出去了。

我在自己机器上装第三方Skills之前固定做几步：

1. 打开目录，逐行看Scripts里的主力脚本；
2. 搜索网络请求相关代码（requests、urllib、socket、subprocess到外部命令等）；
3. 检查有没有读取环境变量、密钥文件的逻辑；
4. 在不熟悉前先在一个临时目录或虚拟机里跑一遍。

这一点不是劝退，而是在Agent时代必须建立的习惯。"agent安全"这件事，目前框架层面能做的隔离很有限，真正防线还是在用户这一步。

5.5 Agent记忆、Evals与Skills的组合用法

最后一个容易被忽略的问题是如何把Skills和自己的使用习惯、项目背景结合起来。搜索词里有"agent记忆"和"agent evals"，这两块恰恰是让Skills从"能用"变成"好用"的关键。

Agent记忆决定了Skill能不能"记住上次用户的偏好"——比如你上次用LaTeX Skills时指定了字体和页边距，那么下次触发时应该优先沿用。目前主流框架对这个的支持还不完全一致，但你可以通过Skill脚本在自定义目录里记录一份配置文件来实现。Evals则是为了保证Skill在修改之后不退化——把一组历史任务固化成测试集，每次改动后跑一遍，成功率不降才能发布。

这三者结合起来的完整工作流是：

1. 用Agent记忆保存用户的格式偏好；
2. 每次触发Skill时读取偏好、按需生成；
3. 用一个固定任务集做Skill的回归测试，确保升级不破坏老功能。

这个铁三角，是我现在所有自用Skills的标准配置。

6. 面向Agent开发新手的两个认知

聊完了实操层面的细节，最后想再分享两个更"元"的认知。这两个认知不一定能帮你解决眼下的报错，但能帮你在Agent开发这条路上少走很多弯路。

第一个认知是：Skills的爆发本质上是Agent行业从"模型能力竞赛"转向"工程能力竞赛"的信号。模型本身的智商差异正在逐步缩小，真正的差距体现在的"谁能为模型配好一套好用的工具"。Skills就是这个"工具装配层"。这其实对开发者很友好——因为模型的训练和你没关系，但Skills是你亲手写的，其中的工程含金量实实在在掌握在你自己手里。

第二个认知是：现在花时间学习写Skills，很可能复利非常明显。很多框架都有自己原生的一套东西，一两年后可能就换了，但Skills这套"能力包"的抽象正在被各生态事实统一。你现在掌握的知识，在Claude Code能用，在Codex能用，在Pi Agent能用，将来大概率还能迁移到更新的Agent平台上。这就像当年会写插件的人从Chrome迁移到VS Code再迁移到Figma，能力本身是一直复用的。

如果你正处在"想学Agent开发但不知道从哪下手"的阶段，我个人建议的路径是：先把官方文档里Skills相关章节读完，再装几个社区热门Skills感受一下"调用了Skill和没调用Skill"的差距，然后挑一个日常重复最多的小任务，自己写一个极简Skill跑通全流程。这一步走完，你对Agent开发的理解会有一次真正的质变，远超看再多的教程。

最后再分享一个小技巧：在调试Skill的时候，往往一个很小的"日志开关"就能让开发效率翻倍。无论你写的是Shell脚本还是Python，都优先加一个--debug参数或者环境变量，把Skill的执行过程打出来。这样装Skill的人遇到问题能自己排查，你也省去了大量"远程猜谜"的时间。这个习惯我从第一个Skill开始保持到现在，救过我无数次。