refactor: unify agent package authoring skills

2026-09-23 12:32:00 +08:00
parent 24e9621574
commit 15631ca4dd
11 changed files with 183 additions and 128 deletions
@@ -0,0 +1,32 @@
+---
+name: agent-package-authoring
+description: >
+  Create, update, or review Agent Package instructions, capabilities, Skill declarations,
+  and evolution.resultContract. Use when authoring or evolving agent-package.json and
+  its referenced content. Routes to focused references; performs local editing and checks,
+  while Agent Workforce owns full Bundle validation and publication.
+---
+
+# Agent Package Authoring
+
+读取当前 `agent-package.json`、入口 instructions、已声明 Skills 与相关运行约束，
+以实际能力和可验证交付为依据。保留用户已有修改，按任务范围选择流程，不默认重写整个包。
+
+## 按任务读取
+
+- 创建或调整角色职责、工作流、产出、约束和停止条件：[Instructions](references/instructions.md)。
+- 补全或审查 `agent.capabilities`：[Capabilities](references/capabilities.md)。
+- 新建 Package Version，或修改核心能力、Skills、instructions、验收与交付逻辑：
+  **必须检查** [Result Contract](references/result-contract.md)，按真实结果生成或更新；
+  没有可验证交付时允许缺失，不编造结果码。
+- 将 Skill 纳入 Package 或调整其声明：[Skill 集成](references/skills.md)。
+  Skill 内容交给通用 `skill-creator`，不在这里重复开放规范。
+- 添加大资产、压缩交付或处理包大小错误：[资产大小与交付](references/asset-packaging.md)。
+
+## 共同约束与交接
+
+- 保持当前 workspace 与 Git ref；不修改 `.git`、Wayflow 保留文件或任务范围外的 Package 字段。
+- 使用当前 schema 和 Host 契约，不新增私有字段；schema 迁移交由版本工作流处理。
+- 只声明已实现的行为和真实依赖，不把能力描述当成已获授权的权限。
+- 优先运行现有校验与最小相关测试；缺少工具时检查 JSON、路径、引用和内容一致性，说明验证范围。
+- 报告改动、验证结果及阻塞项，交回版本工作流执行完整 Bundle 校验；不自行提交或发布 Version。
@@ -0,0 +1,40 @@
+# 资产大小与交付
+
+## 检查实际交付内容
+
+Agent ZIP 包总大小不得超过 500 MB（500,000,000 字节），按最终 ZIP 文件的实际字节数校验。
+大小门禁集中在 Package 归档及上传/下载流程；候选 Git 快照不设单文件、展开总量或文件数量门禁。
+这是 Package 实现限制，不是 Agent Skills 开放规范；Host 仍会独立校验，以当前环境契约为准。
+
+检查整个 Package 生成的 ZIP，包含递归展开的子模块，不能只统计当前 Skill。
+不要把原始资产大小或展开后的总量当成 ZIP 大小，也不要假设 `.gitignore` 能排除已跟踪文件。
+
+## 必需大资产的处理
+
+用户要求随包携带的资产必须保持完整，不擅自删除、裁剪或改成远程下载。
+单个 `assets/` 文件超过 16 MiB（16,777,216 字节）时，发出非阻断警告，列出路径和实际大小，
+并推荐评估无损压缩后随包携带、使用时解压。恰好 16 MiB 不警告；资产仍可原样携带，
+不因这条建议强制压缩或拒绝校验。
+如果最终 ZIP 接近或超过额度且消费流程允许使用前解压，可评估无损压缩；
+ZIP 本身已有压缩，嵌套 gzip 不保证进一步缩小包，必须比较最终 ZIP 大小；小文件和无法有效压缩的资产不必强行采用此方案。
+
+- 可用 Python 标准库 gzip 生成 `.gz`；固定 `mtime=0`，不嵌入机器路径等可变元数据。
+- 验证解压后的字节与原文件完全一致，记录或保留原始文件的 SHA-256。
+  已有预期哈希和业务结果不得为了通过测试而改写。
+- 更新消费脚本，将文件解压到 Wayflow 注入的 Runtime 下的可写目录，再调用原有处理流程。
+  不写入安装后的 Skill 目录，不使用开发机绝对路径；Runtime 缺失时明确报错。
+- 更新 `SKILL.md`、references、脚本及相关文件清单中的引用，区分包内压缩资产和运行时解压路径。
+  Skill 内资产仍不重复声明为顶层 `resources[]`。
+- 使用压缩资产替换方案时，确认交付快照中不再重复包含原文件，并检查最终 ZIP 大小和
+  运行时解压所需空间。运行使用该资产的最小代表性流程，验证既有业务结果。
+
+如果压缩后仍超限，或使用方必须直接读取包内未压缩文件，报告实际大小及消费约束，
+交由 Package/平台工作流处理资源额度；不要在创建 Skill 的任务中擅自修改平台限制。
+
+## Git submodule 交接
+
+候选包读取父仓库 gitlink 锁定的子模块 commit，不读取子模块当前分支的未提交修改。
+按当前任务授权和版本工作流提交子模块修改，再更新父仓库 gitlink；不自动推送远端。
+仅删除本地文件或只在子模块提交而未更新父仓库引用，都不能修复旧锁定快照。
+交接时报告压缩前后字节数、无损与业务验证结果、锁定提交更新情况，以及尚待执行的
+Agent Workforce 完整 Bundle 校验。
@@ -1,13 +1,3 @@
---
-name: agent-package-capabilities-create
-description: >
-  为当前 Agent Package 设计、补全或审查 agent.capabilities 声明。
-  Use when an existing agent-package.json has empty, vague, duplicated, or inconsistent
-  capabilities, including when they do not match instructions, Skills, requirements,
-  runtime, or actual deliverables. This skill performs local authoring and checks only;
-  Agent Workforce remains responsible for authoritative validation and publication.
---
-
 # Agent Package Capabilities Create

 只完善当前 Agent Package 的 `agent.capabilities`。不要借此修改 Agent Key、role、title、
