跳转至

16 · Skills 与 Teams Catalog

Skill CatalogCompany LibraryProvenanceTrust LevelTeam Template

一句话结论： Paperclip 把 Skill 分成只读 Catalog 与 Company Library 两层：安装是带 provenance/hash 的复制，运行时再按 Adapter materialize；Team Catalog 则把 Agent、项目、任务、Routine 和 Skill 依赖打包成可预览、可治理的组织模板。

1. Skill 不是 Prompt 片段，而是可管理资产

一个 Skill 是目录：

my-skill/
├── SKILL.md
├── references/   # 可选
├── scripts/      # 高信任，可选
└── assets/       # 可选

SKILL.md frontmatter 至少包含：

name: my-skill
description: >
  做什么，以及何时使用/何时不要使用。

Description 不是营销文案，而是 Agent 的路由索引：先只把 name/description 暴露给运行时，Agent 判断相关后再读取全文。

2. 两层 Store

flowchart LR
  SRC["packages/skills-catalog/catalog/**"] --> BUILD["build + validate manifest"]
  BUILD --> CAT["Read-only Catalog\ngenerated/catalog.json"]
  CAT -->|"install with provenance"| LIB["Company Skills Library\nDB + files/versions"]
  EXT["GitHub / skills.sh / URL / local scan"] -->|"validate + pin + import"| LIB
  LIB --> SELECT["Agent skill selection/policy"]
  SELECT --> MAT["Runtime materialization"]
  MAT --> ADAPTER["Adapter-specific discovery"]

Catalog 是货架，Company Library 是已安装、可编辑、可版本化的副本。安装后不会让运行时直接读 package 内原文件。

3. Catalog 的构建期契约

@paperclipai/skills-catalog 从目录生成 manifest，验证：

  • key/slug/name 唯一；
  • frontmatter 合法；
  • file inventory；
  • category/recommended roles；
  • trust level；
  • compatibility；
  • content hash；
  • bundled/optional kind；
  • package/artifact 完整性。

生成 manifest 而不是运行时遍历目录，能让发布包内容和 UI 展示稳定，并在 CI 中提前发现坏 Skill。

4. Trust Level 由内容推导

Level 文件内容 风险
markdown_only 只有 Markdown 最低
assets Markdown + 图片/PDF/静态资源 中等
scripts_executables 含 shell/JS/Python/TS 等可执行文件 最高

Trust level 不能由 Skill 自己声称，builder 扫描 file inventory 推导。

外部来源只允许 markdown/assets；带可执行脚本的外部 Skill 默认拒绝，只有受审查的 first-party bundled catalog 可携带 scripts。

这防止“安装一份教程”隐式变成“允许第三方代码在 Agent 主机执行”。

5. 外部来源与不可变引用

Company Skill source 类型可包括：

  • catalog；
  • GitHub；
  • skills.sh（最终解析到 GitHub）；
  • raw URL；
  • local path / in-app create。

Git-backed source 必须解析为固定 40 字符 commit SHA，不能长期指向移动 branch。Library 保存：

  • origin type/ref；
  • resolved commit；
  • upstream content hash；
  • installed package/catalog version；
  • source badge；
  • local drift。

这样“更新”是显式操作，而不是下轮 Agent 运行时悄悄拉到新内容。

6. 导入管线

flowchart TD
  INPUT["GitHub URL / repo ref / raw URL / project scan"] --> RESOLVE["规范化来源 + allowlist/commit pin"]
  RESOLVE --> FETCH["受限 fetch / enumerate SKILL.md"]
  FETCH --> INV["构建 file inventory"]
  INV --> TRUST{"derive trust level"}
  TRUST -->|external executable| REJECT["reject"]
  TRUST -->|allowed| VALID["frontmatter + compatibility + size/path checks"]
  VALID --> PREVIEW["conflict / skip / install preview"]
  PREVIEW --> DB["create company skill + version + provenance"]

Project scan 只在注册 workspace root 内寻找约定路径，不能把整台机器当 Skill 来源。

7. Company Library 生命周期

Company Skill 是一个小型产品对象，支持：

  • create/update/delete；
  • file inventory/content；
  • versions 与 revision history；
  • upstream update status；
  • drift detection；
  • install update / force；
  • reset to origin；
  • audit；
  • fork；
  • star/comment；
  • sharing scope。

Sharing scope 可为 private/company/public link。可见性仍受 Company/actor 授权，public link 也需要专门 token，而不是把数据库 row 全公开。

8. Version、Update、Drift

origin hash       = 安装时上游内容
installed hash    = 当前 Library 内容
latest upstream   = 重新解析后的上游内容

由三者可判断：

  • 未修改、无更新；
  • 未修改、有上游更新；
  • 本地 drift、上游未变；
  • 本地 drift + 上游也变，自动 update 可能冲突。

Force update/reset 都是显式、可审计动作，避免覆盖 Company 自定义说明。

9. Fork 的语义

Fork 创建独立 Skill：

  • 新 ID/key/slug；
  • 复制完整 file inventory；
  • 保存 fork source；
  • 原 Skill fork count 增加；
  • 后续版本与上游独立。

