企业官网建设流程全解析

1. 核心问题：Agent Skills 到底解决了什么痛点？

我最初接触 agent 开发时也一度陷入了思维定式：总认为让 AI 干活的唯一方式，就是把所有要求、规则、步骤都塞进 system prompt，或者压进一个大而全的 README 里让智能体去读。这种方式不是不行，只是过了某个复杂度临界点后，你会发现整个提示词结构臃肿得离谱，修改一次要全局排查，而且模型非常容易在长上下文里把重点指令“隐形化”。

后来我用 Claude Code 和 Codex 这类编程智能体重新思考这个流程时才意识到，行业里真正从工程角度去解决“给模型注入专业能力”这个问题的方案，就是skills（技能包）。如果你把 agent 比作一个只能执行基本指令的外科住院医生，那么 skills 就是给他陆续装上、随时取用的专科手术器械包。器械不用时放在仓库里，只占用一点点元数据；用到了，才把这个器械包完整地递给他。这种模式的好处，在于它不是在系统提示词里堆知识，而是在模型意识到自己需要某个专项领域的方法时，才动态地把对应的方法论和组织好的代码逻辑拉进来。

从热词里能看到不少人在讨论 harness 和 agent 的区别，其实我觉得这正对应了今天这个主题的一个侧面。harness 更像是承载 agent 运行的整套脚手架——工具注册、输出解析、循环控制、上下文剪裁都在 harness 层处理；而 skills 是运行在 harness 之上的“类人专长模块”。简单说，一个管运力，一个管专业度。

这个项目标题被很多人反复提起，某种程度上也说明了一个新的技术共识正在形成：调用模型能力的颗粒度，正从发一段指令，转变成装载一组完整的、可评测的、可复用的技能。整篇博文我就围绕这个共识来展开，讲讲什么是真正好用的 skills，怎么开发自己的第一个技能包，怎么选型、安装现有技能，以及实战里那些会让人一头雾水的坑。

2. 生态盘点：从 Claude Code 到 Pi Agent，各自生态里的 Skills 侧写

热词里同时出现了 claude code skills 安装、codex好用的skills、opencode skills、pi agent桌面端、hermes agent 安装，这恰好说明 skills 不是某个单一产品的专有概念，而是新一代 agent 基础设施里普遍采用的一层抽象。如果你正在纠结用哪个平台，先把每个生态的技能机制看明白，再决定怎么落地，会省去非常多返工时间。

2.1 Claude Code 的 Skills：最像“太空步”的一层抽象

Claude Code 是我最早接触的做 skills 概念验证的环境。它把技能组织成.claude/skills目录下的一组文件夹，每个技能拥有一个SKILL.md文件，里面用 YAML front matter 写元数据，用正文写流程和方法。它最让我喜欢的一点，是在主对话中你可以通过@技能名这类主动唤起的方式让 agent 立刻加载对应的知识；而模型自己在任务拆解时，也会根据元数据里的 description 判断“我现在要不要用这个技能”。这种双触发机制用起来非常舒坦，因为我既能在明确的场景里强制生效，也能在模型自由发挥时给它足够的弹性去自主选择。

我实测过一个小项目，让它写一个 Python 的异步爬虫任务，之前模型疯狂在循环节流和异常捕捉上自我发挥，逻辑也过得去，但风格极其不稳定。给 Claude Code 装上一个我自写的“高质量异步任务编写 skills”后，它开始按照技能包里的流程约束去检查任务上下文、设计并发度、封装连接池，连模块 docstring 的严谨程度都提升了一截。这就是 skills 的魔法：场景一匹配上，模型会认为“我应该按专家的标准去执行”，而不是临时做一次普通的文本生成。

2.2 Codex 与 OpenCode：把技能的“原子能力”往工作流里嵌

OpenAI Codex 生态里对 skills 的重视程度不遑多让，社区里甚至把“codex 开发必备的 skills”当成了入行指南。Codex 在实现上更强调 skills 高频小步的原子能力：比如一个专门负责“检查代码变更前后兼容性”的技能、一个专门处理“README 优化与文档统一”的技能。这种颗粒度划分带来的一个好处是：单个技能高度可测试，评估起来非常清晰。我写代码时经常把“自动生成 release note 的技能”、“输出测试矩阵的技能”、“审计依赖版本升级风险的技能”全部挂在同一个 agent 工作流里，每个单元都像一个独立的微服务，替换和升级都不影响其他部分。