@@ -24,7 +14,7 @@ description: >
 ## 2. 设计 Capabilities

 创建或大幅重写前读取
-[Agent Capabilities 格式](references/agent-capabilities-format.md)。
+下方的格式约定。

 每条 capability 应同时满足：

@@ -57,3 +47,51 @@ description: >
 - 本地验证能力不存在时，完成 JSON、重复项、空值和 Package 内容一致性检查，不因缺少 Workforce tools 阻止本地修改。

 完成后报告改动和本地检查结果，明确标记“待 Agent Workforce 完整 Bundle 与发布校验”。
+
+# Agent Capabilities 格式
+
+Capability 是供任务分派、Package 审查和运行时理解使用的稳定能力声明。它回答“这个 Agent
+可以可靠交付什么”，而不是“这个 Agent 是谁”或“它能访问什么”。
+
+## 推荐结构
+
+优先写成：
+
+```text
+<动作> + <对象或领域> + <可验证结果或关键边界>
+```
+
+示例：
+
+- `评审 TypeScript 服务架构，输出迁移步骤、关键风险与回滚方案`
+- `把产品需求拆解为可执行工程任务，并标注依赖、验收条件和责任边界`
+- `诊断持续交付故障，定位失败阶段并提供可复现证据和恢复建议`
+
+不推荐：
+
+- `技术能力强`：没有对象或结果。
+- `负责所有工程工作`：范围无限且无法验证。
+- `可以访问生产数据库`：这是权限，不是能力。
+- `熟悉 Git、Node.js、Docker`：只是工具清单，没有说明交付结果。
+- `CTO`：重复 role/title。
+
+## 完善步骤
+
+1. 从 instructions 提取长期职责和完成条件。
+2. 从每个 Skill 提取它实际支持的可复用任务，不照抄 Skill 名称。
+3. 从 requirements 和 runtime 判断哪些工作真实可执行，删除缺少依赖的承诺。
+4. 合并同义条目；当任务对象、产出或风险边界明显不同时拆分。
+5. 用一个真实任务检验每条能力：只读该条时，调度者应能判断是否适合分派。
+
+## 质量门槛
+
+- **真实**：当前 Package 已具备所需指引、Skill、依赖和权限边界。
+- **具体**：包含动作以及对象、领域、结果或约束中的至少一项。
+- **可分派**：能映射到一类实际任务，而非人格、愿景或状态。
+- **可验证**：交付物或完成条件可以被审查。
+- **不越权**：不把请求的 capability、permission 或 adapter 写成已授予事实。
+- **低重叠**：每条承担清楚的任务边界。
+
+条目数量和长度必须服从当前 Package Schema。没有更严格要求时，优先保留少量
+高信息密度条目，不为追求数量拆成碎片。
+
@@ -1,13 +1,3 @@
---
-name: agent-package-instructions-create
-description: >
-  在当前 Agent Package 中创建或修改 instructions。Use when asked to define or
-  update an Agent's role, operating workflow, outputs, constraints, stop conditions, or
-  instructions/AGENTS.md, and to keep an existing manifest instruction entry aligned.
-  This skill performs local authoring and checks only; Agent Workforce remains responsible
-  for authoritative validation and publication.
---
-
 # Agent Package Instructions Create

 只在当前 Agent Package 中创建或修改 Agent instructions。不要在这里创建
