企业官网建设流程全解析

Agnes Harness（简称 AGH）是一个面向 Forward Deployed Engineering（FDE）的可插拔 Agent 框架，它的 Skills 系统可以把项目约定、检查步骤、常用方法沉淀为可复用的技能文件，让 Agent 在每次任务中自动按团队的标准来干活。这篇 Agnes Harness Skills 完整指南带你从零创建一个 Skill，理解它的来源优先级、信任审核与启用流程，并学会在 Web 和命令行中管理这些技能资产。

📖 为什么需要 Skills：让 Agent 记住团队打法

用过大模型 Agent 的人都遇到过同样的问题：每个会话都要重新交代一遍"我们代码怎么审查、文档怎么组织、提交前跑哪些检查"。Skills 就是解决这个痛点的机制——把一次性的口头交代，变成磁盘上可复用、可审核、可版本管理的技能文件。

在 AGH 里，一个 Skill 本质上是一份带元信息的 Markdown 说明（SKILL.md）：

• name：技能名，Agent 靠它被点名调用
• description：一句话描述适用场景，Agent 靠它判断"这个任务该不该用我"
• 正文：具体的操作步骤、边界约束（例如"只提建议，不写文件"）

需要特别理解的一点：Skill 提供的是任务说明与知识，不等于执行权限。AGH 会先发现候选、审核版本、解析同名胜出项，再向会话暴露可用内容——不能只因为磁盘上存在文件，就认为模型已经读取了它。这套"发现 → 信任 → 启用 → 就绪"的生命周期，是 AGH Skills 与普通提示词模板最大的区别。

🚀 快速上手：创建第一个工作区 Skill

Skill 不需要写在 AGH 源码库里，而是放在你自己的项目里。在目标项目创建.agh/skills/review-notes/SKILL.md，内容形如：

--- name: review-notes description: 只读整理项目说明中的不一致之处 --- 先读取 README 与相关说明，列出互相冲突的描述和对应文件。 只提出修改建议，不写文件，不安装依赖。

frontmatter 的解析与校验规则（名称最长 128 字符、描述最长 1024 字符、静态 YAML 检查）在 frontmatter.ts 中实现。

创建之后，在 Web 端为该项目创建会话，进入设置 → Skills管理，刷新对应工作区，核对来源和内容修订（revision），再点击"启用"。Web 会先完成版本审核，不再单独显示信任动作；开关跟随你的启用请求——请求过启用它就保持打开，即使 Skill 没能加载起来，失败原因也会显示在同一行。

用命令行同样可以查看和管理底层状态：

node packages/cli/dist/local/agnes.mjs resources list --kind skill node packages/cli/dist/local/agnes.mjs skills refresh --root-key workspace-agnes --workspace-id WORKSPACE_ID node packages/cli/dist/local/agnes.mjs skills trust SKILL_RESOURCE_ID REVISION trusted node packages/cli/dist/local/agnes.mjs resources enable SKILL_RESOURCE_ID --expected-revision REVISION

确认trust=trusted、desired=enabled、actual=ready以及winner都符合预期后，在会话里明确说"使用 review-notes 整理项目说明"即可触发。当会话中明确提名且唯一匹配一个可用 Skill 时，Host 有预加载路径（见 skill-preload.ts）；模糊的描述则不是确定性的激活语法，此时 Agent 会依据技能目录自行匹配并调用skill_read工具读取。

🗂️ Skills 从哪来：7 个来源与优先级规则

AGH 会从多个磁盘位置发现 Skill，默认优先级如下（数字越大越优先，定义在 discover.ts 的FIVE_SKILL_ROOTS）：

几个关键行为值得注意：

• 同名解析：名字按去除首尾空白、忽略大小写分组；非删除候选按优先级降序排列，同分再按sourceId排序，胜出者称为winner。
• 不会自动降级：高优先级项未信任、被拒绝或停用时，不会仅因不可用就自动选择低优先级项——这是刻意设计，避免"你以为在用的技能"悄悄换了个版本。
• 多工作区隔离：每个会话按自己的工作区读取，不用 worker 启动目录替代；WORKSPACE_ID是 64 位十六进制标识，不要把路径或别的会话 ID 填进去。
• 修改要重新审核：磁盘内容改变后需要重新核对 revision 与信任，刷新失败留下的 stale 内容不能当作本次扫描成功。

