企业官网建设流程全解析

做 AI Agent 开发这大半年，我踩得最深的坑不在模型选型，也不在框架配置，而在 skills。这个词如今被说得很多——GitHub 上随手一搜就是几百个 skill 仓库，社区里三天两头冒出“superpower skills”“AI 漫剧常用 skills”这类热词，但真正能讲清楚 skills 是什么、怎么写、怎么装、怎么排障的人，其实很少。我一度以为 skill 就是“给 agent 写一段提示词”，直到亲手做了 agent-skills 这个项目，把几十个技能装进 Claude Code、Codex、Pi Agent 这些环境里反复跑，才把这里面的门道彻底摸透。

这篇文章是我实际做 agent-skills 相关项目过程中的完整复盘。它不是什么官方文档翻译，也不是概念科普，而是从“我要给 agent 装一组能稳定复用的技能包”这个真实需求出发，把 skill 和 agent 的边界、SKILL.md 的写法、Claude Code / Codex 手动安装流程、常见报错的排查套路，以及 LaTeX 排版和图片生成这类实战 skill 的落地过程，全部摊开来讲。适合正在做 agent 开发、或者刚接触 Claude Code / Codex / Pi Agent 这类工具、想给智能体补齐专业能力的读者。

1. 先搞明白：Agent Skills 到底是什么

1.1 skill、agent、harness 三者的边界

很多人一开始都会被这三个词绕晕。我自己的理解是：agent 是一个“能思考、能决策、能调用工具”的执行者，它负责接收任务、拆解步骤、调用工具、汇总结果；harness 是 agent 运行时的外部约束层，它决定了模型能访问哪些工具、哪些文件、哪些权限，相当于给 agent 划了一条活动边界；而 skill 是装进 agent 手里的“专业技能包”，里面包含一段写好的操作指南、配套脚本、模板文件，让 agent 在遇到特定任务时不用从零摸索，直接按成熟流程执行。

打个比方：agent 是一个新入职的员工，harness 是公司的规章制度和门禁权限，skill 则是老员工整理好的“岗位操作手册+工具包”。员工再聪明，没有操作手册也容易凭感觉做事；制度再完善，不教具体怎么做也产出不了高质量结果。所以三者是互补关系：harness 管“能做什么、不能做什么”，skill 管“这件事具体怎么做才专业”。

网上常有人问“skill 和 agent 有什么区别”，其实它们根本不是同一层的东西。skill 是给 agent 用的插件包，agent 是承载 skill 运行的主体。同一个 skill 可以被不同的 agent 加载，比如一个 PDF 解析 skill，既能给 Claude Code 用，也能给 Codex 用，只要它们遵循相同的 skill 加载约定。我在项目里就经常把同一个技能在两个工具间来回搬，这份通用性正是 skills 模式的魅力所在。

1.2 为什么 agent 开发绕不开 skills

大概从去年开始，我明显感觉到纯靠提示词去驱动 agent 已经不够了。原因很简单：大模型的上下文窗口再大，也不可能把所有专业流程都塞进一条 prompt 里；而且提示词是“一次性的”，每次任务都要重新写、重新调，很难沉淀成资产。

skills 这个模式解决了三个非常实际的问题。第一是知识外置，把某个领域的操作流程、注意事项、模板文件全部打包进 skill，agent 只在需要时读取，不占用日常对话的上下文空间。第二是可复用，一个写好的 skill 可以跨项目、跨 agent 使用，团队里共享一份，大家产出的行为就一致了。第三是可迭代，skill 就是普通文件，放进 Git 就能版本管理，改坏了随时回滚。

我做过一个对比实验：同一个 agent，没装 skill 时让它做一个 LaTeX 排版任务，它会把排版格式做得乱七八糟；装上一个写好的 skill 之后，同样的任务，输出质量几乎稳定在同一个水平线上。这就是“手艺”和“套路”的区别。agent 不缺智商，缺的是一个靠谱的套路，而 skills 就是把这些套路沉淀下来的标准方式。

2. Skills 开发的关键细节：从最小结构到完整规范

2.1 一个 skill 的最小文件结构

很多人以为 skill 很神秘，其实剥开看就是一组普通文件，通常长这样：

my-skill/ ├── SKILL.md # 核心指令文件，agent 最先读的就是它 ├── scripts/ # 辅助脚本，比如 Python / Shell 脚本 ├── assets/ # 模板、参考图片、数据文件 └── requirements.txt # 依赖清单（可选）

