Skill 库管理：团队协作与分发

你学会了写 Skill、测 Skill——但单兵作战的能量到此为止。Skill 的真正威力是5 人 / 50 人 / 500 人用同一份。本章讲怎么从单 skill → 团队 skill library → 跨团队 plugin 分发。

24.1 三类 Skill 库形式

─────┬────────────────────┬─────────────────────────────────────
 形式 │ 适用                │ 实现
─────┼────────────────────┼─────────────────────────────────────
 monorepo │ 中小团队           │ 一个 git repo 包含所有 skill
 multi-repo │ 多部门 / 多产品线 │ 一个 skill 一个 repo, plugin manager 安装
 hub+spoke │ 公司级            │ 内网 hub central, 各 repo 上传/同步
─────┴────────────────────┴─────────────────────────────────────

24.2 Skill Monorepo: 适合起步

每个 skill 是一个文件夹，整个 repo 是 .opencode/skills/ + 测试 + CI：

ai-skills/
├── skills/
│   ├── tdd-reminder/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   └── tests/probes.toml
│   ├── pr-review/
│   ├── pre-commit-safety/
│   └── brainstorming/
├── tests/
│   └── test_all_skills.py        ← 跑所有 skill 的 trigger probe
├── .github/workflows/
│   └── skill-regression.yml
└── README.md

CI 例（GitHub Actions）：

# .github/workflows/skill-regression.yml
name: Skill regression
on: [push, pull_request]
jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: opencode-ai/setup-opencode@v1
        with: { version: 'latest' }
      - run: opencode trigger-check --all --skills-dir skills/
      - run: pytest tests/test_all_skills.py

任一 skill 的 trigger probe 不 pass → CI block。多次回归测试让"加新 skill 不破坏旧"。

24.3 把 skill repo 当 SDK 来管理

不要把 skill repo 当"markdown 集合"。把它当 SDK：

给 Skill 加 dependency metadata：A skill 依赖 B skill 时显式声明

---
name: brainstorming-tdd
description: Brainstorm + TDD hybrid flow
depends_on:
  - brainstorming
  - tdd-reminder
---

CI 解析 dependency graph：

import tomllib
from pathlib import Path

def load_skills(d: Path):
    skills = {}
    for sf in d.glob("*/SKILL.md"):
        meta = parse_front_matter(sf.read_text())
        skills[meta["name"]] = meta
    return skills

def check_deps(skills: dict) -> list[str]:
    errs = []
    for n, m in skills.items():
        for dep in m.get("depends_on", []):
            if dep not in skills:
                errs.append(f"{n} requires {dep}, not found")
    return errs

写 release notes：每个新版本 release, 列变更摘要, 让团队 review
release 流程：tag → changelog → internal announcement

24.4 Plugin Manager：跨 repo 安装

OpenCode 0.x / Claude Code 0.x 都已支持 plugin 安装。Plugin 包结构：

opencode-plugin-tdd-reminder/
├── README.md
├── LICENSE
├── plugin.json             ← plugin meta
├── skills/
│   └── tdd-reminder/
│       ├── SKILL.md
│       └── references/
├── mcp/                    ← 可选: plugin 自带的 MCP server
└── hooks/                  ← 可选: hook scripts

plugin.json 示例：

{
  "name": "tdd-reminder",
  "version": "0.7.0",
  "author": "Laozhang Team",
  "compatible_with": ["opencode>=0.5", "claude-code>=0.8"],
  "skills":    ["skills/tdd-reminder"],
  "mcp":       [],
  "hooks":     [],
  "config_schema": null
}

安装时（OpenCode / Claude Code 类似）：

# 从 github 安装
opencode plugin install github:myteam/opencode-plugin-tdd-reminder@v0.7.0

# 从本地 path install (开发中)
opencode plugin install --path ./opencode-plugin-tdd-reminder

# 装完 verify
opencode plugin list
opencode plugin verify tdd-reminder

你的 skill 现在跟"5 行 npm package"是个能量级别——别人一行命令就装好后能直接调用。

三类发布目标，三条不同 setup：

24.5.1 个人私有 skill

位置: ~/.config/opencode/skills/<name>/
分享: 不发布
用例: 个人偏好、内部帐号、私有 MCP 凭证驱动的技巧

24.5.2 团队内部 skill

位置: private git repository e.g. git@github.com:myteam/ai-skills.git
分发: opencode plugin install git+ssh://git@github.com:myteam/ai-skills.git
权限: 仅限组织成员
用例: 团队 PR 规范、commit message 风格、内部 API 调用模式

24.5.3 社区（公开）skill

位置: 公开 git repo  e.g. github.com/you/opencode-skill-foo
分发: opencode plugin install github:you/opencode-skill-foo
权限: MIT/Apache license, README 详细,语义版本
用例: 通用模式, e.g. superpowers 给的 brainstorming / tdd / debug 模板

