企业官网建设流程全解析

接到这个标题“agent-skills”的时候，我第一反应是：这不就是当前 AI Agent 开发圈里被讨论最多、却也最容易被误解的一个概念吗？如果你最近刷过 GitHub、看过 Codex 或 Claude Code 的更新日志，大概率已经见过 skills、superpower skills、pi agent、codex skills 这些词。它们围绕同一个核心：让 AI Agent 不再只是“会聊天”，而是真的“会干活”——按固定流程、带专业方法、能稳定复现地干活。

这篇内容我想用做 agent 项目的实操视角，把 skill 到底是个什么东西、和 agent / harness 有什么区别、怎么安装、怎么写、怎么避坑，从头到尾捋一遍。无论你是刚接触 agent 开发的新手，还是已经在调 Codex、Claude Code 但被“execution terminated due to error”折腾到头秃的老手，这篇文章都能给你一些可以直接上手的参考。

1. Skills到底是什么：一句话能说清，但很多人理解偏了

我见过不少人在群里问“skill 和 agent 有什么区别”。如果只能回答一句话，我会说：agent 是“执行者”，skill 是“执行者脑子里的操作手册”。一个 agent 可以没有 skill，跑步起来；但想让 agent 在某个领域稳定干活，几乎必须有 skill。

1.1 从 Prompt 到 Skills：AI Agent 的“肌肉记忆”

最早大家用 LLM 的时候，靠的是 Prompt。你把需求写清楚，模型自由发挥。自由发挥的问题在于：同一个任务，今天的结果和明天的结果可以差很多。尤其在代码生成、图片生成、文档排版这类有固定流程的任务里，模型常常会跳步、漏细节，或者“自以为做完了但根本没保存文件”。

Skills 的出现就是为了解决这个“自由发挥”的问题。它本质上是一个预定义好的、可复用的能力包，里面装的是：

• 对任务目标的明确描述
• 完成任务的步骤或流程
• 每一步需要调用的工具或命令
• 判断结果是否合格的检查项
• 常见坑和禁忌

用生活类比来说，Prompt 像你给一个实习生口头交代“把这个报表做一下”，而 Skill 像你给他一本《报表制作标准作业流程手册》，里面写了用哪个模板、数据从哪取、公式怎么填、做完怎么自检。显然，后者的结果稳定得多。

我在实际项目中有一个体会：不带 skill 的 agent 更像一个“聪明但不太靠谱的新人”，而带着 skill 的 agent 可以做到“稳定产出合格结果”。这背后的原因是，skill 把隐性的专家经验显性化了。你不需要每次对话都重新解释需求和流程，agent 会在匹配到对应场景时自动套用技能。

1.2 Skill、Prompt、Tool、Agent 到底有什么区别

这个表我建议你存下来，因为几乎每个做 agent 的人都会被问到：

很多人的误区是：把 skill 当成一个超长 prompt。实际上，一个完整的 skill 往往包含多个文件，除了 instructions 或 SKILL.md 这种主文档，还有脚本、模板、参考样例。它是一套“资源包”，不只是几行文字。

还有一个常被搞混的点：tool 和 skill 的区别。Tool 是“手”，skill 是“脑子里的规程”。你可以给 agent 一个 Python 执行工具，但它用 Python 写爬虫还是写数据分析，取决于 agent 自己的临时发挥；而 skill 则规定好了：第一步用 Python 拉数据，第二步清洗，第三步画图并保存到指定目录。所以，skills 可以调用 tools，但 tools 本身不等于 skills。

1.3 为什么今年“Skills”突然爆火

前面提到，AI 编程工具已经进入了“记忆 + 技能”的竞争阶段。一个 Agent 如果只有模型本身的推理能力，没有外部技能包，它顶多是一个“聪明但失忆”的助手。而有了 skills，agent 可以像老员工一样，对不同任务直接调用储存在工作记忆里的流程。

这也解释了为什么 Codex、Claude Code、OpenCode、Pi Agent 都在争相支持 skills：谁支持的技能格式多、谁安装 skill 更方便，谁就能吸附更多开发者生态。对于我们自己写代码的这些人来说，好消息是，skills 一旦写好，是可以在多个 agent 框架之间迁移的，至少目前主流的 SKILL.md 规范在互认。坏消息是，各家在安装路径、调试命令、harness 行为上有差异，需要针对性地适配。

2. 主流 Agent 框架里的 Skills 生态：各家用各家的“方言”

做 agent 开发的人，应该都能感受到当前框架层的变化频率有多快。以我长期用的 Claude Code 和 Codex 为例，它们对 skills 的支持方式差异其实挺大的。

2.1 Claude Code 与 Codex：两大流派的思路

Claude Code 的思路是“把技能放进项目上下文”。它会在启动时读取.claude/skills目录下的技能文件，将其中的指令注入给模型。这个方案的优点是对用户透明，你能直接在对话里感知到“这个技能生效了没有”。缺点是，技能太多会挤占上下文窗口，影响模型处理当前任务的空间。