整个 skill 里最关键的只有 SKILL.md。这个文件的命名和放置路径都有约定：Claude Code 要求每个 skill 独立占一个目录，目录里必须包含 SKILL.md，目录整体放在个人级或项目级的 skills 文件夹下；Codex 的约定大同小异，只是具体路径不同。很多新手在这里栽跟头，把 SKILL.md 直接丢在 skills 根目录下面，没有单独建子目录，结果框架扫描时根本不认这个技能。

我建议一开始不要贪多，一个小 skill 只要两样东西就能跑：一个写清楚的 SKILL.md，外加一个可选脚本。等跑通了再逐步加 assets 和依赖清单。先用最小的结构把流程走通，比一开始就设计一个庞大的目录树要实在得多。

2.2 SKILL.md 到底该怎么写

这是 skill 开发里最关键、也最容易被低估的一步。我的经验是：SKILL.md 不是写给人类看的说明文档，而是写给“一个很聪明、但对你的领域完全不了解的实习生”看的操作手册。你是在把老师傅脑子里的经验翻译成文字，翻译得越具体，agent 执行得越稳。

一个好的 SKILL.md 至少要包含这几块内容：概述，说明这个 skill 是干什么的、在什么场景下使用；适用与不适用情况，明确写出什么时候该用、什么时候不该用，避免 agent 误调用；操作步骤，按顺序列出完整的工作流，每一步要具体到可执行；质量标准，告诉 agent 什么样的输出算合格，比如格式要求、检查清单；反模式，列出常见错误做法并提醒 agent 规避；还有示例，给一两个输入输出样例让 agent 有参照。

举一个我在 LaTeX 排版 skill 里写过的例子。我不会只写“帮用户排版论文”，而是会写清楚：优先使用哪些文档类、中文场景用哪个宏包、图表用哪个环境、参考文献用哪种格式、编译报错时先检查哪几个地方。这样 agent 拿到任务时，每一步都有据可依，而不是凭训练数据里的模糊记忆瞎猜。

还有一个细节：SKILL.md 开头一定要有清晰的元信息，比如 name 和 description。description 尤其重要，因为 agent 是靠它来判断“这个任务该不该调用这个 skill”的。描述写得太泛，agent 会乱调用；写得太窄，该调的时候又调不到。我常用的技巧是：描述里同时包含“触发场景”和“不使用场景”，把边界划清楚，让 agent 的选择成本降到最低。

2.3 三类最常见 skill 的写法差异

我拆过不少社区里的 skill，发现它们大致分成三类，写法侧重点完全不同。

第一类是流程编排型，比如代码审查、数据清洗、自动化测试。这类 skill 的核心是步骤编排，把一系列工具调用串成流水线，写的时候要把每一步的输入输出和判断条件写清楚，重点是“流程不漏步、异常有兜底”。第二类是专业领域型，比如论文排版、财务分析、法律文书。这类 skill 的核心是领域知识外置，把术语、规范、模板都收进来，写的时候要重点写“质量标准”和“反模式”，因为领域任务最怕 agent 凭常识瞎发挥。第三类是工具封装型，比如调用某个 API、操作某个软件。这类 skill 的核心是脚本，SKILL.md 反而可以精简，重点是教会 agent 怎么传参、怎么处理返回值、怎么识别报错。

搞清楚自己写的是哪一类，写起来就快很多。我自己一开始就犯过错误，想写一个全能型的“超级 skill”，塞了一堆互不相关的内容，结果 agent 每次调用都不知道该执行哪一部分，效果反而不如几个小而精的 skill。后来我把这个大而全的东西拆成三个独立技能，整体成功率直接上了一个台阶。

3. Skills 的安装、推荐与日常管理

3.1 Claude Code 和 Codex 手动安装 skills

社区里问得最多的问题就是“Claude Code 怎么手动装 GitHub 上的 skills”。其实流程非常简单：先把 GitHub 上的 skill 仓库 clone 到本地，然后确认仓库里的目录结构中有 SKILL.md，再把整个技能目录复制到 Claude Code 的 skills 路径下，个人级是~/.claude/skills/，项目级是.claude/skills/，最后重启 Claude Code 或者用相关命令刷新技能列表。

Codex 的安装逻辑类似，只是路径换成~/.codex/skills/或项目目录下的.codex/skills/。装完可以用一条简单的测试指令验证，比如直接对 agent 说“列出你当前可用的 skills”，看它能不能正确识别到新装入的技能。这一步千万别省，很多安装失败都是因为路径放错，但当时完全没发现。

