cmaform

cmaform is a Terraform-style CLI for managing Claude Managed Agents and their surrounding resources — agents, skills, memory stores, environments, vaults, and deployments — as files in your repo. You declare each resource as a YAML file, run cmaform plan to see what will change, and cmaform apply to ship it.

  [~] update agent       "release-prep" (id=agent_01Qx..., version=6)
       file: agents/release-prep.yaml
       ~ system:
           ... (12 unchanged lines)
         - prior wording...
         + revised wording...
           ... (8 unchanged lines)
  [+] create skill       "spec-lookup"
       dir:  skills/spec-lookup
       hash: 7b8b14094e01...

Plan (agents):         0 to add, 1 to change, 0 to archive, 5 unchanged.
Plan (skills):         1 to add, 0 to change, 0 to delete, 0 unchanged.
Plan (memory_stores):  0 to add, 0 to change, 0 to archive, 0 unchanged.
Plan (environments):   0 to add, 0 to change, 0 to archive, 1 unchanged.
Plan (vaults):         0 to archive, 1 unchanged.
Plan (deployments):    0 to add, 0 to change, 0 to archive, 1 unchanged.

⚡ Quick Start

Try it first

npx cmaform --help

Install and use

npm install -g cmaform

Bootstrap a new config directory and import an existing managed agent

export ANTHROPIC_API_KEY=sk-ant-...

mkdir my-agents && cd my-agents
cmaform pull agent_011CaSWcCrMdQdp4SA6TVdH6   # writes agents/<name>.yaml + state
cmaform plan                                  # show the diff
cmaform apply                                 # confirm → push to Anthropic

Claude Managed Agents and related APIs for Skills / Memory Stores / Environments / Vaults / Deployments are currently beta. cmaform calls @anthropic-ai/sdk's beta.agents.* / beta.skills.* / beta.memoryStores.* / beta.environments.* / beta.vaults.* / beta.deployments.* endpoints directly.

🚀 Usage

Commands

Command	What it does
`cmaform pull <id> [--by-id]`	Import a remote resource by ID (`agent_` / `skill_` / `memstore_` / `env_` / `vlt_` / `deploy_`) into local files + state. Pass `--by-id` to keep raw IDs in the written agent / deployment YAML instead of rewriting refs to the name form
`cmaform plan [--verbose\|-v] [target...]`	Diff local YAML / state / remote and print a Terraform-style plan. Requires an existing `cmaform.state.json` from `init` or `pull`
`cmaform apply [--yes\|-y] [--verbose\|-v] [target...]`	Show plan, prompt for confirmation, apply, save state. Requires an existing `cmaform.state.json` from `init` or `pull`
`cmaform sync [--by-id]`	Re-fetch every entry in state from remote and rewrite local YAML. Pass `--by-id` to keep raw IDs in the written agent YAML instead of rewriting refs to the name form
`cmaform init`	Initialize / reconcile the state file against remote (no remote writes; spirit of `terraform init`)
`cmaform list`	Show local files / state / remote side-by-side
`cmaform fmt`	Rewrite `multiagent.agents[].id` / `skills[].skill_id` in local YAML to the name form, using `cmaform.state.json` for the id → name lookup

Filtering plan / apply

The last positional arguments to plan and apply are targets. A target can be a resource kind or an individual resource name — useful for staged rollouts (e.g. create a skill first, copy its skill_id into an agent YAML, then apply the agent).

cmaform apply skills                     # all skills
cmaform apply agents                     # all agents
cmaform apply slack-mention-lookup       # a single skill by name
cmaform apply release-prep --yes         # a single agent, skip confirmation
cmaform apply skills release-prep        # all skills + one agent

A <target> is either a kind alias (matches every resource of that type) or the individual name of one specific resource. Use the table below for kind aliases; anything else is treated as a resource name.

Resource	Kind aliases	Individual name format	Example
Agent	`agent` / `agents`	`name:` field in the YAML	`release-prep` (`agents/release-prep.yaml`)
Skill	`skill` / `skills`	directory name under `skills/`	`slack-mention-lookup` (`skills/slack-mention-lookup/`)
Memory Store	`memory_store` / `memory_stores` / `memstore` / `memstores`	directory name under `memory_stores/`	`team-notes` (`memory_stores/team-notes/`)
Environment	`environment` / `environments` / `env` / `envs`	directory name under `environments/`	`python-dev` (`environments/python-dev/`)
Vault	`vault` / `vaults`	directory name under `vaults/`	`my-bot` (`vaults/my-bot/`)
Deployment	`deployment` / `deployments` / `deploy` / `deploys`	directory name under `deployments/`	`nightly` (`deployments/nightly/`)

plan expands create / update diffs symmetrically: a new resource is rendered as + field: ... blocks just like an update is rendered as ~ field: ... blocks. Long string fields (system, description) are truncated to 3 lines plus an ... (N lines hidden) marker. Pass --verbose to show full content.

