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://securityscorecards.dev/viewer/?uri=github.com/BambooGap/skills-orchestrator) [](https://github.com/BambooGap/skills-orchestrator/releases/latest) [](docs/github-action.md) [](#license)

开源 SkillOps / AI instruction governance system — 用 policy packs、组织级 registry、证据包、SARIF/CI、SBOM、生态 adapter 和 MCP bridge，把分散的 .md skills 变成可治理、可审计、可接入团队流水线的工程资产。

它不替代 Codex、Claude Code、Omnigent、CodeGraph、Superpowers 或业务记忆系统；它位于这些工具之间，负责回答团队最实际的问题：哪些 skills 可以用、谁负责、来源是否可信、CI 是否能阻断、审计证据在哪里，以及下游 agent runtime 应消费哪些经过治理的指令资产。

License: MIT OR Apache-2.0 at your option. The top-level LICENSE keeps GitHub license detection on standard MIT text; Apache-2.0 remains available in [LICENSE-APACHE](LICENSE-APACHE).

| Surface | Current status | Entry point | |---------|----------------|-------------| | OSS CLI | Published version shown by the PyPI badge | python3.12 -m pip install skills-orchestrator | | GitHub Action | Pin a reviewed public-release commit | BambooGap/skills-orchestrator@ | | Container image | Published tags and digests on GHCR | ghcr.io/bamboogap/skills-orchestrator: | | SkillOps Contract | v1 executable spec | [SPEC.md](SPEC.md), [CONFORMANCE.md](CONFORMANCE.md) | | Enterprise adoption | Copyable repo starter packs | [docs/adoption-playbook.md](docs/adoption-playbook.md), examples/adoption-repos/ | | Open-core contracts | Schema-backed examples | examples/commercial-handoff/ |

Release contract: a Git tag or the version in the source tree is not a public-release claim. Treat a version as published only after GitHub Release, PyPI, and GHCR are present and the Release Integrity run passes. The workflow keeps the full public-artifact report as evidence and retries for up to 15 minutes while indexes and registries settle.

可验证发布面

生产团队可以直接核验当前发布物，而不是只相信 README 声明：

• GitHub latest release:

release tag、source archive、release notes 和 release commit。

• PyPI project: skills-orchestrator

wheel / sdist；发布流程使用 PyPI Trusted Publishing 和 artifact attestations。

• GHCR package:

多架构 OCI image，可按 tag 或 digest 拉取。

• Post-release Smoke:

发布后核验 GitHub Release、PyPI install、consumer-side hash-locked install、GHCR image、Cosign signature、SBOM/provenance attestations、SLSA readiness report 和 starter kit path。

• Release Integrity:

GitHub Release 发布后自动运行完整 smoke，并为报告生成 artifact attestation；同名 Release 证据禁止覆盖。只有该 run 成功的版本才能作为公开发布版本引用。

• [Supply Chain Verification](docs/supply-chain-verification.md): 消费端验证 PyPI

wheel/sdist attestations、GHCR provenance/SBOM/OS SBOM attestations、Cosign signature、 Docker digest 和 hash-lock 边界的命令。

SLSA 边界：项目生成的是 SLSA readiness / evidence input，用于说明哪些发布证据已经 可验证；它不是正式 SLSA 等级认证，也不声明已经达到 SLSA Build L3+。 细节见 [SLSA Readiness](docs/slsa-readiness.md)。

python3.12 -m pip install skills-orchestrator
skills-orchestrator init --template team-standard
skills-orchestrator check --config config/skills.yaml

The default PyPI install is the lightweight CI governance CLI. Install the optional MCP runtime only when you want serve or mcp-test:

python3.12 -m pip install "skills-orchestrator[mcp]"

Deploy the MCP server with pipx, uv tool, a dedicated virtual environment, or Docker. Do not install it into an existing business FastAPI environment. See [Install](docs/install.md) for the tested compatibility matrix and the release-matched constraints-mcp.txt workflow.

---

为什么需要它？