Codex 的思路更偏向“按需加载”。它把技能视为一个独立资源，只有当任务描述与技能描述匹配时才会被加载执行。这种方式的上下文开销更小，但对技能描述（description）的写作质量要求更高——描述写不好，模型根本不会触发你的技能。我见过很多开发者的 skill 写得很好，但因为 description 里没有写上“什么时候用这个技能”，结果一直没被触发。

在安装路径上，Claude Code 手动装 GitHub 上的 skills 一般是 clone 到.claude/skills/目录；Codex 通常放到~/.codex/skills/或者项目下的.codex/skills/。这块没有行业统一标准，各框架之间互不兼容的情况很常见。我的习惯是，在项目.cursor或.claude下都保留一份关键技能的软链接，避免切换工具时丢失行为。

2.2 周边生态：OpenCode、Pi Agent、Superpower Skills 与技能库

OpenCode 是一个轻量化的 agent 终端工具，它的 skills 体系跟 Codex 接近，依赖 markdown 文件的头信息和目录结构。Pi Agent 则是今年社区里讨论度很高的另一个 agent 项目，它强调“多技能组合调用”，在某些场景下可以把多个 skill 串联成一条工作流。

社区里还有一个很出名的技能集合叫 superpower skills，很多人搜“superpower skills 安装”就是在找它的安装方式。这个集合把大量实用技能（如代码审查、重构、文档生成）打包在一起，安装方式也比较友好。我试用过其中的代码审查技能，确实比裸写 prompt 效果稳定，因为它的检查清单非常具体，比如“是否修改了公共接口但没更新所有调用方”这类细节都能覆盖到。

此外，社区里也涌现出不少“常用 skills 源网站”和“skills 技能库”。这些站点通常按类别整理好了各种领域的技能，比如前端开发、数据可视化、LaTeX 排版等。我的建议是，第一次逛这类技能库时，不要疯狂下载，先想清楚你日常最重复、最痛苦的任务是什么，再针对性地选 2-3 个技能深度使用。否则技能包越攒越多，真正用到的不超过一成，反而拖慢 agent 的加载速度。

这里也提醒一下：从非官方渠道下载技能包时，务必检查 SKILL.md 中是否包含可疑的额外指令，比如要求 agent 执行 curl 脚本、上传本地文件到外部服务器等。AI 领域的供应链攻击已经开始出现了，安全红线必须时刻绷紧。

3. 动手开发第一个 Skills：从零到能稳定复现

接下来进入正题。与其到处找现成 skills，不如自己动手写一个。自己写的技能有两个好处：一是完全贴合你的工作流程，二是能帮你看清 skills 的底层机制，之后调试别人的技能包也会快很多。

3.1 设计 Skills 的核心步骤：先写文档，再写流程

我在跟很多朋友交流时发现，新手最容易犯的错是一上来就写代码、写脚本。但 skills 的核心其实是“流程设计”，不是“脚本编写”。我一般会先回答三个问题：

1. 这个技能解决什么任务？任务边界必须清晰，比如“生成项目周报”而不是“写文档”。
2. 一个专家是怎么完成这个任务的？把步骤拆到 5-8 步，每步必须有可验证的输出。
3. 哪些地方容易出错？把这些坑写进“注意事项”或“checklist”。

以我最近写的一个“图片批量压缩并生成对比图”的技能为例。最初版本的流程只有三步：读取图片、压缩、保存结果。但实际使用时，agent 经常压缩完就忘了生成对比图。后来我在技能里加了一条硬性约束：“第 3 步完成后必须生成压缩前后对比图，并且当且仅当对比图存在时才能输出完成消息”，问题才被解决。

这就是我们常说的“可验证输出节点”。每一步之后，agent 需要 self-check 才能进入下一步，而不是让它自由发挥。

3.2 骨架、SKILL.md 与行动清单的写法

一个标准 skill 的目录结构通常是这样的：

my-skill/ ├── SKILL.md ├── scripts/ │ └── main.py ├── templates/ │ └── output_template.md └── examples/ └── sample_input.json

其中 SKILL.md 是核心，一般用 Markdown 编写。我的习惯是以下结构：

--- name: weekly-report description: 根据 git 提交记录生成周报。适用于项目周报、月度总结，输入为 git log 或 issue 列表。 ---

frontmatter 之后，正文需要包含：

• 触发条件与输入格式：明确这个技能什么时候被调用。
• 执行步骤：数字编号，每一步尽量包含可执行的命令或文件路径。
• 输出规范：最终产物的格式与保存路径。
• checklist：输出前的自检清单。
• 常见错误：以及对应的处理方法。

我一般不会把超长示例写进 SKILL.md 本体，而是放在 examples/ 目录下，让模型按需读取。因为很多 agent 框架在处理超长文件时，反而会“抓不住重点”。

3.3 调试与迭代：一次真实开发踩坑记录

写完第一个 skill 后，真正的痛苦才开始。我调试“代码重构”技能时，前三次运行全部失败。第一次失败是因为步骤描述太模糊，agent 重构完没有跑测试；第二次我加了“必须运行 go test ./...”的指令，但它真的老老实实跑了，却因为测试环境缺依赖报错，agent 直接放弃了任务，报出 “Agent execution terminated due to error.” 后来我在技能里加了“若测试因依赖缺失失败，先安装依赖再重试”的决策分支，效果才正常。

