APM Onboarding
Welcome to Agent Primitives Management (APM) — the package management story for Calab.ai agent primitives. APM lets every consumer repository declare, install, and upgrade reusable AI building blocks (agents, instructions, prompts, skills, hooks, and init scripts) the same way any modern ecosystem manages its dependencies.
This onboarding set takes you end-to-end:
| Page | Use it when… |
|---|---|
| Concepts | You want a mental model — primitives, packages, registry, lockfile, provenance. |
| Authoring primitives | You are creating a new primitive (agent, skill, instructions, prompt, hook, or init). |
| Authoring packages | You are bundling existing primitives into an installable package. |
| Publishing | Your primitive or package is ready to release into calab-ai/apm-registry. |
| Installing | You are a consumer adding APM dependencies to a repository. |
| Upgrading | You need to bump versions, resolve drift, or sync a workspace. |
| Troubleshooting | A command failed and you need the exit-code map and common fixes. |
| Marketplace | You want to browse what is published today. |
Status: APM is GA at registry version
v1.6.1. The CLI surface ingh-calabis stable forinstall,catalog,validate, andimport;resolve,sync,lock,update,uninstall, and the explicitinstall package|primitivesubcommands are landing in active PRs — see each page for current status.
Quick start (consumer)
Already have a Calab.ai consumer repo? Get APM running in five commands.
# 1. Make sure you have the gh extension
gh extension install calab-ai/gh-calab
# 2. Sanity-check your environment
gh calab doctor
# 3. Initialize an APM workspace (creates apm.yml)
gh calab workspace init --tool copilot
# 4. Install the base workspace package
gh calab apm install calab-workspace-base
# 5. Verify what was installed
gh calab apm validateThis drops the GA calab-workspace-base package — the build and plan agents, coding-standards and security instructions, and the az-cli, gh-cli, and summarise skills — into .github/copilot/. Provenance is recorded in .generated-from-apm.json.
Read the full walk-through in Installing.
Quick start (author)
Want to publish a new primitive into the org registry? Three steps.
- Author — Add a new directory under
primitives/<type>/<name>/incalab-ai/apm-registry, including anapm-primitive.jsonmanifest and the primary content file (agent.md,SKILL.md, etc.). See Authoring primitives. - Validate — Run
python scripts/validate_primitive_manifests.pylocally; CI runs the same gate on every PR. - Release — Open a PR. Once merged, semantic-release tags
primitives/<type>/<name>/v<version>and the next catalog cut picks it up. See Publishing.
How APM fits the platform
flowchart LR subgraph Author["Authoring side"] A1[Author primitive] --> A2[apm-primitive.json] A2 --> A3[PR to apm-registry] end subgraph Registry["calab-ai/apm-registry"] R1[primitives/] R2[packages/] R3[catalog/portal-data.json] end subgraph Consumer["Consumer repo"] C1[apm.yml] C2[apm.lock.yaml] C3[Installed files + .generated-from-apm.json] end A3 --> R1 & R2 R1 & R2 --> R3 R3 --> Marketplace[(Marketplace portal)] R3 --> CLI[gh calab apm catalog] CLI --> C1 C1 --> Resolve[gh calab apm resolve] --> C2 --> Sync[gh calab apm sync] --> C3
For deeper architecture, see the existing APM Architecture Overview and APM Sequence Diagrams.
Where to go next
- Browsing: the APM Marketplace lists every published package and primitive.
- Decisions: ADR coverage lives under [00 Governance / Decisions](../../../00 Governance/Decisions/). See decisions [10](../../../00 Governance/Decisions/10 APM Registry Naming.md) through [15](../../../00 Governance/Decisions/15 APM Future Registry Service.md).
- Source of truth:
calab-ai/apm-registryandcalab-ai/gh-calab.