OpenCode 的思路又有些差异。它更倾向于把 skill 看作整个 agent 任务链里的一个 hook 节点，用在哪一步、在什么条件下触发、失败后是重试还是降级，都在配置里显式声明。这种“流程声明式”的做法对复杂工程非常适用，不过在技能数量少、任务简单时容易显得过重。所以在我的经验里：简单场景用 Claude Code 的轻量目录结构，复杂流水线用 OpenCode 的显式编排结构。

2.3 Pi Agent：把 Agent Skills 做成“人机协同桌面层”

热词里反复提到 pi agent 桌面端，这是最近关注度非常高的一款agent执行环境。它的特点是把 agent 的运行挪到桌面客户端里，让人可以直接看到智能体的思考过程、技能触发时机和上下文占用情况。对我来说，它最强的点不是聊天界面多好看，而是它对“技能市场”和“评测指标”的整合。很多新玩家问“skills怎么测评”，Pi Agent 默认就把技能的召回频率、任务完成率、对上下文 token 的消耗做了可视化，这在优化记忆和成本时是极大的帮助。

有一点需要提醒：Pi Agent 因为绑定了桌面环境，对本地文件系统、浏览器、终端的访问层级非常深，安全性边界完全取决于技能包怎么约束自己的行为。所以从“agent安全”的角度看，安装不明来源的技能包前，务必用隔离环境跑一次全链路模拟，检查技能的每一步文件读写和指令执行是否越权。

2.4 Hermes Agent 与开放式框架：当 Skills 成为“最小知识单元”

还有一部分使用者倾向于 Hermes Agent 这类更开放的框架，它们的技能包本质上是由“元数据 + 指令模板 + 工具调用配置 + 参考样例”组成的复合目录。热词里提到的“她的 agent” 实际上是一些人把多角色人格、专属工作流封装成的能力集合体，这也要归入 agent skills 的范畴。框架开放的另一面是选择焦虑，所以我一般建议新手不要一上来就追新框架，先在 Claude Code 或 Codex 生态里把技能的编写逻辑跑通，再往开放架构迁移。

下表是我基于自己的经验整理的几个主流环境的横向对比，方便你在决定踩哪个生态之前先有个数据视角：

看完这张表你应该能理解，skills 的价值不是某一个工具的定义，而是一种组织知识和工具调用的通用模式。这个模式放到哪个 agent 平台上都能成立，区别只是写法、路径和触发规则的不同。

3. 从零手写一个技能包：格式、结构与一个可直接照抄的样例

很多人问“skills怎么写”，我建议把重点放在让技能包具备三个特性：可发现、可理解、可执行。可发现指元数据描述足够准确，agent 在决策时一眼就能判断何时使用它；可理解指正文里的步骤足够清晰，不会让模型在中间环节产生歧义；可执行指你提供的检查清单、代码片段、命令行工具都是直接能跑的，而不是抽象的“就像这样那样做一下”。

3.1 目录组织：一次把信息架构做对

我惯用的技能包目录组织方式大致这样：

my-skill/ ├── SKILL.md ├── scripts/ │ ├── validate_input.py │ └── process_data.py ├── templates/ │ ├── report_template.md │ └── code_snippet.py └── assets/ └── reference_table.md

SKILL.md是灵魂入口，scripts放可执行工具，templates放输出模板，assets放参考知识。这种分层最大的好处，是让模型在“需要看代码逻辑时”只打开 scripts 文件，而不是每次都去阅读庞大的完整知识库。很多新手把所有内容都塞进一个超长 markdown，导致加载慢、关键信息被淹没，这是首个常见反模式。

3.2 SKILL.md 的标准骨架与字段意义

一个合格的 SKILL.md 长这样：

