Cargo CDK — declarative workspace-as-code

Use this skill to define a Cargo workspace in TypeScript (

define*

builders from

@cargo-ai/cdk

) and reconcile it to live infrastructure with

cargo-ai cdk deploy

. It is the declarative counterpart to the imperative capability skills: instead of running one CLI command per resource, you write the whole graph once and deploy it repeatably, with a committed

cargo.state.json

linking your code to what Cargo created.

1) What this skill governs

Authoring every Cargo resource with a
```
define*
```
builder that returns a handle; wiring resources by passing handles to each other (the dependency graph is your variable graph).
Deploying the graph:
```
plan
```
(offline diff) →
```
deploy
```
(create/update, write state) →
```
destroy
```
(tear down). Plus drift (
```
refresh
```
), adoption (
```
import
```
), and recovery (
```
rollback
```
).
Typing the config against your workspace's real integration schemas (
```
cargo-ai cdk types
```
).

The CDK spans every resource kind — so it overlaps every imperative capability skill (

cargo-connection

cargo-storage

cargo-ai

cargo-orchestration

cargo-content

cargo-hosting

, …). Which to reach for is the first decision:

2) CDK or the CLI? — the routing decision

Declarative (this skill) vs imperative (a capability skill).

Use the CDK when the user is managing resources as an artifact:

"Set up / stand up / bootstrap a whole workspace (as code / from a template)."
"Make this reproducible / version-controlled / in git / repeatable across environments (dev → prod)."
"Deploy these connectors + models + agents together" (a multi-resource graph wired by dependency).
Anything that should be re-runnable and diffable, where losing the definition would be a problem.

Use the matching capability skill (imperative

cargo-ai <domain>

) when the user is doing a one-off operation or exploring:

"Create one connector", "add a column to this model", "list connectors", "run this workflow", "query storage", "read this agent's memory."
Any read, ad-hoc query, or single mutation that doesn't need to live in code.

When unsure, ask whether the result should be committed and re-deployable. If yes → CDK. If it's a quick action or a read → the capability skill (see the

cargo

router to pick the right domain).

3) The lifecycle

cargo-ai cdk init <dir>     scaffold a project from a template (blank | full)
        │
cargo-ai cdk types          generate per-workspace types for typed config (optional)
        │
   (author define* files)   importing a .ts file IS registration — no manifest
        │
cargo-ai cdk plan           offline: compile the graph, diff against cargo.state.json
        │
cargo-ai cdk deploy         create/update resources in dependency order, write state
        │
cargo-ai cdk destroy        tear down resources recorded in state

Side branches:

cargo-ai cdk refresh

(read-only drift report) ·

deploy --refresh

(re-apply code over out-of-band edits) ·

deploy --prune

(delete resources removed from code) ·

cargo-ai cdk import <id> <uuid>

(bind an existing live resource into state) ·

cargo-ai cdk rollback

(restore the pre-deploy state snapshot).

4) Documentation hierarchy

Level 1 —
```
SKILL.md
```
(this file): the decision model, lifecycle, critical rules, and routing.

Level 2 — Guides:

guides/authoring-resources.md

guides/deploy-and-state.md

guides/typed-config.md

Level 2.5 — Recipes:
```
recipes/*.md
```
— step-by-step playbooks to follow as your execution plan.

References —

references/resources.md

(the full builder catalog),

references/commands.md

(every

cargo-ai cdk

subcommand + flags),

references/troubleshooting.md

, and

references/examples/full-workspace.md

5) Read behavior — match the task to a doc and READ IT

When the task involves…	Read this first	What it gives you
Writing `define*` files, wiring resources, `secret()` / `env()` , `defineWorkflow` bodies (tool/play logic)	`guides/authoring-resources.md`	The builder catalog, the handle/ref model, secrets, and how workflow bodies compile.
`plan` / `deploy` / `destroy` , the state file, drift, adopting existing resources, CI	`guides/deploy-and-state.md`	The deploy lifecycle, `cargo.state.json` semantics, drift/import/rollback, async builds.
Typed config, `cargo-ai cdk types` , tsconfig wiring, `integrations.*` in workflow bodies	`guides/typed-config.md`	What `cdk types` generates and how to wire it into your project.
A field/spec/output for a specific builder	`references/resources.md`	Every builder → spec fields → which ref each takes → outputs.
Exact command flags	`references/commands.md`	Every `cargo-ai cdk` subcommand and its flags.
A deploy error / footgun	`references/troubleshooting.md`	The known failure modes and fixes.