这次经历让我总结出一个调试原则：永远给 agent 留“失败后怎么办”的补救路径。如果你只告诉它“做 A、做 B、做 C”，当 B 失败时，它很可能卡死或直接终止。而一个成熟的技能应该像老手带新人一样，把“如果遇到 X，就试试 Y”写清楚。

调试时还有一个痛点：上下文爆炸。如果技能文件太多太长，agent 到后面会“忘掉”前面的步骤。我的解决方案是：把一次性加载的内容控制在 2000 字左右，其余内容做成参考文件，在需要时由 agent 自己决定是否读取。这个“按需读取”思路也是很多主流 agent 框架默认支持的。

4. 安装、使用与编排：别让 Skills 变成“摆设”

写好 skill 只是第一步，怎么把它装进 agent，并在日常流程里稳定触发，才是真正考验耐心和工程能力的地方。

4.1 手动安装与常用技能源

很多人在搜“claude code 怎么手动装 github 上的 skills”和“opencode skills”，说明安装这件事确实有门槛。以最常见的做法为例，安装步骤大致是：

# 进入技能目录 cd ~/.claude/skills # 或者项目级目录：cd .claude/skills git clone https://github.com/username/skill-repo.git # 安装后重启会话，或直接询问 agent 是否识别到新技能

对于 Codex，路径一般是：

mkdir -p ~/.codex/skills cp -r /path/to/my-skill ~/.codex/skills/

安装完之后，一定要先问 agent“你现在能用哪些 skills”，或者让它复述技能内容，确认技能被正确加载。这能省下很多“我明明装好了，但它根本不理会”的排查时间。

关于技能源，社区比较活跃的仓库通常会在 README 里写明安装方式。我的建议是：优先选择那些带有 examples 目录、且每个技能都有独立 description 的仓库。如果某个技能包只有一个巨大的 markdown 文件，没有任何脚本和示例，它很可能只是换了个名字的“超长 prompt”，对稳定产出的帮助有限。

4.2 Agent Harness 与 Skills 的编排关系

“harness 和 agent 区别”也是热搜里的高频问题。Harness 可以理解为 agent 的运行框架，它负责调度模型、解析工具调用、管理上下文窗口、处理错误。Skills 则在 harness 的规则之下运行。

实际工程中，harness 决定了 skills 的能力边界：

• 上下文窗口大的 harness 可以加载更多技能说明，但成本更高
• 自动错误重试机制强的 harness，能让技能里的“补救分支”发挥更大作用
• 工具权限控制严格的 harness，安全性更高，但也会限制技能脚本的灵活性

所以，当你在 A 框架里验证了一个 skill 很正常，换到 B 框架后效果大打折扣，不一定是 skill 写得不好，也可能是两个 harness 对上下文的裁剪策略不一样。我习惯在技能文件里写明最低框架要求，比如“需要支持 128k 上下文”，方便以后迁移时快速判断。

另外，编排多个 skills 也是今年的热门话题。比如 Pi Agent 支持把“前端开发”和“图片生成”两个 skills 组合使用，先由图片生成技能产出素材，再由前端开发技能把素材嵌入页面。这种组合本质上是在 harness 层做任务规划，然后逐个子任务调用对应的技能包。实践中我发现，组合技能时的上下文管理比单个技能难得多，务必把两级技能之间的转交方式写清楚，例如“输出文件路径必须以绝对路径传给下一步”，否则 agent 会在中间丢链子。

5. 常见问题与排查技巧实录

最后这部分是我想重点分享的实战避坑清单。以下这些问题，都是我自己或身边同事真实踩过的坑，整理出来希望帮大家少走弯路。

5.1 典型报错与解决对照表

5.2 稳定性心法和安全红线

关于稳定性，我最深的体会是：skills 开发是一个迭代过程，不是一次性写作。第一版能跑通就算成功了一半，后续要在真实使用中不断补充边界情况和补救分支。你可以把技能使用过程中的每一次失败记录下来，每周集中更新一次技能文件。三个月后，这个技能会变得越来越“懂你”。

安全红线可以总结为“三不”原则：

• 不直接执行技能文件里含有的不可见代码，先看后跑。
• 不让 agent 自动上传项目内文件到未经确认的外部服务。
• 不把高权限凭据（如云厂商密钥）放进技能的输入输出路径中。

这些属于 AI 工程里容易被忽视的供应链安全范畴。Skill 的本质是“把代码逻辑混入文档”，这既是它的威力，也是它的风险。能用、好用、安全地用，才是一个合格 agent 开发者的完整要求。

最后再分享一个我的个人习惯：重要技能都应纳入版本管理，像维护代码库一样维护它们。技能文件里的内容是写给 AI 看的“需求文档”，也是写给未来的自己看的“流程资产”。当 agent 开发的知识散落在多个工具和对话里时，一套清晰、可复现、可版本化的 skills 体系，就是团队最值得沉淀的财富。