这里有个容易踩的坑：不少 GitHub 仓库是“skill 集合”，一个仓库里包含十几个甚至几十个技能目录。这时候不要整个仓库复制进去，应该按需把需要的子目录单独复制到 skills 路径下。装得太多，agent 在工具选择阶段会变慢，还容易选错，最后反而拖累整体效率。

3.2 常用 skills 源网站和推荐清单

现在 skills 的获取渠道已经比较成熟了。GitHub 上有不少高质量的技能集合仓库，比如 Anthropic 官方维护的 skills 示例库，里面包含 LaTeX 排版、数据可视化、PDF 处理、量化分析等常用技能。社区里也有各种 awesome 风格的列表，把大量按场景分类的社区 skills 整理成了目录，找起来很方便。

我在实际项目中常用的几类 skills 大概是这样的：

搜索技巧方面，我习惯用“site:github.com 加上场景关键词”的方式去找，命中率比直接搜 skills 高得多。另外还要提醒一句：从任意渠道下载 skill，第一件事是通读 SKILL.md 和 scripts 里的代码，确认没有可疑命令再安装。现在 agent 的权限越来越强，一个恶意的 skill 可能诱导 agent 执行危险操作，安全这根弦不能松。本地 skills 装多了之后，想快速查某个技能里写了什么，也可以用 Agent Ransack 这类本地全文搜索工具直接扫 skills 目录，比一个个文件夹翻要快得多。

3.3 Skills 的清理与版本管理

skills 装多了之后，麻烦就来了。我见过有同事一台机器上装了四十多个技能，结果 agent 每次做任务都要在几十个选项里做选择，经常选错，整体效率反而断崖式下降。社区里有人专门讨论过清理 skills 的方法，我实践下来最有效的是三条。

第一，定期审视使用频率，一个月没被调用过的技能直接禁用，不要心疼。第二，按项目隔离，把通用的轻量技能放在个人级目录，把项目专属的技能放在项目级目录，避免互相干扰。第三，维护一个“白名单”，新下载的 skill 先放进临时目录试用，确认稳定后再转正到正式目录，从源头控制技能总量。

版本管理方面，我强烈建议把团队的 skills 目录做成一个 Git 仓库。每次改动都留记录，谁改了什么一目了然。技能迭代和代码迭代其实是一样的，一定是边用边改，没有版本记录就只能靠记忆，迟早出问题。我现在每次跑完一个失败案例，第一件事就是在 skill 的文档里追加一条注意事项并提交，几个月下来，这些技能变得非常抗造。

4. Agent 开发学习路线：框架、编排、记忆与评估

4.1 主流开源 Agent 框架速览

如果你想系统学习 agent 开发，而不是只停留在“给 agent 装个 skill”的层面，那一定绕不开框架选型。目前社区里活跃度比较高的几个方向包括：Pi Agent，主打桌面端和浏览器自动化，适合做“能自己操作电脑干活”的智能体，有官方桌面应用，对普通用户比较友好；Hermes Agent，定位本地优先的通用 agent，强调隐私和可扩展性，社区讨论很多，安装方式也比较简单；OpenCode，开源终端里的编程 agent，主打和编辑器、命令行深度集成，适合开发者日常使用；再就是 Claude Code、Codex、Cursor 这类商业或半商用工具，内置了 agent 能力，也是我日常用得最多的执行环境。

学习路线我的建议是：先从商业工具上手，因为门槛最低，能快速感受到 agent 加 skills 的完整闭环；然后选一个开源框架读源码，重点理解它的“工具调用循环”是怎么实现的，也就是模型怎么决定调哪个工具、工具返回后怎么继续推进；最后再动手写一个极简框架，把控制循环、上下文管理、错误处理各写一遍，你会对 harness 和 agent 的关系有非常直观的理解。这条路线走完，再去看社区里那些新框架，基本一眼就能看出它的设计取舍。

4.2 框架与编排：理解 harness 和 agent 的分工

前面提到了 harness 和 agent 的区别，这里展开说一下。框架层面的代码通常分成两层：外层是 harness，负责安全策略、工具注册、权限控制、会话管理；内层是 agent，负责任务规划、调用决策、结果反思。为什么需要这种分工？因为纯让模型自己决定“能调什么工具”是很危险的，没有 harness 约束，一个模型可能因为某句 prompt 就尝试读取敏感文件、执行危险命令。

harness 相当于在模型和系统之间加了一道闸门，所有工具调用都必须经过它审批才能放行。理解了这一层，你就明白为什么 skills 要放在 harness 能管理的目录里：skill 本质上也是一种“被批准的工具包”，harness 扫描目录、加载元信息、注册成可用工具，agent 才能在运行时发现它。所以当你发现“skill 装上了但 agent 看不到”，大概率是 harness 的加载路径或者文件格式出了问题，而不是模型的问题。