If you pass an individual name that doesn't exist anywhere (local YAML, state, or remote), cmaform exits with code 2. An unmatched kind is fine — it just shows 0 to add, 0 to change, ....

Pulling existing resources

cmaform pull agent_011CaSWcCrMdQdp4SA6TVdH6   # writes agents/<name>.yaml
cmaform pull skill_013uPS15B3Kw82NpjH4uNQep   # state only — SKILL.md is not regenerated
cmaform pull memstore_01ABC...                # writes memory_stores/<name>/manifest.yaml
cmaform pull env_015G...                      # writes environments/<name>/manifest.yaml
cmaform pull vlt_011CaQ...                    # writes vaults/<name>/manifest.yaml (credentials not managed yet)
cmaform pull deploy_01Gk...                   # writes deployments/<name>/manifest.yaml + state

Skill content is not returned by the Anthropic API once uploaded, so pull for skills only records the ID + version + display title into state. The local SKILL.md must be authored by you.

📦 Resources

cmaform manages six resource types — agents, skills, memory stores, environments, vaults, and deployments. Each lives under its own top-level directory beneath the config root. (Create vaults with cmaform, then finish configuring them on the Anthropic Console.)

Agent (`agents/<name>.yaml`)

name: my-agent # unique within the workspace — this is the identity key
model:
  id: claude-sonnet-4-6
  speed: standard # standard | fast
description: short description
system: |-
  ... full system prompt ...
mcp_servers:
  - name: slack
    type: url
    url: https://mcp.slack.com/mcp
tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: true
      permission_policy:
        type: always_allow
    configs: []
skills: []
metadata: {}

Identity: the name field. agent_id lives in state, not YAML.
Diff: deep-equal on name / model / description / system / tools / mcp_servers / skills / multiagent / metadata.
Delete: present in state but missing locally ⇒ archive (reversible).
Arrays (tools, mcp_servers, skills) are fully replaced — local is the source of truth.

See the Anthropic Agent Setup docs for the full schema.

Skill (`skills/<localName>/`)

Each skill is a directory. The Anthropic API uploads a folder containing SKILL.md plus any auxiliary files.

skills/<localName>/
├── SKILL.md            # required (YAML frontmatter + markdown body)
├── REFERENCE.md        # optional
└── scripts/
    └── helper.py       # optional

SKILL.md requires frontmatter:

---
name: my-skill
description: What this skill does, and when Claude should use it.
---

# My Skill

...

name: ≤64 chars, [a-z0-9-] only. anthropic / claude are reserved.
description: ≤1024 chars.

cmaform computes a SHA-256 hash of the entire directory and compares it against the hash stored in state. If they differ, apply uploads a new version of the skill.

Referencing a skill from an agent

# agents/foo.yaml
skills:
  - type: anthropic
    skill_id: xlsx # well-known Anthropic skills stay id-based
  - type: custom
    name: slack-mention-lookup # = local directory name under skills/
    version: latest # optional

The raw-ID form (skill_id: skill_01XXXXXX) is also accepted for type: custom — name and skill_id are interchangeable. See Name-based references below for resolution semantics.

⚠️ Skills cannot be archived. Deleting the directory and running apply permanently deletes the skill and all of its versions.

🔗 Name-based references

multiagent.agents[] and skills[] accept references by logical name in addition to raw IDs. Names are resolved at plan / apply time, so YAML can reference resources without committing any workspace-specific IDs.

# agents/coordinator.yaml
multiagent:
  type: coordinator
  agents:
    - type: agent
      name: spec-qa # = the `name` field of agents/spec-qa.yaml
    - type: agent
      name: release-prep
      version: latest # optional
skills:
  - type: custom
    name: slack-mention-lookup # = the directory name under skills/

Resolution order for each name:

cmaform.state.json — if the resource is already tracked locally, use its ID.
Remote — findAgentByName / findSkillByDisplayTitle (cached per run).
Local apply set — if a YAML for that name exists locally and is being created in this run, the reference is treated as a forward dependency. cmaform substitutes a placeholder during plan and replaces it with the real ID right after the dependency is created.

If none of the above match, plan / apply fails with an error pointing at the unresolved name.

`pull` / `sync` write back in name form

When writing remote agents back to YAML, cmaform replaces any id / skill_id that resolves to a known local name with the name form. IDs for resources not tracked in state are kept as-is.

Pass --by-id to pull / sync to opt out of the rewrite and keep raw IDs in the written YAML.

Raw-ID form

{ type: agent, id: agent_... } and { type: custom, skill_id: skill_... } are also accepted and behave identically to the name form.