@@ -23,7 +13,7 @@ Agent-scoped Skill、runtime lifecycle、company Agent 或发布流程。
 ## 2. 设计 Instructions

 创建或大幅重构前读取
-[Agent Instructions 格式](references/agent-instructions-format.md)。
+下方的格式约定。

 Instructions 必须覆盖：

@@ -57,3 +47,44 @@ Instructions 必须覆盖：
 - 本地验证能力不存在时，至少检查 JSON、入口路径、文件类型和内容一致性，不因缺少 Workforce tools 阻止本地修改。

 完成后报告改动和本地检查结果，明确标记“待 Agent Workforce 完整 Bundle 与发布校验”。
+
+# Agent Instructions 格式
+
+Agent instructions 是 Package 的长期运行边界，不是单次任务答案。使用清晰的 Markdown
+标题组织内容，并根据 Agent 职责保留以下部分。
+
+## 最小内容
+
+```text
+# Role
+# Responsibilities
+# Workflow
+# Outputs
+# Constraints
+# Stop Conditions
+```
+
+- `Role`：说明 Agent 身份、服务对象和目标。
+- `Responsibilities`：列出负责事项与明确不负责事项。
+- `Workflow`：描述稳定执行顺序、检查点和失败处理。
+- `Outputs`：规定可验证产出、格式和完成条件。
+- `Constraints`：记录权限、数据、工具、安全和环境边界。
+- `Stop Conditions`：说明何时停止、升级、报告阻塞或请求输入。
+
+可以按实际职责调整标题，但不能省略对应语义。
+
+## 与其他 Package 内容的关系
+
+- Instructions 说明整体行为，不重复 Agent-scoped Skill 的详细步骤。
+- Skill 负责可复用的具体任务流程，触发条件写入各自 `SKILL.md`。
+- Instructions 只能引用 Package 中真实存在且 manifest 允许的能力。
+- runtime prepare/healthcheck、资源和 requirements 的字段及引用方式以当前 Package
+  Schema 为准，不在 instructions 中另造声明机制。
+
+## 写作规则
+
+- 使用直接、可执行的指令，避免口号和人格化空话。
+- 明确默认行为、异常路径和完成标准。
+- 不写 token、密码、私钥、机器绝对路径或临时 workspace 标识。
+- 不承诺未声明权限、工具、外部系统或自动发布能力。
+
@@ -1,15 +1,6 @@
---
-name: agent-package-result-contract-create
-description: >
-  基于当前 Agent Package 的真实能力、Skills、instructions 与验收步骤，自动生成或更新
-  evolution.resultContract，使 Wayflow Host 能生成受控、可跨设备消费的包演进证据。
-  Use when creating a new Agent Package Version, evolving a Package, or changing its
-  core capability, workflow, validation, or delivery criteria.
---
-
 # Agent Package Result Contract Create

