# Skills Orchestrator

> Open-source SkillOps / instruction-supply-chain control plane for AI-agent teams: policy packs, registry diff, evidence bundles, SARIF/SBOM, adapters, and MCP runtime.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bamboogap-skills-orchestrator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BambooGap](https://agentstack.voostack.com/s/bamboogap)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BambooGap](https://github.com/BambooGap)
- **Source:** https://github.com/BambooGap/skills-orchestrator
- **Website:** https://pypi.org/project/skills-orchestrator/

## Install

```sh
agentstack add mcp-bamboogap-skills-orchestrator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/BambooGap/skills-orchestrator/actions/workflows/release-integrity.yml)
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](https://github.com/BambooGap/skills-orchestrator/releases/latest):
  release tag、source archive、release notes 和 release commit。
- [PyPI project](https://pypi.org/project/skills-orchestrator/): `skills-orchestrator`
  wheel / sdist；发布流程使用 PyPI Trusted Publishing 和 artifact attestations。
- [GHCR package](https://github.com/BambooGap/skills-orchestrator/pkgs/container/skills-orchestrator):
  多架构 OCI image，可按 tag 或 digest 拉取。
- [Post-release Smoke](https://github.com/BambooGap/skills-orchestrator/actions/workflows/post-release-smoke.yml):
  发布后核验 GitHub Release、PyPI install、consumer-side hash-locked install、GHCR
  image、Cosign signature、SBOM/provenance attestations、SLSA readiness report 和 starter kit path。
- [Release Integrity](https://github.com/BambooGap/skills-orchestrator/actions/workflows/release-integrity.yml):
  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)。

```bash
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`:

```bash
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 分钟）

### 安装

```bash
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:

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

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

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

### 初始化项目

```bash
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

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

启用团队标准规则：

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

启用工程级治理规则：

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

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

```bash
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 中运行：

```yaml
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](CODE_OF_CONDUCT.md), and [Third-party Notices](THIRD_PARTY_NOTICES.md):
  外部贡献、支持边界和依赖 notices 入口。

### SkillOps Readiness 与证据包

```bash
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](https://github.com/BambooGap)
- **Source:** [BambooGap/skills-orchestrator](https://github.com/BambooGap/skills-orchestrator)
- **License:** MIT
- **Homepage:** https://pypi.org/project/skills-orchestrator/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bamboogap-skills-orchestrator
- Seller: https://agentstack.voostack.com/s/bamboogap
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.