Skip to main content
skill CX Codex

pulumi-context-api — Claude Code skill: what it does, how to install

Queries the Pulumi Context API to inspect cloud infrastructure graphs, trace cross-stack dependencies, and evaluate blast radius before updates.

Apache-2.0 211 installs ★ 80 updated 2026-10-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pulumi/agent-skills --skill pulumi-context-api -a claude-code
Open on GitHub

What pulumi-context-api does

This skill directs the agent to query infrastructure as a graph in Pulumi Cloud. It reveals dependencies across components. The agent measures blast radius before changes and discovers unreferenced resources. Discovered cloud assets outside direct Pulumi management are also included.

The workflow first checks whether the session already exposes graph_query and get_graph_schema. If those tools are missing, the agent runs pulumi api GetGraphQuerySchema --output=markdown to pull the contract fresh from the server. It then writes a JSON selector and posts pulumi api GraphQuery -F orgName=<org> --input selector.json. Before returning findings, the agent inspects meta.resultMode, meta.visibility, and pageInfo.continuationToken to guarantee complete traversal.

Queries fail immediately without Pulumi CLI v3.243.0 or newer, an active pulumi login, and an Enterprise or Business Critical organization subscription. The graph schema intentionally omits full property payloads. When you need deep property inspection or failure logs, use Resource Search or pulumi-debug-failed-operation instead.

What it helps with

  • Trace cross-stack and cross-account infrastructure dependencies
  • Evaluate change blast radius before modifying shared resources
  • Spot orphaned or unreferenced cloud resources across the organization
  • Determine which provider versions manage specific cloud resources

Example prompts for the agent

  • Use Pulumi Context API to inspect the blast radius if I delete the networking stack in my-org.
  • Run a graph query to find all orphaned resources and cross-stack dependencies for the database.

How to install pulumi-context-api

1Skills CLI (Vercel)

npx skills add pulumi/agent-skills --skill pulumi-context-api -a claude-code

2Manually: put the files in place

~/.claude/skills/pulumi-context-api/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pulumi-context-api/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pulumi-context-api

How do I install pulumi-context-api in Claude Code?

Run npx skills add pulumi/agent-skills --skill pulumi-context-api -a claude-code. This installs the skill definition into ~/.claude/skills/pulumi-context-api/SKILL.md.

How does Context API differ from Pulumi Resource Search?

Resource Search locates individual resources by name or attributes but cannot traverse graph edges. Context API tracks relationships across stacks and maps blast radius across accounts.

What prerequisites are required to run queries with this skill?

You need Pulumi CLI v3.243.0 or newer, an active pulumi login, and a Pulumi Cloud organization on Enterprise or Business Critical tiers. The user role must grant resources:search permissions.

Source text

SKILL.md · Apache-2.0
---
name: pulumi-context-api
description: |
    Query the Pulumi Context API, a graph query interface over an
    organization's infrastructure in Pulumi Cloud. Use when a question is
    about relationships or reachability across resources and stacks: the
    impact of a change ("what breaks if I change this?", blast radius), what
    depends on a resource or a stack's outputs, which provider instances
    manage which resources and at what versions, orphaned or unreferenced
    resources, or references that cross stacks and cloud accounts, including
    resources Pulumi doesn't manage. Don't load it for finding a single
    resource by name, type, or property (Resource Search covers that), or for
    update history and failure debugging (use skill
    `pulumi-debug-failed-operation`).
---

# Query the Pulumi Context API

The Context API answers questions about an organization's cloud infrastructure
as a graph: what exists, what depends on what, what a change would affect. It
covers resources found through Pulumi Discovery, not just Pulumi-managed ones.

Prefer it over Resource Search whenever the question involves relationships.
Resource Search finds individual resources but cannot follow edges, so
answering "what depends on X" with repeated searches is slow and usually
incomplete.

Public preview, for organizations on the Enterprise and Business Critical
editions, and a role granting `resources:search` (the default Member and Admin
roles do).

## First: is a graph tool already in the session?

If one is — `graph_query` and `get_graph_schema`, under whatever prefix the
server registers them — call it and skip Steps 1 and 2. Compose the selector
from the `graph_query` tool's own description, which carries the grammar; the
tool resolves the organization and credentials itself and drains pagination for
you. When that description is not enough, `get_graph_schema` returns the live
field vocabulary and limits, and will serve the full Step 1 primer when asked
for it. Step 3 still governs what you do with the result.

Steps 1 and 2 are the path for an agent that has a shell and no such tool.

## Step 1: fetch the primer, always

Needs Pulumi CLI v3.243.0 or newer and an active `pulumi login`.

```bash
pulumi api GetGraphQuerySchema --output=markdown
```