-业务人员不编辑 `resultContract` 或 JSON。本 Skill 负责把 Package 已有、可验证的交付结果转换为
+业务人员不编辑 `resultContract` 或 JSON。本流程 负责把 Package 已有、可验证的交付结果转换为
 Host 可校验的受控结果码；它不是添加营销指标、虚构归因或记录用户内容的入口。

 ## 1. 读取可证明的 Package 事实
@@ -51,8 +42,8 @@ Host 可校验的受控结果码；它不是添加营销指标、虚构归因或

 ## 3. 写入 Manifest

-该字段只属于 `wayflow.agent-package/v4`。若当前 Package 是 v3，先按照 Host 当前推荐
-Contract 将新的草稿 Version 迁移到 v4，再在 `agent-package.json` 的 `evolution` 对象中写入或更新：
+该字段只属于 `wayflow.agent-package/v4`。若当前 Package 是 v3，先交回版本工作流，
+按照 Host 当前推荐 Contract 将新的草稿 Version 迁移到 v4，再在 `agent-package.json` 的 `evolution` 对象中写入或更新：

 ```json
 "resultContract": {
@@ -63,7 +54,7 @@ Contract 将新的草稿 Version 迁移到 v4，再在 `agent-package.json` 的
 ```

 保留现有 `evolution.mode`、`policy`、`evaluations`，不要借此变更 Package 身份、版本、权限、Skills
-或其它无关字段。若需要新增或修改这些事实，应先完成对应的 Package 编辑，再重新运行本 Skill。
+或其它无关字段。若需要新增或修改这些事实，应先完成对应的 Package 编辑，再重新执行本流程。

 ## 4. 生成后自检