| 问题 | 没有 Skills Orchestrator | 有了之后 | |------|--------------------------|----------| | Skill 越来越多 | 手动维护 AGENTS.md，容易遗漏或冲突 | build 一条命令自动生成 | | 不同项目用不同规范 | 到处复制粘贴，版本不同步 | Zone 机制，目录自动对应规范 | | CI 只能看退出码 | 终端输出无法被工具链消费 | check --format json/sarif 生成机器可读报告和 rule-level trace | | Instruction 没有清单 | 供应链工具看不到 agent 规则资产 | manifest --format json/cyclonedx 导出 instruction inventory | | Policy 团队无法审计 | Resolver 结果只在 CLI 里可见 | policy export --format opa-input/rego-test 导出 OPA/Rego proof | | 团队规则不可执行 | owner/source/version/license 只写在文档里 | check --policy-pack builtin/team-standard 强制团队治理元数据 | | 外部 Skill 来源不可信 | 只知道复制自 URL，不知道 commit、hash、抓取时间 | import 写入 provenance，builtin/engineering-grade 检查来源证据 | | 多仓 Skill 无法盘点 | 每个 repo 各查各的 | registry build / registry diff / registry graph 导出组织级 skill registry 和治理关系图 | | 外部平台难以接入 | Hosted/GitHub App 重写 CLI 语义 | examples/external-consumer 固化 hosted registry、GitHub App、multi-repo artifact 输入边界 | | 商用审计缺证据包 | 发布时到处找 CI、manifest、SARIF | evidence export 一次导出审计证据和 hash ledger | | 上下文窗口有限 | 所有 Skill 全量注入，浪费 token | MCP Server 默认只注入选中内容；未选中 Skill 仍会以计数和审计元数据出现 | | 两个 Skill 互相冲突 | 运行时才发现，模型行为不确定 | 编译时 conflict_with 强制报错 | | 多步骤工作流无保证 | AI 靠自觉推进，容易跳步或遗漏 | Pipeline 编排 + artifact/evidence 门禁，拒绝仅声明名称或布尔值的伪产出 | | Skill 内容重复 | 相似 Skill 各自维护，改一处忘另一处 | Skill Inheritance，子 Skill 继承父 Skill |

---

快速开始（5 分钟）

安装

python3.12 -m pip install skills-orchestrator

Skills Orchestrator requires Python 3.12 or newer. On macOS, /usr/bin/python3 is often Python 3.9, which can make pip install skills-orchestrator look like the package is missing. Use python3.12, pipx --python python3.12, uvx --python 3.12, or the Docker image.

> pip 包内置 team-standard starter kit；需要更多 examples 时再 clone 本仓库。

serve and mcp-test need the optional MCP runtime extra:

python3.12 -m pip install "skills-orchestrator[mcp]"

不想在 CI host 上安装 Python 包时，也可以直接使用已发布容器：

# Use v4.8.49 only after its Release Integrity run is green.
docker run --rm ghcr.io/bamboogap/skills-orchestrator:v4.8.49 --version

初始化项目

cd my-project

# 生产 bootstrap：生成 config、示例 skills、CI workflow 和 evidence 目录
skills-orchestrator init --template team-standard

# 严格供应链 bootstrap：生成 pinned checkout 的 CI workflow
skills-orchestrator init --template team-standard --hardened-workflow

# 兼容旧流程：从已有 skills/*.md frontmatter 生成配置
skills-orchestrator init --non-interactive

# 交互式：逐个确认每个 Skill 的配置
skills-orchestrator init

检查 Skills

skills-orchestrator check --config config/skills.yaml
# Skills check
#   Findings: 0 errors, 0 warnings, 0 infos

启用团队标准规则：

skills-orchestrator check \
  --config config/skills.yaml \
  --policy-pack builtin/team-standard \
  --fail-on warning

启用工程级治理规则：

skills-orchestrator check \
  --config config/skills.yaml \
  --policy-pack builtin/engineering-grade \
  --fail-on warning

CI 或 GitHub Code Scanning 可以使用机器可读输出：

skills-orchestrator check --config config/skills.yaml --format json > check.json
skills-orchestrator check --config config/skills.yaml --format sarif
skills-orchestrator explainability build \
  --check-json check.json \
  --config config/skills.yaml \
  --output ci-explainability.json \
  --force
skills-orchestrator schema validate --kind check --input check.json
skills-orchestrator schema validate --kind ci-explainability --input ci-explainability.json

JSON check output includes policy_trace: an explainable CI trace for rule evaluation. It traces SkillOps rules and policy packs, not agent reasoning or runtime model behavior. ci-explainability.json turns the same trace into PR/CI-ready failure explanations: rule id, blocking status, file/line, skill id, severity, and suggested fix.