Recipes — follow step-by-step when one matches

Recipe	Use when…
`recipes/scaffold-a-workspace.md`	Standing up a new workspace from scratch ( `init --template full` → types → plan → deploy).
`recipes/add-connector-and-model.md`	Adding a data source + a model sourced from it, wired by handle.
`recipes/build-an-agent.md`	Composing a model + tool + agent (with `uses` / `models` / `tools` ) and deploying.
`recipes/migrate-existing-workspace.md`	Bringing an already-live workspace under CDK management via `cdk import` .
`recipes/deploy-from-ci.md`	Deploying non-interactively from CI (token auth + committed state).

6) Critical rules

Commit
cargo.state.json
. It is the link from your code to the resources Cargo created — and the only handle on a deployed play or agent (they have no slug). Lose it and those resources orphan; recover a link with
```
cargo-ai cdk import
```
. It records only
```
{hash, uuid, outputs}
```
— never secret values. Git-ignore the working files (
```
cdk init
```
scaffolds this):
gitignore
```
.cargo-ai/
cargo.state.lock
cargo.state.bak.json
cargo.state.audit.jsonl
```
Secrets: wire credentials with
```
secret("ENV_VAR")
```
(often
```
secret("HUBSPOT_API_KEY")
```
). The value is read from the environment at deploy time, kept out of the content hash and out of state, so rotating a token doesn't read as drift. Export the env var before deploying — a missing one fails the deploy with an unresolved
```
${ENV_VAR}
```
placeholder.
Wire by handle, never by
.uuid
. Pass a
```
define*
```
handle directly (
```
dataset: hubspot
```
,
```
tools: [enrich]
```
), or
```
xxRef("uuid")
```
for a resource you didn't define in code (
```
connectorRef
```
,
```
modelRef
```
,
```
folderRef
```
,
```
toolRef
```
,
```
agentRef
```
, …). Where a reference needs per-call options, wrap it as
```
{ ref, …options }
```
(e.g.
```
models: [{ ref: contacts, readOnly: true }]
```
).
Run
cargo-ai cdk types
after workspace integrations change — it regenerates
```
.cargo-ai/
```
so
```
defineConnector
```
/
```
defineModel
```
config (and
```
integrations.*
```
in workflow bodies) type-check against the real schemas. Typing is a bonus, never a gate: deploy works without it.
Run
cdk
commands from the project root.
```
npx
```
/
```
cargo-ai
```
resolve from the nearest
```
package.json
```
; run elsewhere and
```
.cargo-ai/
```
and
```
cargo.state.json
```
land in the wrong directory. Use
```
--dir <path>
```
to be explicit.
--yes
in CI.
```
deploy
```
and
```
destroy
```
prompt for confirmation; non-interactive runs must pass
```
--yes
```
.

Prerequisites

Standard Cargo CLI setup (install, login, output conventions) is shared across all skills — see

../cargo/references/prerequisites.md

Two CDK-specific extras:

The project needs
@cargo-ai/cdk
as a dependency (for the
```
define*
```
builders you import).
```
cargo-ai cdk init
```
scaffolds a
```
package.json
```
with it — then run
```
npm install
```
.

The
cargo-ai cdk
domain ships with the CLI. Confirm with

cargo-ai cdk --help

; an

unknown command

means the CLI is too old —

npm install -g @cargo-ai/cli@latest

Help

cargo-ai cdk --help

and

cargo-ai cdk <subcommand> --help

for the live flag surface.

When a documented command/flag/response doesn't match what you observe, file a report:
```
cargo-ai workspaceManagement report create
```
(see
```
../cargo-workspace-management/SKILL.md
```
).

cargo-cdk

NPX Install

Tags

SKILL.md Content