npx skills add ...
npx skills add pulumi/agent-skills --skill pulumi-esc
npx skills add pulumi/agent-skills --skill pulumi-esc
Guidance for working with Pulumi ESC (Environments, Secrets, and Configuration). Use when users ask about managing secrets, configuration, environments, short-term credentials, configuring OIDC for AWS, Azure, GCP, integrating with secret stores (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, 1Password), or using ESC with Pulumi stacks.
Pulumi ESC is a centralized service for managing environments, secrets, and configuration across cloud infrastructure and applications.
ESC enables teams to:
pulumi env get: Shows static definition, secrets appear as [secret]pulumi env open: Resolves and reveals all values including secrets and dynamic credentialspulumi env run: Executes commands with environment variables loadedpulumi config env add: Only takes the / portionEnvironments are YAML documents with reserved top-level keys:
imports: Import and compose other environmentsvalues: Define configuration and secretsReserved sub-keys under values:
environmentVariables: Map values to shell environment variablespulumiConfig: Configure Pulumi stack settingsfiles: Generate files with environment dataUse the fn::open::pulumi-stacks provider to consume another stack's outputs. The
stacks and network keys below are arbitrary names you choose. Once the function
resolves, it replaces stacks.network with the named stack's outputs — so the
output names (vpcId, subnetIds) do not appear in the static YAML; they come from
whatever the producer stack exports. Two things are easy to get wrong:
stack: <project>/<stackName>
field — not separate projectName/stackName fields..outputs. level
(use ${stacks.network.vpcId}, not ${stacks.network.outputs.vpcId}).Example — replace the stack name and output names with your own:
Full schema: https://www.pulumi.com/docs/esc/providers/pulumi-stacks/
The console URL for an environment is
https://app.pulumi.com/<org>/esc/<project>/<environment>. The route segment is
esc, not environments.
If the user asks basic questions like "How do I create an environment?" or "What's the difference between get and open?", answer directly using the information above.
When users need more information, use the web-fetch tool to get content from the official Pulumi ESC documentation:
fn::open::pulumi-stacks): https://www.pulumi.com/docs/esc/providers/pulumi-stacks/pulumi env subcommands over esc CLI.Use the web-fetch tool with specific prompts to extract relevant information from these docs.
When helping users:
pulumi env commands to list environments or read definitionspulumi env get or pulumi preview
a. Only use pulumi env open when the full resolved values are needed, but use cautiously as it reveals secrets.Always prefer CLI commands. Only use the API when absolutely necessary (e.g., bulk operations, automation).
Available API endpoints include:
GET /api/esc/environments/{orgName} - List environmentsGET /api/esc/environments/{orgName}/{projectName}/{envName} - Read environment definitionGET /api/esc/providers?orgName={orgName} - List available providersUse call_pulumi_cloud_api() tool to make requests when needed.
fn::secret for sensitive values<org>/my-app/production-aws not <org>/app/prodpulumi config shows expected values after linking an environment to a stackpulumi env run for commands needing environment variablespulumi env open when absolutely necessary, as it reveals secretspulumi config env add) without explicit user confirmation, and never pass --yes.Start with the remediation in the error message. An expired or missing login usually just needs the user to re-authenticate, and most providers name the fix or the command:
Failed to refresh cached SSO credentials. Please refresh SSO login.
→ aws sso loginExpiredToken: The security token included in the request is expired → refresh the session or keysaz logingcloud auth application-default loginpulumi loginRelay the fix and have the user retry. If the error does not name a remediation
(for example a bare Unable to locate credentials, or an access-denied that may
mean the wrong account or profile rather than an expired login), don't guess —
identify how the project authenticates (provider config, the active profile, any
linked ESC environment) and address that.
Changing where the project gets its credentials (adding or switching an ESC environment, editing provider config) is a deliberate change, not a reflexive fix for an expired session. Do it only if the user wants it, and follow the rules below.
Do not pick an environment because its name looks relevant (*-aws-oidc,
*-creds, *-workshop, etc.). A matching name does not mean it is the right
one or that it belongs to this user's work.
Before proposing any existing environment:
pulumi env get <org>/<project>/<env>.roleArn names a specific AWS account — if it points
at a different account (a shared workshop, an instructor role, another team),
it is the wrong environment and will run operations against the wrong account
or fail.pulumi config env add edits the stack config (Pulumi.<stack>.yaml) and
changes the credentials Pulumi operations run under. Never run it without
explicit user confirmation, and never pass --yes to skip that confirmation.
Tell the user what will change and let them decide.
After linking, resolved credential values often show as [unknown] until the
environment is opened or run. Do not claim the error is fixed or that the next
operation will succeed until you have verified it — check pulumi config, and
confirm the credentials resolve to the expected account before declaring success.
pulumi env ls -o <org>pulumi env open not pulumi env getpulumi config env ls to ensure the stack is listed.
pulumi env get <org>/<project-name>/<environment-name>.pulumiConfig key exists and is nested under the values key.*imports:
- common/base-config
values:
environment: production
region: us-west-2
dbPassword:
fn::secret: super-secure-password
environmentVariables:
AWS_REGION: ${region}
DB_PASSWORD: ${dbPassword}
pulumiConfig:
aws:region: ${region}
app:dbPassword: ${dbPassword}values:
stacks:
fn::open::pulumi-stacks:
stacks:
network: # arbitrary local name for the referenced stack
stack: my-project/dev # producer stack to read outputs from
pulumiConfig:
# vpcId / subnetIds are whatever the producer stack exports; after the function
# resolves they are available directly under `stacks.network` (no `.outputs.`).
vpcId: ${stacks.network.vpcId}
subnetIds: ${stacks.network.subnetIds}User: "How do I set up AWS OIDC credentials in ESC?"
1. Use the web-fetch tool to get AWS OIDC documentation from "https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/"
2. Provide the user with the configuration
3. Ask the user if they have a pre-defined role or need one created for them
4. Set up as much of the environment as possible, then guide them through any steps that you can't do for them
5. Help them test with `pulumi env get` or `pulumi env open` if necessarypulumi env init my-org/my-project/dev-config
# Edit environment (accepts new definition from a file, better for agents, more difficult for users)
pulumi env edit --file /tmp/example.yml my-org/my-project/dev-configpulumi config env add my-project/dev-config
pulumi config # Verify environment values are accessible