也可以直接在 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@v4.8.49
        with:
          config: config/skills.yaml
          policy-pack: builtin/team-standard
          upload-sarif: true
          reviewer-summary: true
          dashboard-snapshot: true
          comment-registry-diff: true

reviewer-summary: true 会生成 check JSON、policy trace、registry graph、evidence ledger 和 reviewer summary artifact；dashboard-snapshot: true 会从同一份 evidence bundle 派生 dashboard-ready JSON。如果同时启用 comment-registry-diff，PR comment 会使用更适合 reviewer 阅读的汇总内容。

更多输入参数见 [GitHub Action 文档](docs/github-action.md)。团队文档入口见 [Documentation Index](docs/INDEX.md)。

Docker 运行方式见 [Docker Usage](docs/docker.md)。

15 分钟生产接入

如果你是在一个真实仓库里第一次接入，优先走 adoption playbook，而不是直接启用最严格的 enterprise gate：

1. 用 init --template team-standard 生成 starter kit。
2. 先跑 check，再跑 build --lock 生成 AGENTS.md 和 skills.lock.json。
3. 再跑 doctor --profile adopter --fail-under 100 和 conformance run --profile core。
4. 在 GitHub Action 里先用 advisory 或 warning gate。
5. 等 registry diff 和 SARIF 对 reviewer 有用后，再升级到 builtin/engineering-grade。

完整步骤见 [Adoption Playbook](docs/adoption-playbook.md)。可复制的真实仓库形态示例见 [Reference Repository Examples](examples/adoption-repos/README.md)。

生产固定版本策略

生产仓库不要自动追最新 tag。固定 PyPI exact version、GitHub Action release commit SHA、 Docker digest 和依赖 hash lock；先以 advisory mode 运行，再按团队变更流程升级到 blocking gate。推荐流程见 [Production Adoption](docs/production-adoption.md)。

规范、一致性与端到端参考

• [SkillOps Contract v1](SPEC.md): skill metadata、registry、diff、evidence、adapter 的机器可验证规范。
• [Conformance](CONFORMANCE.md): 如何用 conformance run、schema validate、check、registry、evidence 验证兼容性。
• [Third-party Implementation Guide](docs/third-party-implementation.md): 如何只依赖 schema、conformance 和负例 fixtures 实现兼容工具。
• [Security Policy](SECURITY.md): MCP trust model、HMAC audit、import provenance 和漏洞报告流程。
• [Reference Repository](examples/demo-repo/README.md): 可复制到独立 repo 的端到端参考场景，覆盖 PR diff comment、SARIF、evidence bundle 和 adapter inspect。
• [Negative Conformance Fixtures](examples/negative-conformance/README.md): 可复制的坏输入样本，证明高风险 instruction artifacts 会稳定失败。
• [Adoption Playbook](docs/adoption-playbook.md): 从 advisory CI 到 blocking gate 的接入路径。
• [Production Adoption](docs/production-adoption.md): 生产 CI 接入的 SHA pin、Docker digest、PyPI version pin、证据保留和 runtime 边界。
• [Supply Chain Verification](docs/supply-chain-verification.md): 验证 PyPI wheel/sdist attestations、GHCR provenance/SBOM attestations、digest 和 hash-lock 边界。
• [Adoption Authorization](docs/adoption-authorization.md): 外部仓库维护者授权 adoption 的请求模板、公开引用许可和防误读边界。
• [External Adoption Intake](docs/external-adoption-intake.md): 外部仓库接入前的 go / no-go 清单。
• [Adoption Evidence Pack](docs/adoption-evidence-pack.md): 真实外部仓库接入的 artifact handoff、review agenda 和 promotion decision 清单。
• [External Adoption Record](examples/external-adoption-record/README.md): 用 schema-valid artifact 记录外部接入、promotion decision 和公开 listing consent。
• [Adoption Case Study Template](docs/adoption-case-study-template.md): 只有在 public listing consent 获批后才使用的公开案例模板。
• [Adoption Maturity Model](docs/adoption-maturity-model.md): 从本地接入到多仓治理的分级准入标准。
• [Agent Fleet Governance](docs/agent-fleet-governance.md): 多 Agent、多租户、多项目指令资产治理边界。
• [Supervisor Governance](docs/supervisor-governance.md): 总控 Agent、子 Agent、交接、权限和证据的治理模型。
• [Agent Handoff Contract Example](examples/agent-handoff/README.md): 可验证的 supervisor/worker handoff、tenant scope、tool boundary 和 evaluation gate 示例。
• [Agent Runtime Image Contract Example](examples/agent-runtime-image/README.md): 可验证的外部 agent runtime 容器镜像、权限边界、证据和 handoff gate 示例。
• [Reference Repository Examples](examples/adoption-repos/README.md): Healthchecks、Umami、Woodpecker 风格仓库的最小接入包。
• [External Consumer Example](examples/external-consumer/): hosted registry、GitHub App 和 multi-repo artifact 输入边界。
• [Commercial And Foundation Readiness](docs/foundation-readiness.md): 商用接入、外部 adoption、基金会候选之间的真实门槛。
• [Release Rollback Playbook](docs/release-rollback.md): 发布错误时如何处理 PyPI、GHCR、GitHub Release 和证据包。
• [Support](SUPPORT.md), [Code of Conduct](CODEOFCONDUCT.md), and [Third-party Notices](THIRDPARTYNOTICES.md):