适合“基于 catalog 深度定制”，比直接修改已安装 upstream copy 更容易理解 provenance。

10. Skill Policy 与 Agent Selection

安装不等于所有 Agent 自动获得。Company policy 和 Agent desired selection 决定：

  • 哪些角色/Agent 可用；
  • auto/manual assignment；
  • deny/allow；
  • sync mode；
  • runtime snapshot；
  • trust/capability compatibility。

运行前把 selection 固化成快照，避免 Skill 在长 run 中途更新导致上下文漂移。

11. Runtime Materialization

Heartbeat 选择 Skill 后：

  1. 读取 Library 当前版本/file inventory；
  2. 校验 policy/trust；
  3. 复制到受控 runtime skills directory；
  4. 清理危险路径/权限；
  5. 交给 Adapter 的 skills integration；
  6. 在 context snapshot 记录选择。

Adapter 可能用 symlink、global skills dir 或 CLI config，但不能让 Library 的 DB 记录和磁盘版本静默不一致。

12. Skill Test

Skill Studio 支持：

  • test input；
  • run template；
  • isolated test run；
  • status/cost summary；
  • saved versions/results。

Test 使用专用 run/key scope 和隔离策略，防止评测 Skill 时对真实 Issue、工具或生产 workspace 产生副作用。

13. Team Catalog 的目录结构

一个 Team 模板可以包含：

team-name/
├── TEAM.md
├── .paperclip.yaml       # 可选声明
├── agents/
│   ├── cto/AGENTS.md
│   └── qa/AGENTS.md
├── projects/
│   └── project/PROJECT.md
│       └── tasks/.../TASK.md
└── skills/               # 可选 vendored local skill

它描述的不是一个 Agent persona，而是一组相互关联的组织资源。

14. Team Manifest 的内容

Catalog builder 提取：

  • Team identity/kind/category/trust/compatibility；
  • Agents 与 instructions；
  • Projects 与 starter tasks；
  • Routines/recurring tasks；
  • Skill requirements：catalog、existing、vendored local；
  • env inputs；
  • source refs/hash；
  • default install 与推荐用途。

快照内置了 core exec、product engineering、product design 等 bundled team，以及 content machine 等 optional team。

15. Team Install 为什么需要 Preview

安装 Team 会跨多表创建资源，必须先解析：

  • Agent 名称/角色冲突；
  • reportsTo 拓扑；
  • adapter 选择与配置缺失；
  • required Skill 是否已安装/可安装；
  • env/secret inputs；
  • Project/workspace 是否存在；
  • Routine schedule；
  • Company budget/hire approval policy。
sequenceDiagram
  participant U as Board
  participant T as Team Catalog Service
  participant S as Skill Service
  participant DB as PostgreSQL

  U->>T: preview(team, company, overrides)
  T->>S: resolve skill requirements
  T->>DB: inspect conflicts / existing resources
  T-->>U: plan + warnings + required inputs
  U->>T: install confirmed plan
  T->>DB: create/reuse agents, projects, tasks, routines
  T->>S: install/link skills
  T->>DB: record provenance + activity

若 Company 要求 hire approval，Team install 不能用模板批量绕过。

16. Bundled 与 Legacy Onboarding 的过渡

teams-catalog/MIGRATION.md 明确记录：当前某些 onboarding assets 仍保留，直到 onboarding 完全切换 catalog。部分角色内容已迁移但旧模板仍服务 ad-hoc hire。

这是一个重要阅读提示：Team Catalog 已存在，不代表所有首次启动路径都已只依赖它。兼容期可能有两套来源，contract test 用来防内容继续分叉。

17. 安全边界

风险 防线
外部 Skill 带脚本 trust derivation + reject executable import
Git branch 内容漂移 resolve/pin commit SHA
path traversal inventory path normalization
上游更新覆盖本地修改 drift detection + force required
Skill 获得过宽工具/资源 Agent selection + runtime scope + tool policy
Team 模板绕过审批 install 仍走 Agent/approval/authorization service
模板引用秘密 env/secret input 声明，不内嵌 value

18. 可复用经验

  1. Catalog 是不可变来源，Company Library 是可编辑安装副本。
  2. 内容 trust level 应由文件推导，不接受自我声明。
  3. 外部 Git 资产必须 pin immutable commit，再记录 hash/provenance。
  4. Update、drift、reset、fork 是不同动作，要分别建模。
  5. Skill 安装与 runtime selection/materialization 分开。
  6. 团队模板先 preview 冲突与输入，再事务式安装，并遵守现有审批门。
  7. 迁移期明确记录 legacy source，避免“看似已替换”导致双重真相。

源码入口

  • packages/skills-catalog/
  • server/src/services/skills-catalog.ts
  • server/src/services/company-skills.ts
  • server/src/services/company-skill-policy.ts
  • server/src/services/runtime-skill-selections.ts
  • packages/db/src/schema/company_skills.ts、company_skill_policies.ts
  • packages/teams-catalog/
  • server/src/services/teams-catalog.ts
  • docs/guides/agent-developer/skills-store.md

Skill/Team 提供能力和组织，持续工作还需要自动化：17 · Routines、Pipelines 与自动化。