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:

1. Task status changes to waiting_for_approval
2. Event contains approval_request_id
3. User reviews the proposed changes
4. 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