From spacelift
Use when working with Spacelift - managing stacks, runs, modules, policies, spaces, contexts, worker pools, blueprints, VCS/cloud integrations, role bindings, audit trail, scheduled runs/tasks; or managing actual infrastructure via intent (create/update/delete/refresh/import resources, intent projects). Wraps the spacelift-local MCP (discover/query/mutate/provider/intent tools). Trigger on terms - spacelift, stack, run, intent, IaC platform, GraphQL Spacelift API, infrastructure resource lifecycle, deploy, provision, tear down, OpenTofu, Terraform managed by Spacelift, Terragrunt, Pulumi.
How this skill is triggered — by the user, by Claude, or both
Slash command
/spacelift:spaceliftThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Procedural guide for the spacelift MCP. Two surfaces share one MCP - the Spacelift control plane (GraphQL: stacks, runs, policies, spaces, integrations) and Intent (lifecycle of actual cloud resources via OpenTofu providers). Most tasks touch both.
examples/01-read-only-audit.mdexamples/02-stack-run-lifecycle.mdexamples/03-intent-end-to-end.mdreferences/api-discovery.mdreferences/integrations.mdreferences/intent-operations.mdreferences/intent-projects.mdreferences/mutations-safety.mdreferences/policies-spaces.mdreferences/runs.mdreferences/stacks.mdProcedural guide for the spacelift MCP. Two surfaces share one MCP - the Spacelift control plane (GraphQL: stacks, runs, policies, spaces, integrations) and Intent (lifecycle of actual cloud resources via OpenTofu providers). Most tasks touch both.
| Tool | Purpose |
|---|---|
discover | Browse the GraphQL schema. Modes: queries, mutations, type. Always run before query/mutate. |
query | Execute a read-only GraphQL operation. select uses GraphQL selection-set syntax. |
mutate | Execute a GraphQL mutation. Modifies state - requires explicit confirmation (see below). |
provider | Inspect OpenTofu providers + resource schemas. Modes: search, describe, resources-describe, datasources-describe. Mandatory before intent create/update/import. |
intent | Manage real infrastructure: create, update, delete, refresh, import, read, resume, status. Supports async=true. |
| User wants to... | Start with |
|---|---|
| Read/list/inspect Spacelift entities (stacks, runs, policies, ...) | discover → query |
| Modify a Spacelift entity (create/update/delete/attach) | discover → mutate (gated, see below) |
| Create/update real cloud infra (EC2, S3, GCS, ...) | provider → intent (gated, see below) |
| Import existing cloud infra into intent state | provider search → intent import |
| Detect drift on managed cloud infra | intent refresh |
| Trigger / confirm / discard a stack run | mutate with runTrigger / runConfirm / runDiscard |
Load only the file that matches the question. Do not preload references.
| Question / task | Load |
|---|---|
| GraphQL syntax, pagination, search predicates, selection sets | references/api-discovery.md |
| Stack lifecycle, settings, dependencies, drift, scheduling, blueprints | references/stacks.md |
| Run state machine, plan/confirm/discard/apply, retry, cancel, tasks | references/runs.md |
| Policy types (10 of them), role bindings, spaces, attachment rules | references/policies-spaces.md |
| AWS/Azure/GCP integrations, VCS providers, contexts, worker pools | references/integrations.md |
| Creating an intent project, configElements, attaching policies/AWS/worker pool, exporting to IaC | references/intent-projects.md |
intent operation mechanics: provider workflow, async polling, resume gating | references/intent-operations.md |
| About to mutate or delete? Read this every time | references/mutations-safety.md |
End-to-end recipes: examples/01-read-only-audit.md, examples/02-stack-run-lifecycle.md, examples/03-intent-end-to-end.md.
discover before query/mutate. Don't guess operation names or argument shapes.provider resources-describe before intent create/update/import. Skipping causes "expected X arguments" errors. Provider schemas drift; do not cache across sessions.references/mutations-safety.md before any mutate or intent delete/update.Before any mutate, intent create, intent update, or intent delete:
intent delete: enumerate dependents first (use searchIntentResources or provider resources-describe linkage).YES or CONFIRM (case-insensitive). No other token confirms. No carryover from prior turns - each destructive call needs a fresh confirmation.Read-only operations (query, discover, provider search/describe, intent read/status/refresh) need no confirmation.
Some intent operations take 10-30 minutes. Use async=true, then poll with intent status:
status returns PENDING_REVIEW, do not call resume. Wait for READY_FOR_EXECUTION, then resume after explicit human approval.Each is real and frequent. Apply the mitigation by default.
| Pitfall | Mitigation |
|---|---|
| User asks "how many X do I have?" - listing every entity is slow and pollutes context | Use searchXxxSuggestions with predicates and select filteredCount - returns the count without entities |
| Deleted context still attached to stacks - runs fail with missing env var | Before contextDelete, list attachedStacks; either detach or warn |
| Worker pool deleted while runs queued - orphaned runs | Drain workers (workerDrainSet), wait for queue to clear, then delete |
stackDelete(destroyResources: true) runs a destroy plan - destroys real infra | Treat as the most destructive operation; require CONFIRM and enumerate dependents |
variables passed as JSON-encoded string ("{\"id\":\"x\"}") | Pass as a JSON object: {"id": "x"} |
Calling runConfirm on a run not in UNCONFIRMED | Read state first; only UNCONFIRMED accepts confirm |
intent resume on PENDING_REVIEW | Only resume when status is READY_FOR_EXECUTION |
| Stale provider schema → "expected X arguments" | Run provider resources-describe before each intent create/update |
| Async over-polling burns tokens / triggers rate limits | Exponential backoff capped at 60s; never re-dispatch |
Selection-set bloat (name description createdAt updatedAt ...) | Request only fields you'll use this turn |
| Pagination forgotten - missing entries on accounts with >50 entities | Use first/after with pageInfo.hasNextPage; loop until exhausted or stop early |
Mutations are not idempotent (slug collisions on stackCreate) | query for existence first; handle 409-shaped errors as "already exists" |
Deprecated fields silently hidden by discover | Pass includeDeprecated: true only when truly needed |
| Tracked commit drifts behind remote silently | stackSyncCommit to refresh; do not assume trackedCommit is current |
Treating IntentProject as separate from Spacelift entities | It has space, workerPool, attachedPolicies like a stack - use the same auth/policy mental model |
When concepts go beyond what's here (vendor-specific behaviors, billing edge cases, integration-test setups, custom blueprint authoring), consult https://docs.spacelift.io/sitemap.xml to find the relevant page, then WebFetch.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub spacelift-io/claude-plugins --plugin spacelift