Update to Cargo CLI

{
  "name": "cargo-cdk",
  "description": "Manage a whole Cargo workspace as code — declare connectors, models, plays, tools, agents, MCP servers, segments, context, folders, files, workers, and apps in TypeScript, then reconcile them with `cargo-ai cdk` (init → types → plan → deploy), the way you would run Pulumi or the AWS CDK. Triggers: \"as code\", \"in git\", \"version-controlled\", \"reproducible\", \"Terraform for Cargo\", \"set up a whole workspace\", \"staging and production\", \"deploy from CI\", \"review this in a PR\", \"cargo.state.json\", \"scaffold from a template\", \"is there a cookbook for this\", \"start from a cookbook\". Skills with a CDK example (TAM building, account scoring, contact sourcing, routing, AI SDR, rep cockpit) live in gtm-skills; menu in references/cookbooks.md. Skip when: it is a one-off operation, a read, or an ad-hoc query — use the matching capability skill.",
  "included_files": [
    {
      "relative_path": "guides/authoring-resources.md",
      "size_in_bytes": 10740
    },
    {
      "relative_path": "guides/deploy-and-state.md",
      "size_in_bytes": 4952
    },
    {
      "relative_path": "guides/typed-config.md",
      "size_in_bytes": 2811
    },
    {
      "relative_path": "recipes/add-connector-and-model.md",
      "size_in_bytes": 2247
    },
    {
      "relative_path": "recipes/build-an-agent.md",
      "size_in_bytes": 2971
    },
    {
      "relative_path": "recipes/deploy-from-ci.md",
      "size_in_bytes": 2476
    },
    {
      "relative_path": "recipes/migrate-existing-workspace.md",
      "size_in_bytes": 2532
    },
    {
      "relative_path": "recipes/scaffold-a-workspace.md",
      "size_in_bytes": 2636
    },
    {
      "relative_path": "references/commands.md",
      "size_in_bytes": 2460
    },
    {
      "relative_path": "references/cookbooks.md",
      "size_in_bytes": 3857
    },
    {
      "relative_path": "references/examples/full-workspace.md",
      "size_in_bytes": 4312
    },
    {
      "relative_path": "references/resources.md",
      "size_in_bytes": 6745
    },
    {
      "relative_path": "references/troubleshooting.md",
      "size_in_bytes": 3775
    },
    {
      "relative_path": "skill-metadata.json",
      "size_in_bytes": 2220
    }
  ],
  "skill_md_contents": "---\nname: cargo-cdk\ndescription: \"Manage a whole Cargo workspace as code — declare connectors, models, plays, tools, agents, MCP servers, segments, context, folders, files, workers, and apps in TypeScript, then reconcile them with `cargo-ai cdk` (init → types → plan → deploy), the way you would run Pulumi or the AWS CDK. Triggers: \\\"as code\\\", \\\"in git\\\", \\\"version-controlled\\\", \\\"reproducible\\\", \\\"Terraform for Cargo\\\", \\\"set up a whole workspace\\\", \\\"staging and production\\\", \\\"deploy from CI\\\", \\\"review this in a PR\\\", \\\"cargo.state.json\\\", \\\"scaffold from a template\\\", \\\"is there a cookbook for this\\\", \\\"start from a cookbook\\\". Skills with a CDK example (TAM building, account scoring, contact sourcing, routing, AI SDR, rep cockpit) live in gtm-skills; menu in references/cookbooks.md. Skip when: it is a one-off operation, a read, or an ad-hoc query — use the matching capability skill.\"\nversion: \"1.2.3\"\ncompatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token\nhomepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CDK — declarative workspace-as-code\n\nUse this skill to define a Cargo workspace in TypeScript (`define*` builders from\n`@cargo-ai/cdk`) and reconcile it to live infrastructure with `cargo-ai cdk deploy`.\nIt is the **declarative** counterpart to the imperative capability skills: instead\nof running one CLI command per resource, you write the whole graph once and deploy\nit repeatably, with a committed `cargo.state.json` linking your code to what Cargo\ncreated.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\ncargo-ai cdk --help                     # `unknown command` = CLI too old; reinstall @cargo-ai/cli@latest\n```\n\nTwo 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 `npm install`), and the `cargo-ai cdk` domain ships with the CLI itself.\n\nEvery command prints JSON to stdout; failures exit non-zero with `{\"errorMessage\": \"...\"}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.\n\n## 1) What this skill governs\n\n- **Authoring** every Cargo resource with a `define*` builder that returns a\n  **handle**; wiring resources by passing handles to each other (the dependency\n  graph is your variable graph).\n- **Deploying** the graph: `plan` (offline diff) → `deploy` (create/update, write\n  state) → `destroy` (tear down). Plus drift (`refresh`), adoption (`import`), and\n  recovery (`rollback`).\n- **Typing** the config against your workspace's real integration schemas\n  (`cargo-ai cdk types`).\n\nThe CDK spans **every** resource kind — so it overlaps every imperative capability\nskill (`cargo-connection`, `cargo-storage`, `cargo-ai`, `cargo-orchestration`,\n`cargo-content`, `cargo-hosting`, …). Which to reach for is the first decision:\n\n## 2) CDK or the CLI? — the routing decision\n\n> **Declarative (this skill) vs imperative (a capability skill).**\n\nUse the **CDK** when the user is **managing resources as an artifact**:\n\n- \"Set up / stand up / bootstrap a whole workspace (as code / from a template).\"\n- \"Make this reproducible / version-controlled / in git / repeatable across\n  environments (dev → prod).\"\n- \"Deploy these connectors + models + agents together\" (a multi-resource graph\n  wired by dependency).\n- Anything that should be re-runnable and diffable, where losing the definition\n  would be a problem.\n\nUse the matching **capability skill** (imperative `cargo-ai <domain>`) when the\nuser is doing a **one-off operation** or **exploring**:\n\n- \"Create one connector\", \"add a column to this model\", \"list connectors\",\n  \"run this workflow\", \"query storage\", \"read this agent's memory.\"\n- Any read, ad-hoc query, or single mutation that doesn't need to live in code.\n\nWhen unsure, ask whether the result should be committed and re-deployable. If yes\n→ CDK. If it's a quick action or a read → the capability skill (see the\n[`cargo` router](../cargo/SKILL.md) to pick the right domain).\n\n## 3) The lifecycle\n\n```\ncargo-ai cdk init <dir>     scaffold a project from a template (blank | full)\n        │\ncargo-ai cdk types          generate per-workspace types for typed config (optional)\n        │\n   (author define* files)   importing a .ts file IS registration — no manifest\n        │\ncargo-ai cdk plan           offline: compile the graph, diff against cargo.state.json\n        │\ncargo-ai cdk deploy         create/update resources in dependency order, write state\n        │\ncargo-ai cdk destroy        tear down resources recorded in state\n```\n\n> **`cdk plan` says what resources change; it doesn't show what a play does.**\n> For a `definePlay` / `defineTool` graph past three nodes, present a Mermaid\n> flowchart of the node graph alongside the plan — routing, fallbacks, and which\n> nodes bill on every scheduled run are what the reviewer is approving. Generate it\n> from the deployed release after the first deploy, or from the node array while\n> authoring:\n> [`../cargo-orchestration/references/node-diagram.md`](../cargo-orchestration/references/node-diagram.md).\n\nSide branches: `cargo-ai cdk refresh` (read-only drift report) · `deploy --refresh`\n(re-apply code over out-of-band edits) · `deploy --prune` (delete resources removed\nfrom code) · `cargo-ai cdk import <id> <uuid>` (bind an existing live resource into\nstate) · `cargo-ai cdk rollback` (restore the pre-deploy state snapshot).\n\n## 4) Documentation hierarchy\n\n- **Level 1** — `SKILL.md` (this file): the decision model, lifecycle, critical\n  rules, and routing.\n- **Level 2** — Guides:\n  [`guides/authoring-resources.md`](guides/authoring-resources.md),\n  [`guides/deploy-and-state.md`](guides/deploy-and-state.md),\n  [`guides/typed-config.md`](guides/typed-config.md).\n- **Level 2.5** — Recipes: [`recipes/*.md`](recipes/) — step-by-step playbooks to\n  follow as your execution plan.\n- **References** — [`references/resources.md`](references/resources.md) (the full\n  builder catalog), [`references/commands.md`](references/commands.md) (every\n  `cargo-ai cdk` subcommand + flags),\n  [`references/troubleshooting.md`](references/troubleshooting.md), and\n  [`references/examples/full-workspace.md`](references/examples/full-workspace.md).\n\n## 5) Read behavior — match the task to a doc and READ IT\n\n| When the task involves… | Read this first | What it gives you |\n|---|---|---|\n| Writing `define*` files, wiring resources, `secret()`/`env()`, `defineWorkflow` bodies (tool/play logic) | [`guides/authoring-resources.md`](guides/authoring-resources.md) | The builder catalog, the handle/ref model, secrets, and how workflow bodies compile. |\n| `plan` / `deploy` / `destroy`, the state file, drift, adopting existing resources, CI | [`guides/deploy-and-state.md`](guides/deploy-and-state.md) | The deploy lifecycle, `cargo.state.json` semantics, drift/import/rollback, async builds. |\n| Typed config, `cargo-ai cdk types`, tsconfig wiring, `integrations.*` in workflow bodies | [`guides/typed-config.md`](guides/typed-config.md) | What `cdk types` generates and how to wire it into your project. |\n| A field/spec/output for a specific builder | [`references/resources.md`](references/resources.md) | Every builder → spec fields → which ref each takes → outputs. |\n| Exact command flags | [`references/commands.md`](references/commands.md) | Every `cargo-ai cdk` subcommand and its flags. |\n| A deploy error / footgun | [`references/troubleshooting.md`](references/troubleshooting.md) | The known failure modes and fixes. |\n| A known GTM outcome, before authoring one | [`references/cookbooks.md`](references/cookbooks.md) | The cookbook menu: gtm-skills that carry a worked CDK example, and the adaptations each supports. |\n\n### Cookbooks — check the menu before authoring a known outcome from scratch\n\n[`getcargohq/gtm-skills`](https://github.com/getcargohq/gtm-skills) holds, beside its\none-off skills, **cookbooks**: skills that carry worked CDK resources, the same job as a deployed\npipeline that keeps producing the result (TAM building, account scoring, contact\nsourcing, routing engine, AI SDR, rep cockpit, …). Every folder is self-contained: its\nown models, connectors and folders, no shared foundation, no requires graph.\n\n**The menu is local: [`references/cookbooks.md`](references/cookbooks.md).** Read it\nbefore authoring a common GTM outcome from scratch. It is generated from gtm-skills'\n`catalog.json`, so it cannot drift.\n\n**A cookbook is a worked example, not a template to fill in.** Each one declares in its `SKILL.md` what may be reshaped, what must hold or it stops\nworking, and what has to be answered either way, and it carries its own procedure:\nlook at the repo, `cargo-ai cdk init --template blank` if there is no CDK project yet,\ncopy the folder in as a sibling and reconcile it with what is already declared, adapt,\nplan and stop, deploy on a yes, walk its `Done when`. There is no scaffolder or copy\ntool in the middle: **you place the code**, because you can see the project and a tool\ncannot.\n\n```sh\nnpx skills add getcargohq/gtm-skills/tam-building    # then: \"keep our TAM current\"\ncargo-ai cdk init my-project --template blank        # only if there is no CDK project yet\n```\n\n**If you are mid-task and the skill is not in this session**, run the `skills add`\nabove and read `.agents/skills/<slug>/SKILL.md` directly; no reload needed. To read\none without installing, `npx skills use getcargohq/gtm-skills@<slug>` prints it.\n\n**Routing rule: one-off versus standing.** A user who wants the list today wants\n`cargo-gtm` (or gtm-skills' one-off `build-tam-list`); a user who wants a pipeline\nthat keeps producing it wants `tam-building`. The same words describe both (\"build\nour TAM\"), so listen for whether the result is meant to keep arriving. A cookbook\nmatches → install it and follow it. No match → author from the recipes below.\n\n**Never `cargo-ai cdk init --force` into a directory that is not empty.** It replaces\nthe project's `package.json` and reverts adapted code, while `cargo.state.json`\nsurvives, so the next `plan` diffs a live workspace against code nobody wrote. Copy the\nskill folder in as a sibling instead.\n\nCaveat: the examples typecheck, but they are not yet deploy-verified against a live\nworkspace, and every one is `to-be-approved`. Treat each skill's `Done when` as the\nacceptance test, and always review `cargo-ai cdk plan` before deploying.\n\n### Recipes — follow step-by-step when one matches\n\n| Recipe | Use when… |\n|---|---|\n| [`recipes/scaffold-a-workspace.md`](recipes/scaffold-a-workspace.md) | Standing up a new workspace from scratch (`init --template full` → types → plan → deploy). |\n| [`recipes/add-connector-and-model.md`](recipes/add-connector-and-model.md) | Adding a data source + a model sourced from it, wired by handle. |\n| [`recipes/build-an-agent.md`](recipes/build-an-agent.md) | Composing a model + tool + agent (with `uses` / `models` / `tools`) and deploying. |\n| [`recipes/migrate-existing-workspace.md`](recipes/migrate-existing-workspace.md) | Bringing an already-live workspace under CDK management via `cdk import`. |\n| [`recipes/deploy-from-ci.md`](recipes/deploy-from-ci.md) | Deploying non-interactively from CI (token auth + committed state). |\n\n## 6) Critical rules\n\n## Help\n\n- `cargo-ai cdk --help` and `cargo-ai cdk <subcommand> --help` for the live flag\n  surface.\n- When a documented command/flag/response doesn't match what you observe, file a\n  report: `cargo-ai workspaceManagement report create` (see\n  [`../cargo-workspace-management/SKILL.md`](../cargo-workspace-management/SKILL.md)).\n"
}