@@ -0,0 +1,13 @@
+# Package Skill 集成
+
+使用通用 `skill-creator` 编写 Skill 内容，本流程只处理其与当前 Package 的集成。
+
+- Skill 位于 `skills/<name>/`，只属于目标 Agent，不创建 company Skill 或修改其他 Agent。
+- 按当前 schema 更新 `agent-package.json.skills[]`；manifest name、目录名和 frontmatter name 一致。
+- `path` 指向 Skill 目录而非 `SKILL.md`；声明唯一，入口及引用文件真实存在。
+- `required`、`visibility` 按 schema 和任务要求设置，不写入 Skill frontmatter。
+- Skill 内部 references、scripts、assets 由 Skill 声明覆盖，不重复加入顶层 `resources[]`。
+- 不借此修改 Package 身份、权限或发布状态；必要的 instructions、capabilities 和 resultContract
+  调整按主入口中的对应流程处理。
+- 检查路径穿越、秘密信息、机器绝对路径和不受目标 Package 支持的文件类型；
+  运行配套脚本及代表性用例，最后回到版本工作流做完整 Bundle 校验。
@@ -1,4 +0,0 @@
-interface:
-  display_name: "Agent Package Capabilities Create"
-  short_description: "完善 Agent Package 的 capabilities 声明"
-  default_prompt: "Use $agent-package-capabilities-create to design precise capabilities for the current Agent Package."
@@ -1,46 +0,0 @@
-# Agent Capabilities 格式
-
-Capability 是供任务分派、Package 审查和运行时理解使用的稳定能力声明。它回答“这个 Agent
-可以可靠交付什么”，而不是“这个 Agent 是谁”或“它能访问什么”。
-
-## 推荐结构
-
-优先写成：
-
-```text
-<动作> + <对象或领域> + <可验证结果或关键边界>
-```
-
-示例：
-
- `评审 TypeScript 服务架构，输出迁移步骤、关键风险与回滚方案`
- `把产品需求拆解为可执行工程任务，并标注依赖、验收条件和责任边界`
- `诊断持续交付故障，定位失败阶段并提供可复现证据和恢复建议`
-
-不推荐：
-
- `技术能力强`：没有对象或结果。
- `负责所有工程工作`：范围无限且无法验证。
- `可以访问生产数据库`：这是权限，不是能力。
- `熟悉 Git、Node.js、Docker`：只是工具清单，没有说明交付结果。
- `CTO`：重复 role/title。
-
-## 完善步骤
-
-1. 从 instructions 提取长期职责和完成条件。
-2. 从每个 Skill 提取它实际支持的可复用任务，不照抄 Skill 名称。
-3. 从 requirements 和 runtime 判断哪些工作真实可执行，删除缺少依赖的承诺。
-4. 合并同义条目；当任务对象、产出或风险边界明显不同时拆分。
-5. 用一个真实任务检验每条能力：只读该条时，调度者应能判断是否适合分派。
-
-## 质量门槛
-
- **真实**：当前 Package 已具备所需指引、Skill、依赖和权限边界。
- **具体**：包含动作以及对象、领域、结果或约束中的至少一项。
- **可分派**：能映射到一类实际任务，而非人格、愿景或状态。
- **可验证**：交付物或完成条件可以被审查。
- **不越权**：不把请求的 capability、permission 或 adapter 写成已授予事实。
- **低重叠**：每条承担清楚的任务边界。
-
-条目数量和长度必须服从当前 Package Schema。没有更严格要求时，优先保留少量
-高信息密度条目，不为追求数量拆成碎片。
@@ -1,4 +0,0 @@
-interface:
-  display_name: "Agent Package Instructions Create"
-  short_description: "创建或更新 Agent Package instructions"
-  default_prompt: "Use $agent-package-instructions-create to create or update instructions in the current Agent Package."
@@ -1,39 +0,0 @@
-# Agent Instructions 格式
-
-Agent instructions 是 Package 的长期运行边界，不是单次任务答案。使用清晰的 Markdown
-标题组织内容，并根据 Agent 职责保留以下部分。
-
-## 最小内容
-
-```text
-# Role
-# Responsibilities
-# Workflow
-# Outputs
-# Constraints
-# Stop Conditions
-```
-
- `Role`：说明 Agent 身份、服务对象和目标。
- `Responsibilities`：列出负责事项与明确不负责事项。
- `Workflow`：描述稳定执行顺序、检查点和失败处理。
- `Outputs`：规定可验证产出、格式和完成条件。
- `Constraints`：记录权限、数据、工具、安全和环境边界。
- `Stop Conditions`：说明何时停止、升级、报告阻塞或请求输入。
-
-可以按实际职责调整标题，但不能省略对应语义。
-
-## 与其他 Package 内容的关系
-
- Instructions 说明整体行为，不重复 Agent-scoped Skill 的详细步骤。
- Skill 负责可复用的具体任务流程，触发条件写入各自 `SKILL.md`。
- Instructions 只能引用 Package 中真实存在且 manifest 允许的能力。
- runtime prepare/healthcheck、资源和 requirements 的字段及引用方式以当前 Package
-  Schema 为准，不在 instructions 中另造声明机制。
-
-## 写作规则
-
- 使用直接、可执行的指令，避免口号和人格化空话。
- 明确默认行为、异常路径和完成标准。
- 不写 token、密码、私钥、机器绝对路径或临时 workspace 标识。
- 不承诺未声明权限、工具、外部系统或自动发布能力。
@@ -46,6 +46,9 @@ git submodule update --init --recursive

 ## 技能与角色维护

+`.agents/skills/agent-package-authoring` 是 Package 编写的统一入口，按需读取
+references 中的 instructions、capabilities、result contract、Skill 集成和资产交付规则。
+
 `.agents/skills/skill-creator` 提供通用 Skill 创建、更新和校验流程；其
 `upstream/agentskills` 子模块保留完整的 Agent Skills 规范与参考工具。