BambooGap/skills-orchestrator

# Skills Orchestrator [](https://pypi.org/project/skills-orchestrator/) [](https://github.com/BambooGap/skills-orchestrator/actions/workflows/ci.yml) [](https://github.com/BambooGap/skills-orchestrator/actions/workflows/codeql.yml) [](https://github.com/BambooGap/skills-orchestrator/releases/latest) [](docs/github-action.md) [](LICENSE) **开源 SkillOps / instruction-supply-chain 控制层** — 用 policy packs、组织级 registry、证据包、SARIF/CI、SBOM、生态 adapter 和 MCP runtime，把分散的 `.md` skills 变成可治理、可审计、可接入团队流水线的工程资产。 它不替代 Codex、Claude Code、Omnigent、CodeGraph、Superpowers 或业务记忆系统；它位于这些工具之间，负责回答团队最实际的问题：哪些 skills 可以用、谁负责、来源是否可信、CI 是否能阻断、审计证据在哪里，以及运行时应给 agent 注入哪些指令。 | Surface | 当前状态 | 入口 | |---------|----------------|-------------| | OSS CLI | PyPI 上的 `v3.0.6` | `python3.12 -m pip install skills-orchestrator` | | GitHub Action | `v3.0.6` 发布标签 | `BambooGap/skills-orchestrator@v3.0.6` | | 容器镜像 | 发布在 GHCR | `ghcr.io/bamboogap/skills-orchestrator:v3.0.6` | | SkillOps 合同 | v1 可执行规范 | [`SPEC.md`](SPEC.md), [`CONFORMANCE.md`](CONFORMANCE.md) | | Open-core 合同 | 基于 Schema 的示例 | `examples/commercial-handoff/` | ``` python3.12 -m pip install skills-orchestrator skills-orchestrator init --template team-standard skills-orchestrator check --config config/skills.yaml ``` ## 为什么需要它？ | 问题 | 没有 Skills Orchestrator | 有了之后 | |------|--------------------------|----------| | Skill 越来越多 | 手动维护 AGENTS.md，容易遗漏或冲突 | `build` 一条命令自动生成 | | 不同项目用不同规范 | 到处复制粘贴，版本不同步 | Zone 机制，目录自动对应规范 | | CI 只能看退出码 | 终端输出无法被工具链消费 | `check --format json/sarif` 生成机器可读报告 | | Instruction 没有清单 | 供应链工具看不到 agent 规则资产 | `manifest --format json/cyclonedx` 导出 instruction inventory | | Policy 团队无法审计 | Resolver 结果只在 CLI 里可见 | `policy export --format opa-input/rego-test` 导出 OPA/Rego proof | | 团队规则不可执行 | owner/source/version 只写在文档里 | `check --policy-pack builtin/team-standard` 强制团队治理元数据 | | 多仓 Skill 无法盘点 | 每个 repo 各查各的 | `registry build` / `registry diff` 导出组织级 skill registry | | 商用审计缺证据包 | 发布时到处找 CI、manifest、SARIF | `evidence export` 一次导出审计证据 | | 上下文窗口有限 | 所有 Skill 全量注入，浪费 token | MCP Server 按需加载，500 个 Skill 和 5 个消耗相同 | | 两个 Skill 互相冲突 | 运行时才发现，模型行为不确定 | 编译时 `conflict_with` 强制报错 | | 多步骤工作流无保证 | AI 靠自觉推进，容易跳步或遗漏 | Pipeline 编排 + 质量门禁，每步必须产出 | | Skill 内容重复 | 相似 Skill 各自维护，改一处忘另一处 | Skill Inheritance，子 Skill 继承父 Skill | ## 快速开始（5 分钟） ### 安装 ``` python3.12 -m pip install skills-orchestrator ``` Skills Orchestrator 需要 Python 3.12 或更高版本。在 macOS 上，`/usr/bin/python3` 通常是 Python 3.9，这会导致 `pip install skills-orchestrator` 看起来像找不到该包。 请使用 `python3.12`、`pipx --python python3.12`、`uvx --python 3.12` 或 Docker 镜像。 不想在 CI host 上安装 Python 包时，也可以直接使用已发布容器： ``` docker run --rm ghcr.io/bamboogap/skills-orchestrator:v3.0.6 --version ``` ### 初始化项目 ``` cd my-project # 生产 bootstrap：生成 config、示例 skills、CI workflow 和 evidence 目录 skills-orchestrator init --template team-standard # 兼容旧流程：从已有 skills/*.md frontmatter 生成配置 skills-orchestrator init --non-interactive # 交互式：逐个确认每个 Skill 的配置 skills-orchestrator init ``` ### 检查 Skills ``` skills-orchestrator check --config config/skills.yaml # Skills 检查 # 发现：0 个错误，0 个警告，0 条信息 ``` 启用团队标准规则： ``` skills-orchestrator check \ --config config/skills.yaml \ --policy-pack builtin/team-standard \ --fail-on warning ``` CI 或 GitHub Code Scanning 可以使用机器可读输出： ``` skills-orchestrator check --config config/skills.yaml --format json skills-orchestrator check --config config/skills.yaml --format sarif skills-orchestrator schema validate --kind check --input check.json ``` 也可以直接在 GitHub Actions 中运行： ``` permissions: contents: read security-events: write pull-requests: write jobs: skills: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: BambooGap/skills-orchestrator@v3.0.6 with: config: config/skills.yaml policy-pack: builtin/team-standard upload-sarif: true comment-registry-diff: true ``` 更多输入参数见 [GitHub Action 文档](docs/github-action.md)。团队文档入口见 [文档索引](docs/INDEX.md)。 Docker 运行方式见 [Docker 用法](docs/docker.md)。 ### 规范、一致性与可运行 Demo - [SkillOps Contract v1](SPEC.md)：skill metadata、registry、diff、evidence、adapter 的机器可测试规范。 - [一致性测试](CONFORMANCE.md)：如何用 `schema validate`、`check`、`registry`、`evidence` 验证兼容性。 - [安全策略](SECURITY.md)：MCP trust model、HMAC audit、import provenance 和漏洞报告流程。 - [Demo 仓库](examples/demo-repo/README.md)：可复制到独立 repo 的端到端场景，覆盖 PR diff comment、SARIF、evidence bundle 和 adapter inspect。 ### SkillOps Readiness 与证据包 ``` skills-orchestrator doctor --profile adopter --config config/skills.yaml skills-orchestrator doctor --profile maintainer --config config/skills.yaml skills-orchestrator evidence export \ --config config/skills.yaml \ --out evidence skills-orchestrator registry build \ --config-glob "config/skills.yaml" \ --output skill-registry.json skills-orchestrator registry diff registry-before.json registry-after.json \ --format markdown \ --output registry-diff.md skills-orchestrator registry comment-body registry-diff.md \ --output registry-diff-comment.md skills-orchestrator schema validate \ --kind registry \ --input skill-registry.json skills-orchestrator integrations list skills-orchestrator adapters inspect --format json skills-orchestrator supply-chain sbom --output package-sbom.cdx.json ``` `doctor` 默认使用 `adopter` profile，检查接入仓库真正需要的 config、policy、 SkillOps CI workflow、lock 和 `AGENTS.md` 证据；`maintainer` profile 才额外检查 本项目发版用的 `action.yml`、`Dockerfile` 和版本化测试报告。`evidence export` 写出 `check.json`、`check.sarif`、`instruction-manifest.json`、`policy-opa-input.json`、 `policy-proof.rego`、`doctor.json` 和 `skill-registry.json`，适合 CI artifact、审计归档或客户交付。 `schema validate` 可单独验证 config、check、manifest、policy OPA input、doctor、 registry、registry diff、adapter inspection、SBOM 和 commercial handoff 文件合同。 ### 生态适配与 Open-core Handoff ``` skills-orchestrator adapters inspect --path . --format json \ > adapter-inspect.json skills-orchestrator adapters export mcp-client-config \ --config config/skills.yaml \ --output mcp-client.json skills-orchestrator adapters export openai-agents-sdk \ --config config/skills.yaml \ --output openai_skillops_agent.py skills-orchestrator schema validate \ --kind hosted-registry-ingest \ --input examples/commercial-handoff/registry-ingest.json ``` 开源核心只负责产出本地 artifact 与机器可读合同。后续 GitHub App、hosted registry 和 enterprise dashboard 应消费这些文件，而不是在 SaaS 后端里重新实现 resolver 或 registry 语义。 ### 导出 Instruction Manifest Native JSON 保留 Skills Orchestrator 的完整语义，CycloneDX 输出是实验性映射，用于进入现有 BOM / supply-chain 词汇体系。 ``` skills-orchestrator manifest --config config/skills.yaml --format json skills-orchestrator manifest --config config/skills.yaml --format cyclonedx ``` ### 导出 Policy Proof OPA/Rego 是对外审计和集成表面，不是第二套运行时 backend。Resolver 仍然是权威决策系统。 ``` skills-orchestrator policy export --config config/skills.yaml --format opa-input skills-orchestrator policy export --config config/skills.yaml --format rego-test ``` ### 编译生成 AGENTS.md ``` skills-orchestrator build --config config/skills.yaml # ✓ 解析完成: N skills, N zones # ✓ 使用 Zone: 默认区 (default) # ✓ 输出: AGENTS.md ``` 把生成的 `AGENTS.md` 放到项目根目录，Claude / Cursor 会在会话启动或项目重新加载时读取。 ## 核心功能 ### Runtime 模型 Skills Orchestrator 把“启动时引导”和“运行时加载”分开： | 层 | 作用 | 典型入口 | |----|------|----------| | `AGENTS.md` | Bootstrap。告诉 Agent 当前项目有哪些 required / available skills，以及如何按需请求更多内容。多数 Agent 只在会话启动或项目重新加载时读取它。 | `build`, `sync agents-md` | | Check Reports | Static diagnostics。检查 metadata、重复 id、冲突声明、lock drift，并输出 text / JSON / SARIF。 | `check`, `validate --format json` | | Policy Packs | Team governance。把 owner/source/version/lifecycle/approver 等团队规则变成可执行检查。 | `check --policy-pack builtin/team-standard` | | Instruction Manifest | Inventory export。导出 native JSON 和实验性 CycloneDX BOM，便于把 agent instructions 纳入供应链资产清单。 | `manifest` | | Policy Export | Policy proof。导出 OPA input 和 Rego test fixture，证明 resolver 事实可被 policy-as-code 审计。 | `policy export` | | Registry & Evidence | SkillOps evidence。生成组织级 registry、doctor readiness 报告和发布审计证据包。 | `registry`, `doctor`, `evidence export` | | MCP Server | Runtime skill loading。对话过程中通过 `prepare_context` / `search_skills` / `get_skill` 动态选择并获取本轮 Skill 内容，避免一次性塞满上下文。 | `serve`, `mcp-test` | | Pipeline | Runtime workflow orchestration。把多个 Skill 串成有状态流程，并在每一步自动注入当前步骤 Skill。 | `pipeline start`, MCP pipeline tools | 团队落地建议见 [团队标准化指南](docs/team-standardization.md)。 ### 同一会话内如何动态切换 Skills `AGENTS.md` 不是热更新文件。多数 Agent 只会在 `/new`、新会话、项目重新加载时读取一次它。Skills Orchestrator 的动态能力来自 MCP：`AGENTS.md` 只告诉 Agent 一条固定协议，真正的 Skill 选择在每个任务开始时通过 `prepare_context` 完成。 ``` /new ↓ Agent 读取一次 AGENTS.md ↓ AGENTS.md 提供固定协议： - 不要把所有 available skills 全量塞进上下文 - 每个新任务开始或任务目标明显变化时，先调用 MCP prepare_context(task) - 本轮只遵循 prepare_context 返回的 active_skills - 上一轮加载过但本轮未返回的 skills 视为 inactive ↓ 任务 1：用户说“帮我做安全审查” ↓ Agent 调用： prepare_context({"task": "帮我做安全审查", "max_skills": 3}) ↓ MCP 返回本轮 active_skills，例如： - security-review（安全代码审查） - pr-review（PR Review） - error-handling（错误处理规范） ↓ Agent 按这组 Skills 执行任务 1 ↓ 任务 2：用户说“现在帮我写发版流程” ↓ Agent 再次调用： prepare_context({"task": "写发版流程", "max_skills": 3}) ↓ MCP 返回新的 active_skills，例如： - deployment-checklist（部署检查清单） - git-commit-conventions（Git 提交规范） - documentation（写文档） ↓ Agent 按新这组 Skills 执行任务 2，任务 1 的安全审查 Skills 不再作为本轮规则 ``` `prepare_context` 默认会直接返回 active skills 的完整内容，适合让 Agent 立即进入任务。如果只想先看路由结果，可以传 `include_content: false`，再对需要的条目调用 `get_skill(id)`。 ``` skills-orchestrator mcp-test prepare_context \ '{"task": "帮我做安全审查", "max_skills": 3, "include_content": false}' \ --config config/skills.yaml ``` 返回结果包含四类信息： | 字段 | 含义 | |------|------| | `active_skills` | 本轮任务应该遵循的 Skill ID 列表 | | `inactive_skills` | 当前 Registry 中未被本轮选中的 Skill，本轮任务不应受其约束 | | `Decision Record (JSON)` | 结构化路由记录，包含 `routing_id`、`task_hash_alg`、registry generation、active/inactive skills、内容哈希和截断信息 | | `Execution Rule` | 明确告诉 Agent：旧 Skill 与本轮 active skills 冲突时，以本轮为准 | | `Active Skill Content` | 当 `include_content=true` 时，直接注入本轮所需 Skill 全文 | 这意味着同一个会话可以连续处理多个不同任务，但每个任务边界都要重新路由一次。`prepare_context` 不能删除模型历史上下文里的旧文字，所以它会显式输出 inactive 规则，让 Agent 在行为上切换到新的一组 Skills。 因此，修改 Skill 后通常需要重新 `build` / `sync` 并重启或刷新对应 Agent 会话；如果使用 MCP Server，运行中的 server 也需要重启才能重新加载配置和 Skill 内容。 ### 1. 编译时治理 解析 Skill 的 YAML frontmatter，检测冲突，按 Zone 生成 `AGENTS.md`。 - **Zone 机制**：不同目录自动应用不同规范（企业强制区 vs 个人自由区） - **冲突检测**：编译时 `conflict_with` 强制报错，不会运行时才发现 - **Auto-Discovery**：从 frontmatter 自动发现 Skill，无需手动注册 ### 2. MCP Server（10 个工具） 让 Claude 在对话中按需动态加载 Skill，上下文零浪费。 | 工具 | 用途 | |------|------| | `list_skills` | 查看所有可用 Skill（含 tag 过滤） | | `search_skills` | 按需求搜索相关 Skill | | `get_skill` | 加载完整 Skill 内容到上下文 | | `suggest_combo` | 根据任务描述推荐 Skill 组合 | | `prepare_context` | 每个新任务动态选择本轮 active skills，并可直接注入完整内容 | | `pipeline_start` | 启动一个工作流，注入当前步骤指导 | | `pipeline_status` | 查看工作流进度和当前步骤 | | `pipeline_list_runs` | 列出已保存的 Pipeline 运行记录 | | `pipeline_advance` | 完成当前步骤，推进到下一步 | | `pipeline_resume` | 恢复中断的工作流 | 推荐在 `AGENTS.md` 中固定写入这条规则：每次新任务开始或任务目标明显变化时，先调用 `prepare_context(task)`；本轮只遵循返回的 `active_skills`，之前任务加载过但本次未返回的 Skill 视为 inactive。 启动方式： ``` skills-orchestrator serve --config config/skills.yaml ``` 需要运行期审计时，指定 audit 目录。审计事件是 JSONL，只记录 tool、参数 key、routing hash、active skill id 等治理字段，不记录任务原文或 Skill 正文。 ``` skills-orchestrator serve --config config/skills.yaml --audit-dir .skills-audit skills-orchestrator usage report --audit-dir .skills-audit ``` 在 `.claude/settings.json` 中配置： ``` { "mcpServers": { "skills-orchestrator": { "command": "skills-orchestrator", "args": ["serve", "--config", "/absolute/path/to/config/skills.yaml"] } } } ``` ### 3. Pipeline 编排 把多个 Skill 编排成有序工作流，质量门禁保证每步产出。 ``` # config/pipelines/quick-fix.yaml id: quick-fix name: 快速修复流程 steps: - skill: systematic-debugging gate: must_produce: [root_cause] min_length: 50 - skill: tdd gate: must_produce: [test_code] min_length: 100 - skill: pr-review skip_if: trivial_fix ``` ``` # 启动工作流 skills-orchestrator pipeline start quick-fix # 查看进度 skills-orchestrator pipeline status # 推进到下一步 skills-orchestrator pipeline advance quick-fix # 恢复中断的工作流 skills-orchestrator pipeline resume ``` **关键**： - `pipeline_start` / `pipeline_advance` / `pipeline_resume` 返回时自动注入当前步骤 Skill 的完整内容，AI 无需额外调用 `get_skill` - Gate 质量门禁：`must_produce` 检查上下文中 key 的存在性，`min_length` 检查最小长度 - `skip_if` 条件跳过：满足条件时自动跳过该步骤 - RunState 持久化：工作流状态存到 `~/.skills-orchestrator/runs/`，中断后可恢复 ### 4. Skill 继承 子 Skill 继承父 Skill 的内容，避免重复维护。 ``` --- id: chinese-code-review name: 中文代码审查 base: code-review # 继承父 Skill tags: [review, coding, chinese] --- ## 额外规则（追加到父内容之后） - 审查意见用中文撰写 - 遵循国内团队 commit 规范 ``` 编译时 Resolver 校验继承链（循环引用、缺失父 Skill），运行时 `get_skill` 返回合并后的完整内容。 ### 5. Sync 多工具同步 将 Skill 同步到不同 AI 工具的目录格式。 ``` # 同步到 Hermes Agent（全量，默认） skills-orchestrator sync hermes # 同步到 OpenClaw（全量，默认） skills-orchestrator sync openclaw # 同步到 AGENTS.md（摘要模式，默认） skills-orchestrator sync agents-md # 同步到 Cursor（摘要模式，默认） skills-orchestrator sync cursor # 同步到 Copilot（摘要模式，默认） skills-orchestrator sync copilot # 全量导出到指定文件 skills-orchestrator sync agents-md --full -o AGENTS.md ``` | 目标 | 默认模式 | 说明 | |------|----------|------| | `hermes` | 全量 | 写入 `~/.hermes/skills/` 目录 | | `openclaw` | 全量 | 写入 `~/.openclaw/workspace/skills/` 目录 | | `agents-md` | 摘要 | 生成 `AGENTS.md`，Required Skills 完整内容 + Available Skills 表格 | | `cursor` | 摘要 | 生成 `.cursor/rules/*.mdc`，每个 Skill 对应一个文件 | | `copilot` | 摘要 | 生成 `.github/copilot-instructions.md` | AGENTS.md 输出格式： ``` ## 必需 Skills --- id: systematic-debugging ... （完整 Skill 内容） --- ## 可用 Skills | Skill | 描述 | Tags | |-------|------|------| | brainstorming | 在任何创造性工作之前必须使用... | planning, creative | | writing-plans | 当你有规格说明或需求时使用... | planning | ``` ## Skill 文件格式 每个 `.md` 文件开头加 YAML frontmatter，Skills Orchestrator 自动发现，无需手动注册： ``` --- id: my-skill name: 我的技能 summary: "一句话描述，用于 search 和摘要展示" tags: [coding, quality] load_policy: free # free / require（强制注入） priority: 80 # 数值越大优先级越高 zones: [default] # 适用的 Zone conflict_with: [] # 互斥的 Skill ID 列表 base: parent-skill # 可选：继承父 Skill --- # 正文内容（Markdown） ... ``` ### 目录结构（推荐） ``` skills/ ├── coding/ tdd.md, error-handling.md, api-design.md ├── git/ git-operations.md, git-worktrees.md ├── ops/ deployment-checklist.md, environment-setup.md ├── planning/ brainstorming.md, writing-plans.md ├── quality/ refactoring.md, systematic-debugging.md └── review/ chinese-code-review.md, security-review.md ``` ## 配置文件（skills.yaml） ``` version: "2.0" # 自动扫描目录，无需手动列出每个 Skill skill_dirs: - ../skills # Zone：不同目录使用不同规范 zones: - id: enterprise name: 企业强制区 load_policy: require # 该 Zone 内所有 Skill 强制注入（free 自动升级为 forced） rules: - pattern: "*/internal/*" - git_contains: "company.com" - id: default name: 默认区 load_policy: free rules: [] # 覆盖个别 Skill 的 frontmatter 默认值 overrides: [] # Combo：预定义的 Skill 组合 combos: - id: full-dev-workflow name: 完整开发工作流 skills: [brainstorming, writing-plans, git-worktrees, finish-branch] ``` ## 所有命令 ``` # 编译 & 验证 skills-orchestrator build --config # 生成 AGENTS.md skills-orchestrator validate --config # 验证，不生成文件 skills-orchestrator status --config # 查看 forced/passive/blocked skills-orchestrator inspect --workdir # 检查目录命中哪个 Zone # 初始化 & 导入 skills-orchestrator init # 交互式初始化 skills-orchestrator init --non-interactive # 非交互式，从 frontmatter 自动生成 skills-orchestrator import # 从 GitHub 导入 Skill # MCP Server skills-orchestrator serve --config # 启动 MCP Server skills-orchestrator mcp-test # 测试 MCP 工具 # 示例：为一个新任务动态选择本轮 skills skills-orchestrator mcp-test prepare_context '{"task": "做安全审查", "max_skills": 3}' # Pipeline 编排 skills-orchestrator pipeline start # 启动工作流 skills-orchestrator pipeline status # 查看进度 skills-orchestrator pipeline advance # 推进到下一步 skills-orchestrator pipeline resume # 恢复中断的工作流 # Sync 同步 skills-orchestrator sync hermes # 同步到 Hermes Agent skills-orchestrator sync openclaw # 同步到 OpenClaw skills-orchestrator sync agents-md [-o FILE] # 同步到 AGENTS.md skills-orchestrator sync cursor # 同步到 Cursor (.cursor/rules/*.mdc) skills-orchestrator sync copilot [-o FILE] # 同步到 Copilot # Lock 可复现性 skills-orchestrator build --lock # 编译时同时生成 skills.lock.json skills-orchestrator check --check-lock skills.lock.json # 检查 lock 是否过期 ``` ## 从 GitHub 导入 Skill ``` # 导入单个仓库里的所有 Skill skills-orchestrator import https://github.com/forrestchang/andrej-karpathy-skills # 导入后自动放入 skills/external/ 目录 ``` ## 开发 ``` git clone https://github.com/BambooGap/skills-orchestrator cd skills-orchestrator python3.12 -m pip install -e ".[dev]" pytest tests/ -v ruff check skills_orchestrator/ tests/ ``` CI 运行：ruff lint + format check + Python 3.12/3.13 矩阵测试。 ## 路线图 ### 已完成主线 - v2.0.x：稳定了 build / validate / zone / conflict、frontmatter discovery、MCP Server、Skill Inheritance、sync targets、Pipeline 编排、PyPI 发布和基础安全边界。 - 检查诊断与机器报告阶段：补齐 `check` 诊断面，输出 JSON / SARIF，并把项目定位收敛到 SkillOps 和 instruction supply chain。 - v2.3.x：发布 GitHub Action、CycloneDX / native manifest、OPA/Rego proof export、Action SHA pinning、artifact attestation 和 PyPI 发布防护。 - v2.4.x：补齐 Docker 交付、团队标准化文档、MCP runtime decision record、usage audit、pipeline recovery 和本地运行证据。 - v2.5.x：补齐 `builtin/team-standard` policy pack、治理元数据、`doctor` readiness、组织级 `registry`、`evidence export`、integration catalog、MCP 内容上限、audit HMAC 和 pipeline 状态脱敏。 - v2.6.x：补齐稳定 JSON Schema、`schema validate`、`init --template team-standard` 和 `registry diff --format markdown`，降低团队 bootstrap 与 PR review 摩擦。 - v3.0.x：补齐 PR registry diff comment automation、package SBOM、CodeQL/GHCR workflows、生态 adapter inspect/scaffold、open-core commercial handoff schemas 和 GitHub App / hosted registry / dashboard 蓝图。 ### 下一阶段 - 增加 container image SBOM/provenance，并把 attestation 绑定到 GHCR digest。 - 增加 Claude Skills import/export round-trip fixtures 和更多真实生态 adapter examples。 - 在外部仓库实现 GitHub App / hosted registry / dashboard，继续消费 OSS artifact contracts，而不是把 SaaS 后端塞进核心 CLI。 ## License MIT

标签：AI智能体, DevOps工具, LLM工程, 审计与合规, 技能编排, 请求拦截, 逆向工具