--- name: frontend_performance_audit description: 对前端项目进行性能基线审计，输出关键耗时指标、资源加载分析和优化建议清单。 when_to_use: 页面交互明显卡顿、首屏加载过慢、需要性能优化前的基线数据收集时使用。 prerequisites: - node >= 18 - 已安装 lighthouse 依赖 version: 1.0.0 --- # 前端性能审计技能包 ## 执行流程 1. 启动本地开发服务器，确认项目可稳定访问。 2. 使用 lighthouse 对首页进行三次采样，并取中位数。 3. 分析主线程占用、网络请求队列与资源体积关系。 4. 输出优化建议，并按优先级排列。 ## 关键命令 ...

你注意 description 字段，它不能像写散文一样写长篇大论，而应明确覆盖“这个技能是做什么的”和“什么状态下应该拿起它”。代码模型在做工具匹配时是高度依赖语义相似度的，描述里的动词和名词越接近用户问题的真实表达，命中率就越高。when_to_use 这个字段在不少框架里被单列，虽本身不直接触达 prompt，但它是模型内部 classify 的重要辅助特征。相当于给技能装了一个“使用场景雷达”。

3.3 我在写技能时遵循的“三层设计法”

第一层是领域知识，包括术语、背景和约束，这个部分来源可以是官方文档、书籍、你自己踩坑沉淀的经验，作用是让模型不至于在基础概念上犯浑。第二层是操作流程，你要把专家做事时的步骤按时间顺序拆开，告诉模型先做什么、后做什么、什么情况下可以跳过某一步。第三层是质量验收标准，等于给输出定义一套可见的勾稽关系：报告里必须包含哪些指标、代码里必须有什么类型的 docstring、哪些 lint 规则必须通过。没有第三层，技能包只是知识的堆砌，有了第三层，它才变成可执行的“手艺”。

我自己最爱写的技能包，是用在“将零散需求转化为技术方案文档”这个场景上的。技能包里我强制模型按背景调研、约束分析、选型对比、风险识别、实施步骤、回滚方案六段式输出，并且给每一个技术选型强制补充至少两个备选项。测试下来，输出质量和稳定性提升非常明显，特别是在面对模糊需求时，模型的“即兴发挥”被流程约束住了，出来的方案一眼就能感觉到“有框架”。

3.4 一个可直接抄作业的轻量技能包

如果要说一个最通用的入门样例，我建议学会自己给代码库生成“变更影响分析技能”。在你的技能目录下建这样的SKILL.md：

--- name: change_impact_analysis description: Analyze the impact of code changes in a repository, produce a risk assessment and recommend necessary follow-up actions. when_to_use: after modifying core modules, before submitting a pull request, or when planning a large refactor. --- # Change Impact Analysis ## Goal Understand which components, tests, and documentation files are affected by uncommitted changes. ## Procedure 1. Read `git diff --name-only` to list changed paths. 2. For each changed file, determine its dependency relationships by inspecting import/require statements. 3. Search for usages of exported symbols across the repository. 4. Identify test files that cover affected modules. 5. Produce a markdown report with three sections: affected modules, suggested test commands, and risk notes. ## Report Format ```markdown ## Summary of Changes ## Affected Modules ## Suggested Test Commands ## Risk Notes

Quality Bar

• Must cover every changed file.
• Must list concrete test commands, not generic advice.
• Risk notes must explicitly distinguish breaking changes from compatible changes.

