Authoring APM Primitives

A primitive is a single, independently versioned building block. This page covers the shared manifest contract and the per-type rules.

Source of truth: schemas/apm-primitive.schema.json (JSON Schema Draft 2020-12). Anything on this page that diverges from the schema is a bug — open an issue against calab-ai/apm-registry.

---

1. Pick a directory

Every primitive lives at:

primitives/<type>/<name>/

• <type> is one of agents, instructions, prompts, skills, hooks, init (always plural; matches the schema enum).
• <name> is kebab-case matching ^[a-z][a-z0-9-]+$. Pick the same name as the directory.

Convention: small, focused names. gh-cli, not github-and-related-cli-helpers. If two primitives feel like the same thing, they probably are.

2. Write apm-primitive.json

Required fields:

Field	Type	Notes
id	string	Reverse-domain id matching ^[a-z][a-z0-9]*\.(agent|instructions|prompt|skill|hook|init)\.[a-z][a-z0-9-]+$. Note the singular type segment. Use calab.<type>.<name>.
type	string	One of agents, instructions, prompts, skills, hooks, init. Must match the directory.
name	string	kebab-case, matches the directory name.
version	string	Semver MAJOR.MINOR.PATCH (optional prerelease). Drives the release tag.
description	string	One-sentence catalog description.

Recommended optional fields:

Field	Use it for
maintainers	["calab-ai"] for org-owned content, otherwise GitHub handles or team slugs.
tags	Searchable strings for the marketplace (e.g. ["copilot", "azure", "cli"]).
compatibility.tools	Subset of copilot, claude, codex, opencode, any.
compatibility.min_catalog_version	Set when you depend on a newer catalog feature.
entrypoint	Primary content file (agent.md, SKILL.md, …).
files	Every file shipped (paths primitive-relative, forward-slash, no ..).

A canonical, schema-clean example (the az-cli skill primitive):

{
  "$schema": "https://raw.githubusercontent.com/calab-ai/apm-registry/main/schemas/apm-primitive.schema.json",
  "id": "calab.skill.az-cli",
  "type": "skills",
  "name": "az-cli",
  "version": "1.0.0",
  "description": "Use Azure CLI safely for tenant, subscription, resource, and Microsoft Entra operations.",
  "maintainers": ["calab-ai"],
  "tags": ["skills", "copilot", "azure", "cli"],
  "compatibility": { "tools": ["copilot"] },
  "entrypoint": "SKILL.md",
  "files": ["SKILL.md"]
}

Always set $schema so editors give you live validation.

3. Validate locally

pip install 'jsonschema==4.*'
python scripts/validate_primitive_manifests.py

The same script runs in CI via .github/workflows/validate-primitive-manifests.yml. PRs that fail this gate are blocked.

---

Per-type authoring rules

agents

• Entrypoint: agent.md.
• Required content: YAML frontmatter (name, description, tools) followed by the system prompt. Mirror the existing build and plan agents.
• Sizing: keep agents single-purpose. If you find yourself describing two modes, ship two agents.
• Install snippet (single-arg auto-detect — works today):

  gh calab apm install calab.agent.build

instructions

• Entrypoint: instructions.md.
• Required content: YAML frontmatter with applyTo glob (e.g. **/*, **/*.ts) and the rule body. See coding-standards and security.
• Convention: instructions are always-on; keep them short and assertion-shaped (“Use…”, “Never…”).
• Install snippet:

  gh calab apm install calab.instructions.coding-standards

prompts

• Entrypoint: prompt.md.
• Required content: Frontmatter declaring inputs/parameters, then the prompt template body. The prompts/ directory currently contains only the README.md placeholder — the first real prompt should follow the agent/instructions conventions and be added under primitives/prompts/<name>/.
• Install snippet:

  gh calab apm install calab.prompt.<name>

skills

• Entrypoint: SKILL.md.
• Required content: Frontmatter (name, description, license) and a body that documents capabilities, prerequisites, and invocation patterns. Example: gh-cli, az-cli.
• Bundled scripts: ship them under the primitive directory and list every path in files.
• Install snippet:

  gh calab apm install calab.skill.gh-cli

hooks

• Entrypoint: hook.ps1 (or hook.sh on POSIX).
• Required content: A small executable script invoked by the agent runtime pre/post task. Frontmatter or a sibling metadata.json should declare event and runOn constraints.
• Status: the hooks/ directory currently ships only the README.md placeholder. The first real hook should follow the existing primitive directory layout.
• Install snippet:

  gh calab apm install calab.hook.<name>

init

• Entrypoint: init.ps1 (or init.sh).
• Required content: First-run workspace setup. The script must be idempotent — safe to re-run on every apm sync.
• Reference: cloud-agent-setup is the canonical example.
• Install snippet:

  gh calab apm install calab.init.cloud-agent-setup

---

Path rules (apply to every type)

entrypoint and every files entry:

• Use forward slashes only.
• Are primitive-relative — never absolute.
• Never contain . or .. segments, backslashes, or Windows-invalid characters.

The schema enforces this with the relative-path regex; CI will reject violations.

Ready to publish?

Continue to Publishing.

Related

• Concepts
• Authoring packages
• Existing primitives (browse): primitives/
• Reference: docs/apm-primitive-manifest.md in the registry