Pulumi Neo Skill

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

Quick Start

IMPORTANT: Always use

--no-poll

Preferred: Python Script

python <skill-base-directory>/scripts/neo_task.py --org <org> --message "Your message" --no-poll

Alternative: Direct API

export PULUMI_ACCESS_TOKEN=<your-token>
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
curl -s -X POST "https://api.pulumi.com/api/preview/agents/<org>/tasks" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -d "{\"message\":{\"type\":\"user_message\",\"content\":\"How many stacks do I have?\",\"timestamp\":\"$TIMESTAMP\",\"entity_diff\":{\"add\":[],\"remove\":[]}}}"

Fetch events:

curl -s "https://api.pulumi.com/api/preview/agents/<org>/tasks/<task-id>/events" -H "Authorization: token $PULUMI_ACCESS_TOKEN" -H "Accept: application/vnd.pulumi+8" | jq '.events[-1].eventBody.content'

MCP Tools (if Pulumi MCP server is installed):

mcp__pulumi__neo-bridge

mcp__pulumi__neo-get-tasks

mcp__pulumi__neo-continue-task

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

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"

Entity Context

Attach entities for context:

stack

repository

pull_request

policy_issue

Task Status

running

idle

Note: Task completion and approval requests are determined by examining events, not task status.

Approval Flow

When Neo requires confirmation for an operation (this is a key concept — Neo never makes destructive changes without asking):

1. Task status remains

   running

   or transitions to

   idle

2. An

   agentResponse

   event contains

   tool_calls

   with an

   approval_request

   tool — this is the specific event structure to look for
3. The

   approval_request_id

   is found in the tool call parameters
4. User reviews the proposed changes
5. Send approval via

   --approve

   or cancellation via

   --cancel

Detecting approvals: Check events for

eventBody.tool_calls

approval_request

# Approve a pending request
python scripts/neo_task.py --org <org> --task-id <task-id> --approve

# Cancel/reject a pending request
python scripts/neo_task.py --org <org> --task-id <task-id> --cancel

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 --no-poll

Fix Policy Violations

python scripts/neo_task.py --org myorg \
  --message "Help me fix the policy violations in my production stack" --no-poll

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" --no-poll

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 --no-poll

Troubleshooting

curl -s -H "Authorization: token $PULUMI_ACCESS_TOKEN" https://api.pulumi.com/api/user

pulumi org get-default

--no-poll

--no-poll

export PULUMI_ACCESS_TOKEN="$PULUMI_ACCESS_TOKEN"

API Reference

Base URL:

https://api.pulumi.com/api/preview/agents

/{org}/tasks

/{org}/tasks

/{org}/tasks/{id}

/{org}/tasks/{id}/events

/{org}/tasks/{id}

Required headers:

• Authorization: token $PULUMI_ACCESS_TOKEN

• Accept: application/vnd.pulumi+8

• Content-Type: application/json

See references/pulumi-neo-api.md for full details.