这个技能写起来不到三十行，但价值非常高。实际使用中，在准备 PR 之前手动唤起它，模型就会按上面的流程把 git diff 与模块依赖关系扫一遍，输出一份扎实的风险评估，大幅减少“改了 util 导致远端接口挂掉”这类低级事故。 ## 4. 安装与调用过程里真正需要重视的“暗坑” 有很多人搜索 claude code skills 安装、superpower skills 安装、图片生成skills安装包、latex排版skills，说明大家解决问题的思路没问题，但不少坑往往发生在安装和调用这一层。这里不重复那些一搜就有的安装命令，重点聊聊我踩过几次、且容易长期潜伏的问题。 ### 4.1 技能包永远不会被命中：先检查描述与触发词 最典型的症状就是：技能包装好了，目录位置也正确，但无论怎么问，agent 就是不理它，仿佛技能包不存在。绝大多数情况，问题出在技能元数据里的 description 描述不够“接近自然语言”。你要站在“模型如何匹配”的角度去想这件事：当用户说“帮我看看这部分改动会不会影响老接口稳定性”，模型脑子里把这句话向量化后，是在和一个 description 字段做匹配。如果你技能包里写的是“Analyze code impacts and risks”，那么很可能因为它不够具体而被其他更泛化的工具先抢答。 我的做法是用一组真实的用户问句去反向构造 description。例如同时列出“这个改动会影响什么”“重构后有哪些依赖需要迁移”“变更评估报告”，然后把它们的共性语义浓缩进 description 中。这样匹配精准度会明显提升，实测下来，技能调用率提高了非常多。 ### 4.2 技能内容过载：一次加载几十个技能会让模型“选择瘫痪” 我很理解大家在各种 skills 源网站上下载了大量看起来都很有用的技能包，装上去之后颇有一种“武装到牙齿”的安全感。但 agent 在执行任务时会在一次决策窗口里评估大量可用技能，如果你的技能列表过于庞大，模型会选择困难，甚至跳过最合适的那个，随机走向一个相关性一般的技能；或者明明不该触发技能的任务，它非要牵强地触发某个技能，导致输出变得拖沓。 推荐原则：**运行环境里保留的常用技能不超过 10 个，其他长期不用的移到归档目录**。就像人在工作台上放太多工具时反而降低效率一样，给模型保留一个“够用且清爽”的技能集，是所有工程化落地里性价比最高的一招。 ### 4.3 技能与 Harness 的版本耦合问题 热词里持续有人问 harness 和 agent 的区别，其实这个问题也会演化成技能包层面的坑。不同 harness 版本之间，工具执行的上下文注入方式、上下文窗口策略、多轮调用的状态保持机制都会变化。你为一个旧版本 harness 调优好的技能包，升级到新版本后可能表现大幅下滑。这种问题最隐蔽的地方在于：它不报错、不失败，只是输出变得中庸，像“一次性”回答，却又说不出哪里有毛病。 我缓解这个问题的办法是：每个技能包里显式写明最低兼容的 agent 版本，并对技能包做版本化语义管理。主版本不兼容时，不采取原地修改，而是另建一个新目录专门适配新版本，旧版本保留归档，以备在项目降级时快速回切。这个方法帮我在一次大版本升级中省下了整整一个下午的排查时间。 ### 4.4 技能包内部互相“污染”：命名空间与副作用管理 框架不会刻意隔离技能与技能之间的文件读写或变量命名。两个技能包如果 scripts 目录下都有 `utils.py` 或 `helper.py`，在部分执行机制下就可能出现互相覆盖的问题。此外，某个技能在自己的示例代码里定义了一个“长度为 1000 的临时列表”，但它的副作用是修改了全局配置里的 `OUTPUT_PATH`，另一个技能使用时就会读到错误的路径值。 所以我一般要求技能包遵循“**外部传入，内部输出**”的原则：所有路径必须由调用方注入，所有可执行脚本禁止修改环境变量，所有中间产物统一输出到当前工作目录下的独立命名空间。这样就不会因为临时状态而让两个技能产生隐式纠缠。 ## 5. 技能质量从“能跑”到“可信”：评测方法与调优思路 再往下走一步，就是很多人反复搜索的“skills怎么测评”。市面上会自动给出一些榜单和推荐，其实最好的评测起点是你的真实任务集。对技能的评测本质上是对“在受控条件下，技能包是否稳定地让模型输出更高水平结果”这件事做检验。 ### 5.1 一次性写死五个评测任务 我给自己的每个核心技能包都会配套一个评测集，里面包含五类任务： - 一个最简单的基础任务，验证最基本能力没有缺失； - 一个正常复杂度任务，对应技能的典型使用场景； - 一个边界任务，故意输入超出常规范围的数据，观察技能的容错； - 一个对抗任务，输入措辞模糊、结构混乱的需求，看技能能否把对话拉回正轨； - 一个组合任务，同时涉及多个技能包配合，验证彼此协作不冲突。 这五类任务跑下来，基本可以定性判断一个技能包是“偶有闪光”还是“稳定可靠”。迭代时优先修对抗任务和边界任务暴露的问题，因为正常任务的问题通常一眼就能看出来，而边界条件的坑往往藏得极深。 ### 5.2 量化指标的“温度”也要调 技能包评测不只看输出文本，我在 Pi Agent 和 Claude Code 上评测时，会重点记录三类量化指标：**技能触发准确率**（应当触发时正确触发/不应当触发时不误触发）、**任务完成度**（步骤覆盖率与质量标准达成率）、**token 消耗倍数**（使用技能前后的 token 增幅是否在合理区间）。一个技能如果让准确率提升了 30% 但 token 消耗翻了三倍，那在成本敏感的生产环境里未必划算。 调优时，优先调的是 `SKILL.md` 里的流程描述。模型是极度依赖文本暗示的实体，你写得越像一份内部专家给实习生的操作手册，它的执行就越像专家。举个例子：把“处理数据”改成“先去除空值与重复值，再对异常离群点做标记，然后归一化到 0-1 区间，最后输出统计摘要和缺失值报告”，模型的执行稳定性会直线上升。这个经验可以放到任何技能开发中反复使用。 ### 5.3 版本管理与团队协作的一些实践 实际做项目时，一个技能包往往不止你一个人维护。我推荐团队里把技能仓库当成代码仓库一样管理，实行 MR/PR 审查制。审查的重点不是看文笔，而是看“新增内容是否只是知识堆砌”“流程步骤是否出现了相互矛盾的顺序”“模板文件是否被无谓格式调整”。技能包里的 diff 和代码 diff 很像，一行描述用语的变化，在模型侧可能会引发出完全不同的分支行为，因此任何改动都要留痕、可回滚。 另外，如果团队内已有自己的 agent 应用，建议给技能包建一个 `catalog.json` 索引文件，把技能名、版本、负责人、最后评测时间、核心标签都放进去。这么做一方面方便 agent 在运行时快速读取可用技能列表，另一方面也是给团队留一份“能力地图”，避免重复造轮子。 ## 6. 常用技能源网站与选型建议：如何避开“看起来很强”的坑 最后聊一下很多人都关心的“从哪里获取技能包”。热词里提到常用 skills 源网站、图片生成skills安装包、latex排版skills。网上的技能市场逐渐多起来，但质量参差不齐。我自己的筛选标准很朴素：先看技能包的 `SKILL.md` 是否结构完整，再看是否提供评测样例和版本记录，最后看维护频次。一个常年不更新的技能包，除非解决的问题极其稳定不变（比如“文本标准化格式转换”），否则大概率会随着底层模型能力变化而逐渐失效。 针对热门方向，我分别给一点选型心得： - **图片生成 skills 安装包**：优先选那些不仅提供 prompt 模板，还把负面 prompt、画面比例参数、后处理流程也封装进去的技能包。安装后先用自己的固定 prompt 做对照实验，看技能包是否真的提高了出图稳定性，避免只是换了一批花哨提示语。 - **latex 排版 skills**：核心不在“能生成 latex”，而在“能否符合目标期刊模板规范、是否处理了跨页图表和参考文献压缩”。我建议选那些自带论文实时编译校验步骤的技能包，它能在生成最终 pdf 前自动拦截格式错误。 - **superpower skills**：这套技能以“组织任务执行流程”见长，非常像给智能体装了一个项目管理方法论。但实话说，它更适合做规划层，不适合做专业领域执行层，通常我会把它和具体的领域技能配合使用，而不是单独依赖它。 所谓“好用的 skills”，最终都要经过你自己的任务集磨砺才能真正好用。别人的金技能包拿到你的场景可能水土不服，我的建议是：把第三方技能包当作起点模板，而不是最终答案。下钻到核心步骤里，把与你实际业务流程不符的部分改掉，把缺失的验收标准补上，这个技能包才能像一件贴合你手掌的工具，而不是一把所有人都攥过、但与谁都未必贴合的通用旋钮。 这个领域迭代极快，我也还在持续替换自己手头技能库里的过时方案。每次模型能力大幅度升级时，我会系统性重测一遍技能集，把那些已经可以被模型默认能力覆盖的“廉价技能”淘汰掉，把真正需要专家方法论的技能做深做实。从当前的趋势来看，agent 与人协同的方式会越来越像“专家工具箱”，而能把技能包写好、评估好、管理好的人，会是这个时代定义自己生产力边界的那批人。