⚖️ 同名技能冲突：如何调整优先级

当工作区技能（500）和用户技能（400）同名时，想让低优先级的一方胜出，可以在 Web 的设置 → Skills中打开 Skill 详情，查看来源、当前 winner、被覆盖候选和有效优先级，然后在"同名覆盖优先级"输入 50–500 的整数并保存。

比如要把AGH_HOME/skills的用户候选顶掉工作区候选，可以把工作区项降到 350。注意两点：

1. 它只改变该 resourceId 在当前 profile 中的持久覆盖，不改文件内容，也不会启用 Skill；
2. 保存成功后还要重新查看 winner 与 actual，若新 winner 尚未启用，需审核后再启用。

需要恢复默认时，通过 Node 客户端传入priority: null（client.skills.prioritySet）。这些管理动作需要 admin authority 与resources.skills.write权限，合同定义见 resource-control.ts，持久控制与删除标记在 skills.ts。

🧩 用 Skill Helper 批量导入：GitHub 仓库、ZIP、本地目录

手写之外，AGH 随版本附带了官方的@agnes/skill-helper插件，在 Web 的插件管理页可以看到它（默认安装并启用）：

Skill Helper 提供四个工具（skill_helper_import/skill_helper_creator/skill_helper_create/skill_helper_install），支持：

• 导入本地 Skill 目录（离线即可）
• 导入 GitHub 公共仓库或子目录（需要网络，走受限的公共网络策略）
• 导入本地 ZIP 文件或 HTTPS 原始 Markdown 清单
• 从模型输出生成新的 Skill 文件，可附官方 skill-creator 编写指引

它的安全边界同样值得了解：不覆盖已有不同内容的技能、不支持私有仓库登录、不执行第三方脚本、归档包超过 2 MiB 限制时需改走本地 ZIP 导入。详细说明见 skill-helper/README.md。

🛠️ 进阶：让插件在运行时贡献 Skill

如果你在做插件开发，受信插件可以声明inject: ['skills']，在apply阶段注册运行时技能：

ctx.skills.register({ name: 'review-notes', description: '只读整理说明冲突', body: '读取相关说明，列出矛盾与证据，不修改文件。', })

register()返回 disposer，注册随调用方 fiber 清理；动态集合用registerProvider，数据变化后调用control.invalidate()。与磁盘技能不同，运行时贡献不进入 trust/desired 管理流程，其信任来自受信代码本身。更多插件开发内容见 插件开发文档。

🧹 日常维护与安全须知

最后几个实操要点，能帮你避免大部分运维坑：

• 停用 vs 删除：需要暂时停用时选"停用"。"永久删除"会删除选中的 Skill 目录及其中全部文件，不是移入回收站，且删除操作受理后不支持取消、重启也不是撤销。
• 用户目录是共享的：~/.claude/skills等目录可能被其他应用共用，删除前先想清楚影响面。
• 操作要留痕：保存 operation ID 并等待状态succeeded再核对结果；API 返回 receipt 仅表示受理。
• 失败不要盲重试：报告SKILL_REMOVAL_PENDING时，条目已被阻止重新启用，排除文件占用等原因后再显式重试。
• 扫描限额：每个来源根最多 128 个条目、单文件 256 KiB、根目录总量 2 MiB，超限的候选会被跳过并记录原因，而不是让整个扫描失败。

Skills 的运行时行为——技能目录（catalog）如何注入提示词、skill_read与skill_read_file工具的分页读取——在 runtime.ts 中实现；候选注册与同名胜出解析在 resource-control-runtime/src/skills.ts。

📚 延伸资料

• 官方 Skills 指南：docs/guide/skills.zh-CN.md
• Skill 发现逻辑源码：packages/base/extensions/skills/src/discover.ts
• 技能预加载：packages/host/src/resources/skill-preload.ts
• 插件开发总览：docs/develop/plugins.zh-CN.md
• 包管理生命周期（安装/信任/更新/回滚）：docs/guide/packages.zh-CN.md

把团队的检查清单、代码规范、排障手册写成 Skill 放进.agh/skills/，从下一个会话开始，你的 Agent 就会带着团队的"肌肉记忆"开工——这正是 Agnes Harness Skills 的核心价值：方法论不再依赖口口相传，而是变成可复用、可审核、随项目分发的技能资产。