If an entry writes both name: and id: (or skill_id:), cmaform resolves the name and asserts that it matches the pinned ID. Mismatches abort plan / apply with a clear error. This is useful as a safety net while migrating from id-based references — cmaform fmt can then drop the redundant raw IDs once everything verifies.

type: anthropic skills (well-known IDs like xlsx) always use the skill_id form. type: self agent references take neither.

Memory Store (`memory_stores/<localName>/manifest.yaml`)

name: my-store
description: optional
metadata:
  team: platform

Diff fields: name / description / metadata.
metadata is patched: keys missing locally are deleted, others are upserted.
Delete = archive (one-way; the store's memory data is preserved).

Environment (`environments/<localName>/manifest.yaml`)

name: python-dev
description: optional
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy==2.2.0
    npm:
      - express
  networking:
    type: limited
    allowed_hosts:
      - https://api.example.com
    allow_mcp_servers: true
    allow_package_managers: true
metadata: {}

Diff fields: name / description / metadata / config.
Only config.type: cloud is currently supported (self-hosted environments are out of scope).
Empty package lists, false defaults in limited networking, and the server-side type: 'packages' marker are normalized away so the plan is idempotent.
Delete = archive. Archived environments stop accepting new sessions but existing sessions keep working.

Vault (`vaults/<localName>/`)

Status: ⚠️ Partial support — vault design is still evolving in cmaform.

Operation Supported by cmaform Notes

Create vault ✅ New local manifest → vault is created on the server.

Archive vault ✅ Removing a local manifest archives the vault. Cascades server-side to attached credentials.

Update vault ❌ Edits to display_name / metadata after creation are silently ignored. Archive and recreate to rename / relabel.

Manage credentials ❌ Credentials are not yet managed by cmaform — the secret-resolution design is still being settled. Use the Anthropic Vault Credentials API directly to attach / rotate credentials.

The vault scope will be expanded (update, credential management with secret backends) in a future release.

A vault is a container that holds credentials for MCP servers. The local layout is intentionally minimal in this release:

vaults/
└── my-bot/
    └── manifest.yaml

manifest.yaml — the vault definition:

display_name: my-bot
metadata:
  external_user_id: bot

Deployment (`deployments/<localName>/manifest.yaml`)

A deployment binds an agent + environment + initial events + an optional cron schedule into one unit. The platform creates a session from the deployment on each schedule fire (and lets you trigger one on demand). This is how a managed agent runs on a schedule.

name: nightly-triage # unique within the workspace
description: optional
# Reference an agent by name (resolved via state -> remote -> local apply set)
# or by raw id. Omit `version` to track the latest at create time, or pin one.
agent: release-prep
# agent:
#   name: release-prep
#   version: 6
environment: python-dev # environment name or env_... id
# Events sent to each session immediately after creation (1–50).
initial_events:
  - type: user.message
    content:
      - type: text
        text: Run the nightly triage.
# Optional. 5-field POSIX cron (minute hour day-of-month month day-of-week).
# Extended syntax (seconds/year, L W # ?, @daily) is NOT supported. Omit the
# whole block for an on-demand (manual-run) deployment.
schedule:
  type: cron
  expression: '0 9 * * 1-5' # 09:00 on weekdays
  timezone: Asia/Tokyo # IANA timezone
# Optional. Resources mounted into each session's container.
resources: []
# Optional. Vault names or vlt_... ids supplying stored credentials.
vault_ids: []
metadata: {}

Identity: the name field. The deployment_id lives in state, not YAML.
Diff fields: name / description / agent / environment_id / initial_events / schedule / resources / vault_ids / metadata.
References: agent / environment / vault_ids[] accept logical names (resolved at plan/apply time, same rules as Name-based references) or raw ids. A name pointing at a resource being created in the same apply run is treated as a forward dependency — cmaform creates it first, then the deployment.
Agent version: omit version to track the latest at create time (version drift is then ignored in the diff). Pin a version to detect and re-pin changes.
Delete: present in state but missing locally ⇒ archive (one-way; the schedule stops firing).
Out of scope: the imperative pause / unpause / run transitions are not modeled declaratively — status is treated as remote-owned. resources containing write-only credentials (e.g. a GitHub authorization_token) are sent on create/update but stripped before diffing, so they never appear as a permanent change.

See the Anthropic Deployments docs for the full schema.

🗂️ Directory Layout

cmaform reads from the current working directory (or CMAFORM_DIR if set):

<cwd>/
├── agents/
│   └── *.yaml
├── skills/
│   └── <localName>/SKILL.md
├── memory_stores/
│   └── <localName>/manifest.yaml
├── environments/
│   └── <localName>/manifest.yaml
├── vaults/
│   └── <localName>/manifest.yaml
├── deployments/
│   └── <localName>/manifest.yaml
└── cmaform.state.json

🧾 State File (`cmaform.state.json`)

{
  "agents": {
    "release-prep": { "id": "agent_01Qx...", "version": 6 }
  },
  "skills": {
    "slack-mention-lookup": {
      "id": "skill_013uPS...",
      "version": "1778647403232223",
      "hash": "7b8b14094e01...",
      "display_title": "slack-mention-lookup"
    }
  },
  "memory_stores": {
    "team-notes": { "id": "memstore_01...", "name": "team-notes" }
  },
  "environments": {
    "python-dev": { "id": "env_01...", "name": "python-dev" }
  },
  "vaults": {
    "my-bot": { "id": "vlt_01...", "display_name": "my-bot" }
  },
  "deployments": {
    "nightly-triage": { "id": "deploy_01...", "name": "nightly-triage" }
  }
}

Maintained by pull / apply / sync / init.
Recommended to .gitignore (treat as the local source of truth, like a Terraform state file).
If someone shares a state file with you, run cmaform sync to regenerate the local YAML for every agent (skill bodies cannot be restored — see above).

🔐 Environment Variables

Variable	Required	Purpose
`ANTHROPIC_API_KEY`	✅	Anthropic API authentication
`CMAFORM_DIR`		Config root directory (default: `cwd`)

⚠️ Caveats

Renaming an agent creates a new agent. To rename, delete the old YAML, run apply (archives the old one), then add the new YAML with the new name.
Deleting a skill directory and running apply is destructive — there is no archive for skills.
For full reproducibility, avoid making manual changes in the Anthropic Console. Always go through the YAML / SKILL.md / manifest.yaml.

🛠️ Development

mise install
pnpm install
pnpm dev -- --help     # run from source (tsx)
pnpm typecheck
pnpm build             # bundle to dist/cli.js via tsup
node dist/cli.js --help

📋 Requirements

Node.js ≥ 22
An Anthropic API key with access to the Claude Managed Agents and related Skills / Memory Stores / Environments / Vaults / Deployments beta APIs

📄 License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.agents/skills/release-procedure		.agents/skills/release-procedure
.claude/skills		.claude/skills
.codex/skills		.codex/skills
.github/workflows		.github/workflows
examples		examples
src		src
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.ja.md		README.ja.md
README.md		README.md
SECURITY.md		SECURITY.md
lefthook.yml		lefthook.yml
mise.toml		mise.toml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
renovate.json		renovate.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

cmaform

⚡ Quick Start

🚀 Usage

Commands

Filtering plan / apply

Pulling existing resources

📦 Resources

Agent (`agents/<name>.yaml`)

Skill (`skills/<localName>/`)

Referencing a skill from an agent

🔗 Name-based references

`pull` / `sync` write back in name form

Raw-ID form

Memory Store (`memory_stores/<localName>/manifest.yaml`)

Environment (`environments/<localName>/manifest.yaml`)

Vault (`vaults/<localName>/`)

Deployment (`deployments/<localName>/manifest.yaml`)

🗂️ Directory Layout

🧾 State File (`cmaform.state.json`)

🔐 Environment Variables

⚠️ Caveats

🛠️ Development

📋 Requirements

📄 License

About

Releases

Packages

Contributors

Languages

Operation	Supported by cmaform	Notes
Create vault	✅	New local manifest → vault is created on the server.
Archive vault	✅	Removing a local manifest archives the vault. Cascades server-side to attached credentials.
Update vault	❌	Edits to `display_name` / `metadata` after creation are silently ignored. Archive and recreate to rename / relabel.
Manage credentials	❌	Credentials are not yet managed by cmaform — the secret-resolution design is still being settled. Use the Anthropic Vault Credentials API directly to attach / rotate credentials.

Folders and files

Latest commit

History

Repository files navigation

cmaform

⚡ Quick Start

🚀 Usage

Commands

Filtering plan / apply

Pulling existing resources

📦 Resources

Agent (agents/<name>.yaml)

Skill (skills/<localName>/)

Referencing a skill from an agent

🔗 Name-based references

pull / sync write back in name form

Raw-ID form

Memory Store (memory_stores/<localName>/manifest.yaml)

Environment (environments/<localName>/manifest.yaml)

Vault (vaults/<localName>/)

Deployment (deployments/<localName>/manifest.yaml)

🗂️ Directory Layout

🧾 State File (cmaform.state.json)

🔐 Environment Variables

⚠️ Caveats

🛠️ Development

📋 Requirements

📄 License

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Agent (`agents/<name>.yaml`)

Skill (`skills/<localName>/`)

`pull` / `sync` write back in name form

Memory Store (`memory_stores/<localName>/manifest.yaml`)

Environment (`environments/<localName>/manifest.yaml`)

Vault (`vaults/<localName>/`)

Deployment (`deployments/<localName>/manifest.yaml`)

🧾 State File (`cmaform.state.json`)