This returns a self-contained guide to composing selectors — vocabulary, edge
types, engine caps, worked examples, pagination, completeness rules, the gates
that deny a query, and the traps that produce a confident wrong answer instead
of an error. It is served by the deployment that answers your queries, so it is
the contract, and it moves between schema versions. This skill bootstraps you
to it and stops there; everything below defers to it. Fetch it fresh in every
session — a primer remembered from earlier may describe a schema this
deployment no longer serves.

The operation takes no organization; one schema covers every org the login can
reach. `--output=json` on it returns the same contract as a machine-readable
payload, useful for reading `limits` or `fieldValues` programmatically, but
compose from the markdown.

**Read it in full — never truncate it with `head`, `tail`, or a byte cap.** A
clipped primer means malformed selectors and rejected queries.

### If this call fails

You have no primer yet, so handle it here rather than looking it up there:

| Response | Meaning |
|---|---|
| `401 Unauthorized` | no active `pulumi login`, or an expired token |
| `404 Not Found`, detail-free | a wrong path, or a deployment without the endpoint |
| `503 Service Unavailable` | transient — retry |

Entitlement gates are per-organization, so they cannot appear on this call —
they surface in Step 2, by which point the primer's "When it denies you" table
is in hand. If `pulumi api` doesn't know `GetGraphQuerySchema` at all, that is
not a gate: run `pulumi api list --refresh-spec` to refresh the cached spec,
then retry the fetch.

## Step 2: query

```bash
pulumi api GraphQuery -F orgName=<org> --input selector.json
```

The body is a JSON selector, not query text. Compose it from the primer you
just read, not from memory or from a grammar you recall from another session.

Name the org explicitly. Left off, `-F orgName` resolves from the selected
stack or the default org, which is often an individual account with no
entitlement; `pulumi whoami -v` lists every organization the login can reach.
A denial here names its gate — the primer's "When it denies you" table says
which are worth retrying and which to report to the user.

## Step 3: apply the primer's completeness rules before answering

Every response carries fidelity signals — currently `meta.resultMode`,
`meta.visibility`, and `pageInfo.continuationToken`; the primer names the
authoritative set. Read the primer's rules for them and follow them; the
remedies differ per signal and a stale paraphrase here would be worse than
none.

What matters most: **a completeness claim needs all of them clean.** Impact
analysis, "nothing depends on this", an exhaustive cleanup list, a total across
groups — none of these survive a truncated result, a trimmed traversal, or an
undrained page. When you can't get there, say what the answer does cover.

## Scope of the graph

Resources, stacks, and the relationships between them, trimmed to the stacks
and accounts the caller can see. The primer's "What it cannot answer yet"
section is the live boundary — check it before concluding a question is
unanswerable, and reach for a different API rather than approximating one of
those gaps with a graph query.

One boundary worth knowing up front, because it decides which API to use: the
graph returns a schema-declared subset of fields per node type, not full
resource property bags. The primer lists which fields each node type can match
on and which it can return; when the question needs the property values
themselves, they come back from Resource Search.

Human-readable reference:
[Context API overview](https://www.pulumi.com/docs/insights/context-api/) and
[query guide](https://www.pulumi.com/docs/insights/guides/context-api/).

© pulumi · Apache-2.0 · pulumi/agent-skills

Similar skills

All skills for DevOps and infrastructure →

From the same set17

The whole set →
provider-upgrade provider-upgrade walks an agent through bumping a Pulumi provider version and reconciling preview diffs so nothing gets recreated in the cloud. CX Codex +1 898installs package-usage package-usage scans Pulumi organization stacks to report which projects run a given package and flag versions that lag behind the latest release. CX Codex +1 875installs pulumi-upgrade-provider pulumi-upgrade-provider drives upgrade-provider --no-submit through a Pulumi provider repo, fixes the usual failures and stops at a local result for review. CX Codex +1 717installs upstream-patches upstream-patches manages Terraform provider submodule patches using ./scripts/upstream.sh. Useful for provider upgrades, resolving patch conflicts, and rebasing. CX Codex +1 655installs pulumi-overview pulumi-overview directs AI coding agents through cloud infrastructure tasks with Pulumi, ranging from single CLI commands to multi-resource stacks. CX Codex +1 626installs pulumi-neo-handoff pulumi-neo-handoff turns the current thread into one opening prompt for a new Pulumi Neo task. The handoff is one-way: control goes to Neo and does not come back. CX Codex +1 463installs pulumi-debug-failed-operation pulumi-debug-failed-operation reads the record of a failed pulumi up or pulumi preview, finds the cause, and points to where the fix belongs. CX Codex +1 405installs pulumi-migrate-from-discovered-stack pulumi-migrate-from-discovered-stack — a skill that imports CloudFormation or ARM stacks already discovered by Pulumi Cloud's Discovery feature into Pulumi. Works only with stacks already scanned and visible in the discovered-stacks API. CX Codex +1 219installs

Project sponsors

Companies that keep this analytics open