我见过很多初学者把精力全花在调提示词上，却忽略了对 harness 层的理解。其实只要把工具注册、权限配置、上下文管理这几个机制搞明白，很多看似玄学的问题都能迎刃而解。框架和编排的价值就在这里：它决定了你的 agent 是“裸奔”还是“穿着装备作战”。

4.3 记忆、评估与安全：把 skill 放对位置

除开技能，一个完整的 agent 还涉及三个容易被忽略的组件：记忆、评估、安全。记忆解决的是跨会话连续性问题，最简单的实现是把历史关键信息写成结构化文件存起来，复杂一点会用向量数据库做语义检索。我的经验是：能用文件解决的场景，不要急着上向量库，文件直观、可控、好调试，很多 agent 需求其实用不上语义检索。

评估解决的是“怎么知道 agent 改好了还是改坏了”的问题。我强烈建议每个项目至少维护十条以上的评测用例，覆盖典型任务和边界情况。每次修改 skill、提示词或者框架配置，都跑一遍评测看成功率是上升还是下降，而不是凭感觉判断。社区里常说的 evals 就是这个意思，它本质上是在给 agent 做单元测试。

安全则贯穿始终。除了前面说的检查 skill 内容，还要注意三点：给 agent 的权限遵循最小化原则，能不给的权限尽量不给；对来自外部的文件或链接，要求 agent 先检查再处理，防止提示词注入；敏感操作设置人工确认环节，避免 agent 在无人监督时执行高风险动作。在我自己跑项目的过程中，安全配置做得越细，反而越敢放权给 agent 去做复杂任务，因为你知道它不会越界。

5. 从报错到可用：常见问题排查实录

5.1 “agent execution terminated due to error” 排查思路

“agent execution terminated due to error”是社区里被问得最多的一条报错。这个提示本身只说“执行被终止”，真正的原因千奇百怪。我排查这类问题的固定顺序是四步。

第一步看上下文长度，很多 agent 在执行长任务时把中间过程全部堆在上下文里，一旦超限就会被强制终止，解决办法是拆分任务、减少不必要的中转输出，或者给 agent 配置摘要机制。第二步看工具调用格式，agent 生成的动作如果不符合工具协议，框架会直接终止，这时要检查是不是自定义 skill 的参数格式写错了，比如 JSON 字段名不一致。第三步看外部 API 错误，模型服务限流、超时、返回异常都会导致中断，这类错误通常会在日志里给出更具体的提示，优先看日志尾部。第四步看权限问题，agent 尝试访问没有权限的文件或命令，被 harness 拦下来，也会呈现为 terminated。

我的经验是：遇到这类错误先不要慌，把日志级别调成 debug 重跑一遍，百分之九十的原因都会在日志里现出原形。基本没有必须靠猜才能解决的问题。把这条报错当成一个“总入口”，顺着日志往里钻，比反复重试有效得多。

5.2 Skill 装上了却不生效怎么办

这个问题的出现频率也很高。装好 skill 之后，agent 完全不调用它，或者调用了但行为没变化。我排查时会按下面的顺序一项项过。

首先确认路径是否正确，skills 该放在个人目录还是项目目录，不同工具有不同约定，放错位置就白装了。其次确认元信息是否规范，SKILL.md 里的 name 和 description 有没有写清楚，description 写得不好，agent 在决策时根本不会选中它。然后确认目录是否完整，有些 skill 依赖 scripts 下的脚本文件，复制的时候漏了文件，skill 一运行就报错。最后确认是否刷新，部分工具需要重启会话才能重新扫描技能目录，装完没重启，自然看不到效果，这不是 skill 的问题，是你没给它“上岗”的机会。

另外还有一个很容易被忽略的点：项目级目录的技能优先级通常高于个人级目录。如果你在个人级装了一个旧版本、项目级又放了一个新版本，agent 很可能会加载旧的那个，排查时记得把两个目录都看一眼。

5.3 工具调用混乱与上下文污染

装了一堆 skills 之后，另一个典型问题是 agent 频繁调用错误的技能，或者一次任务把所有技能都“过”了一遍。这通常是两个原因造成的：一是技能描述写得太宽泛，导致多个技能在 agent 看来都“沾边”，选择困难；二是技能数量过多，工具选择空间太大，模型决策难度直线上升。

