pulumi-esc
Skill19 starsChanged 8 months agoMITView on GitHub
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.
In this repository53 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/skills/agent-rules/AGENTS.mdAGENTS.md
- .github/workflows/AGENTS.mdAGENTS.md
- pkg/AGENTS.mdAGENTS.md
- agent-ready-goSkill
- agent-rulesSkill
- architecture-designerSkill
- cli-developerSkill
- cloudformation-to-pulumiSkill
- code-reviewerSkill
- commitlintSkill
- commitSkill
- csharp-developerSkill
- decideSkill
- dep-upgradeSkill
- design-principlesSkill
- devops-engineerSkill
- flux-cliSkill
- flux-operator-cliSkill
- golang-proSkill
- go-nolint-auditSkill
- javascript-proSkill
- kubernetes-specialistSkill
- lint-fixSkill
- markdownlintSkill
- prSkill
- pull-request-msg-with-ghSkill
- pulumi-arm-to-pulumiSkill
- pulumi-automation-apiSkill
- pulumi-best-practicesSkill
- pulumi-cdk-to-pulumiSkill
- pulumi-cliSkill
- pulumi-componentSkill
- pulumi-goSkill
- pulumi-neoSkill
- pulumi-pythonSkill
- pulumi-terraform-to-pulumiSkill
- pulumi-typescriptSkill
- python-proSkill
- reviewSkill
- roadmapSkill
- rust-async-patternsSkill
- rust-best-practicesSkill
- rust-engineerSkill
- scoutSkill
- security-auditSkill
- spring-boot-engineerSkill
- sre-engineerSkill
- sync-websiteSkill
- tailscale-installSkill
- tech-debtSkill
- the-foolSkill
- typescript-proSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
22 rules. About 0 are common, 8 are distinctive, and 14 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Version and audit: all configuration changes
- Very specific: line 54
pulumi config env add: Only takes the <project-name>/<environment-name> portion - Very specific: line 60
imports: Import and compose other environments - Distinctive: line 95
If the user asks basic questions like "How do I create an environment?" or "What's the difference between get and open?", answer directly …
- Distinctive: line 99
When users need more information, use the web-fetch tool to get content from the official Pulumi ESC documentation:
- Very specific: line 110
Prefer using the pulumi env subcommands over esc CLI.
- Distinctive: line 112
Use the web-fetch tool with specific prompts to extract relevant information from these docs.
- Very specific: line 119
Check existing setup: Use pulumi env commands to list environments or read definitions
- Distinctive: line 120
Fetch relevant documentation: Use the web-fetch to get specific examples or syntax from the official docs
- Distinctive: line 156
Always prefer CLI commands: Only use the API when absolutely necessary (e.g., bulk operations, automation).
- Very specific: line 164
Use call_pulumi_cloud_api() tool to make requests when needed.
- Very specific: line 168
Always use fn::secret for sensitive values
- Distinctive: line 169
Prefer OIDC over static keys
- Very specific: line 170
Use descriptive names like <org>/my-app/production-aws not <org>/app/prod
- Very specific: line 172
Verify that pulumi config shows expected values after linking an environment to a stack
- Very specific: line 173
Prefer using pulumi env run for commands needing environment variables
- Very specific: line 174
Only use pulumi env open when absolutely necessary, as it reveals secrets
- Very specific: line 178
"Environment not found": Check permissions with pulumi env ls -o <org>
- Very specific: line 179
"Secret decryption failed": Use pulumi env open not pulumi env get
- Very specific: line 180
"Stack can't read values": Verify pulumi config env ls to ensure the stack is listed.
- Distinctive: line 181
Ensure the environment is referenced only by the project-name/environment-name format.
- Very specific: line 183
Verify the pulumiConfig key exists and is nested under the values key.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Pulumi ESC (Environments, Secrets, and Configuration)
Pulumi ESC is a centralized service for managing environments, secrets, and configuration across cloud infrastructure and applications.
What is ESC?
ESC enables teams to:
- Centralize secrets and configuration in one secure location
- Compose environments by importing and layering configuration
- Generate dynamic credentials via OIDC for AWS, Azure, GCP
- Integrate external secret stores (AWS Secrets Manager, Azure Key Vault, Vault, 1Password)
- Version and audit all configuration changes
- Control access with fine-grained RBAC
Essential CLI Commands
# Create a new environment
pulumi env init <org>/<project-name>/<environment-name>
# Edit environment (opens in editor)
pulumi env edit <org>/<project-name>/<environment-name>
# Set values
pulumi env set <org>/<project-name>/<environment-name> <key> <value>
pulumi env set <org>/<project-name>/<environment-name> <key> <value> --secret
# View definition (secrets hidden)
pulumi env get <org>/<project-name>/<environment-name>
# Open and resolve (reveals secrets)
pulumi env open <org>/<project-name>/<environment-name>
# Run command with environment
pulumi env run <org>/<project-name>/<environment-name> -- <command>
# Link to Pulumi stack
pulumi config env add <project-name>/<environment-name>Key Concepts
Command Distinctions
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<project-name>/<environment-name>portion
Environment Structure
Environments are YAML documents with reserved top-level keys:
imports: Import and compose other environmentsvalues: Define configuration and secrets
Reserved sub-keys under values:
environmentVariables: Map values to shell environment variablespulumiConfig: Configure Pulumi stack settingsfiles: Generate files with environment data
Basic Example
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}Working with the User
For Simple Questions
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.
For Detailed Documentation
When users need more information, use the web-fetch tool to get content from the official Pulumi ESC documentation:
- Complete YAML syntax and functions → https://www.pulumi.com/docs/esc/environments/syntax/
- Provider integrations (AWS, Azure, GCP, Vault, 1Password):
- AWS: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/aws-login/
- Azure: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/azure-login/
- GCP: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/gcp-login/
- Short-term credential (OIDC) providers: https://www.pulumi.com/docs/esc/integrations/dynamic-login-credentials/
- Dynamic secret providers: https://www.pulumi.com/docs/esc/integrations/dynamic-secrets/
- Getting started guide → https://www.pulumi.com/docs/esc/get-started/
- CLI reference → https://www.pulumi.com/docs/esc/cli/commands/
- Prefer using the
pulumi envsubcommands overescCLI.
- Prefer using the
Use the web-fetch tool with specific prompts to extract relevant information from these docs.
For Complex Tasks
When helping users:
- Understand the goal: Are they setting up new environments, migrating from stack config, or debugging?
- Check existing setup: Use
pulumi envcommands to list environments or read definitions - Fetch relevant documentation: Use the web-fetch to get specific examples or syntax from the official docs
- Provide step-by-step guidance: Walk through the process with specific commands
- Validate: Help them test with
pulumi env getorpulumi previewa. Only usepulumi env openwhen the full resolved values are needed, but use cautiously as it reveals secrets.
Example: Helping with AWS OIDC Setup
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 necessaryCommon Workflows
Creating an Environment
pulumi 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-configLinking to Stack
pulumi config env add my-project/dev-config
pulumi config # Verify environment values are accessibleAPI Access (Rare)
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 providers
Use call_pulumi_cloud_api() tool to make requests when needed.
Best Practices
- Always use
fn::secretfor sensitive values - Prefer OIDC over static keys
- Use descriptive names like
<org>/my-app/production-awsnot<org>/app/prod - Layer environments: base → cloud-provider → stack-specific
- Verify that
pulumi configshows expected values after linking an environment to a stack - Prefer using
pulumi env runfor commands needing environment variables - Only use
pulumi env openwhen absolutely necessary, as it reveals secrets
Quick Troubleshooting
- "Environment not found": Check permissions with
pulumi env ls -o <org> - "Secret decryption failed": Use
pulumi env opennotpulumi env get - "Stack can't read values": Verify
pulumi config env lsto ensure the stack is listed.- Ensure the environment is referenced only by the project-name/environment-name format.
- Get the specific environment definition with
pulumi env get <org>/<project-name>/<environment-name>. - Verify the
pulumiConfigkey exists and is nested under thevalueskey.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

