pulumi-neo
Pulumi Neo AI-powered infrastructure automation agent. Use when working with Pulumi Neo for conversational infrastructure management, creating Neo tasks, monitoring task progress, infrastructure analysis, maintenance operations, or automating multi-step cloud workflows through natural language.
When & Why to Use This Skill
Pulumi Neo is an AI-powered infrastructure automation agent designed for platform engineers to manage cloud environments through natural language. It simplifies complex DevOps workflows by enabling conversational infrastructure management, automated analysis, and multi-step cloud operations. By integrating directly with Pulumi Cloud, it allows users to create tasks, monitor progress, and maintain infrastructure as code (IaC) with high efficiency and reduced manual overhead.
Use Cases
- Infrastructure Analysis: Automatically scan production stacks for security vulnerabilities, cost optimization opportunities, and architectural improvements using natural language queries.
- Automated Maintenance Operations: Execute complex cloud updates, such as upgrading Kubernetes clusters or modifying Lambda function configurations, through simple conversational commands.
- Policy Compliance & Remediation: Identify and fix governance policy violations within Pulumi stacks to ensure infrastructure remains compliant with organizational standards.
- AI-Driven Code Generation: Generate complete Pulumi TypeScript projects or infrastructure components from scratch based on high-level requirements.
- Intelligent Pull Request Reviews: Analyze infrastructure changes within PRs to provide automated feedback on impact, security, and best practices before deployment.
- Multi-step Workflow Automation: Orchestrate end-to-end CI/CD pipelines and cloud deployment sequences by describing the desired outcome to the AI agent.
| name | pulumi-neo |
|---|---|
| description | Pulumi Neo AI-powered infrastructure automation agent. Use when working with Pulumi Neo for conversational infrastructure management, creating Neo tasks, monitoring task progress, infrastructure analysis, maintenance operations, or automating multi-step cloud workflows through natural language. |
Pulumi Neo Skill
Pulumi Neo is an AI agent for platform engineers that enables conversational infrastructure management through natural language.
Prerequisites
- Pulumi Cloud account with Neo access
- PULUMI_ACCESS_TOKEN environment variable set with your Personal Access Token
- Organization: Required for all Neo API calls
Detecting Organization
# Get current Pulumi organization from CLI
pulumi org get-default
# If no default org or using self-managed backend, ask user for organization name
If pulumi org get-default returns an error or shows a non-cloud backend, prompt the user for their Pulumi Cloud organization name.
Claude Code Integration
RECOMMENDED: Use MCP tools directly - they work natively with Claude Code:
mcp__pulumi__neo-bridge # Create and interact with Neo tasks
mcp__pulumi__neo-get-tasks # List existing tasks
mcp__pulumi__neo-continue-task # Continue polling a task
If using the Python script, ALWAYS add --no-poll:
# REQUIRED: --no-poll prevents blocking (script will hang without it)
python scripts/neo_task.py --org <org> --message "Your message" --no-poll
# Check events separately
python scripts/neo_task.py --org <org> --task-id <task-id> --get-events
WARNING: Never run the script without --no-poll in Claude Code - the polling loop will block indefinitely.
Using the Python Script
The script handles Neo task creation, polling, and management:
# Create a task and poll for updates (interactive/terminal use)
python scripts/neo_task.py --org <org-name> --message "Help me optimize my Pulumi stack"
# Create task without polling (CI/CD or programmatic use)
python scripts/neo_task.py --org <org-name> --message "Analyze this" --no-poll
# Create task with stack context
python scripts/neo_task.py --org <org-name> \
--message "Analyze this stack" \
--stack-name prod --stack-project my-infra --no-poll
# Create task with repository context
python scripts/neo_task.py --org <org-name> \
--message "Review this infrastructure code" \
--repo-name my-repo --repo-org my-github-org --no-poll
# List existing tasks
python scripts/neo_task.py --org <org-name> --list
# Fetch current events (single request, no polling)
python scripts/neo_task.py --org <org-name> --task-id <task-id> --get-events
# Poll an existing task for updates (interactive)
python scripts/neo_task.py --org <org-name> --task-id <task-id>
# Send approval for a pending request
python scripts/neo_task.py --org <org-name> --task-id <task-id> --approve
# Cancel a pending request
python scripts/neo_task.py --org <org-name> --task-id <task-id> --cancel
Neo Task Workflow
1. Creating Tasks
Tasks are created with a natural language message describing what you want Neo to do:
- Infrastructure analysis: "Analyze my production stack for security issues"
- Maintenance operations: "Help me upgrade my Kubernetes cluster"
- Configuration changes: "Add monitoring to my Lambda functions"
- Multi-step workflows: "Set up a complete CI/CD pipeline for this project"
2. Entity Context
Provide context to Neo by attaching entities:
| Entity Type | Use Case |
|---|---|
stack |
Reference a Pulumi stack (name + project) |
repository |
Reference a code repository (name + org + forge) |
pull_request |
Reference a PR (number + merged status + repository) |
policy_issue |
Reference a governance policy issue (id) |
3. Task Status
| Status | Description |
|---|---|
pending |
Task is queued |
running |
Neo is processing the task |
waiting_for_approval |
Neo needs user confirmation to proceed |
completed |
Task finished successfully |
failed |
Task encountered an error |
4. Approval Flow
When Neo requires confirmation for an operation:
- Task status changes to
waiting_for_approval - Event contains
approval_request_id - User reviews the proposed changes
- Send approval or cancellation via the API
Common Workflows
Analyze Infrastructure
python scripts/neo_task.py --org myorg \
--message "What security improvements can I make to my AWS infrastructure?" \
--stack-name prod --stack-project aws-infra
Fix Policy Violations
python scripts/neo_task.py --org myorg \
--message "Help me fix the policy violations in my production stack"
Generate Pulumi Code
python scripts/neo_task.py --org myorg \
--message "Create a new Pulumi TypeScript project for a containerized web app on AWS ECS"
Review Pull Request
python scripts/neo_task.py --org myorg \
--message "Review the infrastructure changes in this PR" \
--repo-name infra --repo-org myorg --repo-forge github
Best Practices
Clear Instructions
- Be specific about what you want Neo to do
- Include relevant context (stack names, regions, requirements)
- Specify constraints (budget, compliance requirements)
Entity Context
- Always attach relevant stack or repository entities
- This helps Neo understand the scope of your request
Approval Workflow
- Review Neo's proposed changes carefully before approving
- Neo generates pull requests for infrastructure changes
- Use the preview feature to understand impact before deployment
Troubleshooting
Authentication Errors (401)
# Verify token is set
echo $PULUMI_ACCESS_TOKEN
# Test authentication
curl -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
https://api.pulumi.com/api/user
Organization Not Found (404)
- Verify organization name with
pulumi org get-default - Ensure your token has access to the organization
Cannot Respond While Request Pending (409)
- Wait for Neo to finish processing before sending new messages
- Poll for status updates before responding
References
- references/pulumi-neo-api.md - Complete API documentation