外部贡献、支持边界和依赖 notices 入口。

SkillOps Readiness 与证据包

skills-orchestrator doctor --profile adopter --config config/skills.yaml

skills-orchestrator doctor --profile maintainer --config config/skills.yaml

skills-orchestrator conformance run \
  --config config/skills.yaml \
  --policy-pack builtin/engineering-grade

skills-orchestrator check \
  --config config/skills.yaml \
  --policy-pack builtin/engineering-grade \
  --format json \
  > check.json

skills-orchestrator explainability build \
  --check-json check.json \
  --config config/skills.yaml \
  --output ci-explainability.json \
  --force

skills-orchestrator evidence export \
  --config config/skills.yaml \
  --out evidence

skills-orchestrator evidence index \
  --manifest "repo-a=../repo-a/evidence/evidence-manifest.json" \
  --manifest "repo-b=../repo-b/evidence/evidence-manifest.json" \
  --scope-name platform-adoption \
  --output multi-repo-artifacts.json

skills-orchestrator registry build \
  --config-glob "config/skills.yaml" \
  --output skill-registry.json

skills-orchestrator registry graph \
  --config-glob "config/skills.yaml" \
  --output registry-graph.json

skills-orchestrator registry diff registry-before.json registry-after.json \
  --format json \
  --output registry-diff.json \
  --force

skills-orchestrator registry diff registry-before.json registry-after.json \
  --format markdown \
  --output registry-diff.md \
  --force

skills-orchestrator reviewer summary \
  --check-json check.json \
  --registry-diff-json registry-diff.json \
  --registry-diff-markdown registry-diff.md \
  --registry-graph registry-graph.json \
  --evidence-manifest evidence/evidence-manifest.json \
  --output skillops-review-summary.md

skills-orchestrator dashboard snapshot \
  --evidence-dir evidence \
  --repository BambooGap/skills-orchestrator \
  --ref refs/heads/main \
  --commit "$(git rev-parse HEAD)" \
  --output dashboard-snapshot.json

skills-orchestrator dashboard rollup \
  --snapshot dashboard-snapshot.json \
  --organization BambooGap \
  --output dashboard-rollup.json

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 schema validate \
  --kind registry-graph \
  --input registry-graph.json

skills-orchestrator schema validate \
  --kind enterprise-dashboard-snapshot \
  --input dashboard-snapshot.json

skills-orchestrator schema validate \
  --kind enterprise-dashboard-rollup \
  --input dashboard-rollup.json

skills-orchestrator schema list --format json > schema-catalog.json
skills-orchestrator schema validate \
  --kind schema-catalog \
  --input schema-catalog.json
skills-orchestrator schema audit --stability stable --format json > schema-audit.json
skills-orchestrator schema validate \
  --kind schema-audit \
  --input schema-audit.json

skills-orchestrator schema validate \
  --kind agent-handoff \
  --input examples/agent-handoff/release-review-handoff.json

skills-orchestrator schema validate \
  --kind agent-runtime-image \
  --input examples/agent-runtime-image/codex-worker-image.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 和版本化质量报告；enterprise profile 读取 evidence bundle 并验证核心 artifact schema，适合平台团队接入。evidence export 写出 check.json、check.sarif、ci-explainability.json、instruction-manifest.json、 policy-opa-input.json、`

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BambooGap
• Source: BambooGap/skills-orchestrator
• License: MIT
• Homepage: https://pypi.org/project/skills-orchestrator/

Install and usage instructions live in the source repository linked above.