对应的解决办法也很直接：把各个技能的 description 重新精修，明确各自的触发边界，让相似技能之间形成互补而不是重叠；同时对暂时用不上的技能禁用，让可选集变小。上下文污染的问题则要靠“减少中转输出”来解决，让 agent 只保留对后续步骤有价值的信息，而不是把工具的所有原始输出都留在上下文里。我习惯在 SKILL.md 里明确写一句“只返回摘要，不要粘贴完整日志”，这一个习惯就能省下大量上下文空间。

6. 两个实战案例：LaTeX 排版 skill 与 AI 漫剧图片生成 skill

6.1 从零开发一个 LaTeX 排版 skill

完整走一遍写 skill 的流程，我拿 LaTeX 排版来做例子。这个需求很典型：很多用户并不熟悉 LaTeX，但写论文、做报告、排简历都需要它，符合“专业性高、流程固定、经验可沉淀”的 skill 特征。我的 SKILL.md 结构大概是这样的：

--- name: latex-typesetting description: 用于 LaTeX 文档排版，包括论文、报告、简历。当用户需要生成或修改 .tex 文件时使用；不用于纯文本排版。 --- # LaTeX 排版 ## 使用前提 - 确认输出目标是 .tex 文件，且编译引擎可用。 ## 排版步骤 1. 根据文档类型选择文档类（article/report/ctexart）。 2. 正文用结构化写法，图表用 figure/table 环境。 3. 参考文献用 BibTeX，编译顺序按 xelatex -> bibtex -> xelatex -> xelatex。 ## 质量标准 - 中文字符能正常编译。 - 图表编号和引用一致。 - 不出现 Missing $ 和 Undefined control sequence 类报错。 ## 反模式 - 不要手工调整页码和边距来"硬排版"。 - 不要混用不同宏包的相似功能。

核心思路是把一个专业排版人员的经验全部压进文件里。我还会附一个模板文档放到 assets 目录，agent 可以直接复制改。这个 skill 开发完成后，实测效果提升非常明显：原本 agent 生成的 LaTeX 经常编译不过，装上后出错率大幅下降，因为反模式部分已经提前把最常见的坑写明白了。这个案例对我最大的启发是：写好一个 skill 的关键，不是堆功能，而是把你踩过的坑全部写进去。

6.2 安装并调优一个图片生成 skill

另一个高频场景是 AI 漫剧的图片生成。这类任务的痛点是画风不稳定、分镜不统一，社区里有一些现成的图片生成 skills 安装包，装好后能给 agent 提供结构化的提示词模板，让每次生成的画面风格都锁定在同一套参数里。

安装流程和前面说的一样：下载、放进 skills 目录、重启、验证。但真正值钱的是调优环节。我会重点修改 skill 里的提示词模板，把角色描述、场景描述、光线风格固定成若干可替换的插槽，每次生成时只替换关键变量。这样即便换了场景，画风和角色形象也能保持一致。这个思路其实和写代码是一样的：把不变的东西抽象出来，把变化的东西做成参数，图片生成 skill 立刻就从“能用”变成了“好用”。

6.3 前端开发类 skills 的选型经验

最后简单说下前端开发场景。热词里提到的 superpower skills，其实是社区里一套比较知名的技能集合，里面覆盖了前端组件生成、代码审查等常见任务。我的建议是：不要整套安装，按需选几个和你技术栈匹配的单独用。

前端类 skill 的选型核心看两点：一是它使用的技术栈版本是否和你项目一致，二是它有没有内置质量检查步骤。一个只生成代码但不做检查的 skill，产出的代码往往需要大量人工返工；而包含 lint 和构建验证步骤的 skill，才是真正能减少工作量的。我自己选 skill 的标准很简单：先看它的 SKILL.md 里有没有“验证”部分，没有的坚决不装，因为那只是把不完整的活推给你自己。

我个人在实际操作中最大的体会是：agent 的能力上限由模型决定，但它的能力下限由 skills 决定。同样是当前主流的模型，装没装好一组高质量 skills，实际交付质量可以差出好几个档次。所以如果你现在正准备入门 agent 开发，我的建议是别急着追新框架，先手写两三个自己的 skill，把 SKILL.md 写好、装进工具、跑通一个完整任务，再回头看框架源码，整个认知会瞬间打通。

最后再分享一个小技巧：给你的每个 skill 都建一个“失败记录”。每次 agent 在某个步骤上出错，就把错误现象和修复方法追加进去，并在 SKILL.md 的反模式里同步更新。跑几个月之后，这个 skill 会变得非常抗造，这才是 skills 最大的复利效应。