重要: 别把 internal-only 内容（公司域名、内部代号、客户名字）放进公开 skill —— commit 历史也是泄漏面。

24.6 Hook: Skill 与生命周期事件

OpenCode / Claude Code 等 harness 提供 hook events，让 plugin 在 lifecycle 时刻注入：

// plugin.json 补充
"hooks": {
  "on_session_start":  ["hooks/check-env.py"],
  "before_response":  ["hooks/inject-prefix.py"],
  "after_response":   ["hooks/trace-log.py"]
}

例如 on_session_start 帮你 verify 环境：

# hooks/check-env.py
import sys, os
required = ["ANTHROPIC_API_KEY", "GITHUB_PAT"]
missing  = [k for k in required if not os.getenv(k)]
if missing:
    print(f"[WARN] missing env: {missing}", file=sys.stderr)
sys.exit(0)    # dry-run warning, do not block

让你 plugin 不仅"提示模型"还"操作 harness"。

24.7 团队治理：Skill Ownership

每 skill 有 owner:

# in SKILL.md front matter
---
name: tdd-reminder
owner: laozhang-team
reviewers: [yuqienu, mengxi]
channels_help: "#ai-skill-help"
last_audit: 2026-07-01
sla_days_review: 3
---

PR review 流程：

PR author: 改 SKILL.md + tests/probes.toml
reviewers: 至少 1 个非 owner 合并
CI: trigger probe regression 兜底
merge 后 changelog 一行 release notes

关键 metric：每个 skill 月活跃用户（触发次数）。低于阈值的 skill 进入"重新评估 list"。

24.8 跨团队 / 部门：公司级 Skill catalog

到 200 人以上公司,skill 治理要分类:

公司 Skill Catalog
  ├─ core-skills     │ 通用流程, 每人必备（brainstorming / TDD / debug）
  ├─ lang-skills     │ 语言 / 框架特定 (golang / postgres / react)
  ├─ platform-skills │ 内部平台 (e.g. 构建系统 / deploy 工具)
  └─ domain-skills   │ 业务领域 (checkout / risk / fulfillment)

每个 category 配 owner 一至两人。让新人入职时：

opencode plugin install core-skills lang-skills:python platform-skills:myteam

5 行命令即可让新人 AI 协作环境跟团队对齐。

24.9 防 Skill 风险：三个 reverse / control

风险	例子	缓解
Skill drift	跟不上模型版本变化, trigger 失效	季度 audit (第 23 章)
Skill 鸿沟	老员工 skill 用得好,新人不会用	onboard 流程 + skill catalog
Skill 爆炸	库里 200 个 skill, 模型分心怎么办	top-K limit + scope per-project
Skill 不安全	skill 里 prompt 让模型"忽略指令"	code review + lint prompt

最后一条 lint:

opencode skill-lint --rule forbidden-phrases \
                    --phrases 'ignore previous', 'forget above'

24.10 一份完整 Skill 包的样子

ai-skill-repo/
├── README.md
├── LICENSE (Apache 2.0)
├── CHANGELOG.md
├── pyproject.toml 或 package.json
├── plugin.json
├── skills/
│   ├── tdd-reminder/
│   ├── pr-review/
│   └── pre-commit-safety/
├── tests/
│   ├── fixtures/
│   ├── probes.toml
│   ├── test_trigger.py
│   └── test_behavior.py
├── .github/workflows/
│   ├── skill-regression.yml
│   └── skill-release.yml
└── docs/
    ├── CONTRIBUTING.md
    └── STYLE.md

STYLE.md 写 Skill 风格规范（你 21 章学的 7 原则归档进去）—— 让贡献者提交时知道尺度。

24.11 Skill 库的成熟度模型

Level 1 (个人):       有几个 skill 散在 ~/.config/opencode/skills/
Level 2 (起步团队):   git monorepo,无 CI,trigger test 5 个 probes manually
Level 3 (成熟团队):   skill repo + CI + version + release notes
Level 4 (公司):       plugin catalog + per-category owner + onboarding
Level 5 (生态):       社区 publish 1 个 or 多个 plugin, 公开 + 半公开

我推荐到 Level 3，单兵作战能量已经够。Level 4 是团队协作标准，Level 5 是社区级别。

24.12 小结

三类 skill 库：monorepo / multi-repo / hub+spoke
plugin.json 是 plugin 元数据, opencode plugin install 一行安装
三类发布：私有个人 / private 团队 / 公开社区
plugin 治理：owner / reviewers / CI / 月活跃 metric / Skill audit 季度仪式
跨部门成 catalog 团队 ai-collab 治理

下一篇: 《25 实战一：构建一个 Docs Skill》——进入实战篇,把 4 篇理论加热。

Summary: skill 库从 monorepo 到 plugin catalog，CI 跑回归、季度 audit、version 0.x→1.0、跨团队 catalog 是终极形态。