---
name: pulumi-create-agent
description: Create a reusable Pulumi Agent with saved instructions, a role, and selected integrations. Use when the user asks to create, define, or set up a new Pulumi Agent.
title: pulumi-create-agent
canonical_url: https://skilld.dev/gh/pulumi/agent-skills/pulumi-create-agent
last_updated: 2026-11-18T13:18:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/additional-outcomes.md](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/additional-outcomes.md), [references/automation-cli-contract.md](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/automation-cli-contract.md), [references/automation-recovery.md](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/automation-recovery.md), [references/automation-webhook-secrets.md](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/automation-webhook-secrets.md), [references/cli-contract.md](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/cli-contract.md), [references/configure-automation.md](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/configure-automation.md), [use_cases.yaml](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/use_cases.yaml).
>
> If the user asked to install this Skill, run `npx skilld install pulumi/agent-skills/pulumi-create-agent`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/pulumi-create-agent`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/pulumi/agent-skills/pulumi-create-agent) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/pulumi-create-agent`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/pulumi-create-agent --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/pulumi-create-agent --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Create a Pulumi Agent

Create a saved agent definition. Starting a task or configuring automation is a separate action.

## Discover and resolve

Confirm the target organization and current login with `pulumi whoami -v`. Do not infer the organization from the current stack or repository. Read [CLI contract](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/cli-contract.md) for operation discovery, request fields, and integration selection.

Check existing agents before choosing a name. If the name is taken, show the existing agent and ask how to proceed.

Resolve these settings from the user's request and project context:

- Name, display name, responsibility, resource scope, and expected output.
- Saved instructions, including relevant team requirements. These replace organization AI preferences, so include requirements the agent must retain.
- An organization role the caller may assign. Check its grants and exclude built-in Admin and Billing Manager roles. Instructions and deprecated `permissionMode` do not restrict authority.
- Connected MCP integrations. Set the selection explicitly, including `[]` for none; omission inherits all organization integrations.
- Approval mode. If unresolved, propose manual approval and explain that unattended runs may wait for a person.

Local files and uncommitted changes are not automatically available to the remote agent. Check that it can reach the repositories and connections needed for its responsibility. MCP selection does not control separate CLI credentials.

Ask only for missing choices. If a required API is unavailable or access cannot be verified, save a local draft with the known settings, complete instructions, and remaining questions. Explain the blocker without changing the requested access.

## Tell the user, then create

Show the complete configuration and literal instructions that will be saved:

```text
Organization:
Name and display name:
Responsibility and resource scope:
Role:
MCP integrations:
Approval mode:
Saved instructions:
[complete text]
```

Keep the instructions within the requested responsibility and resource boundary. For work outside that boundary, tell the agent to report the dependency and request a revised responsibility.

Submit exactly the displayed values using the request-file workflow in [CLI contract](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/cli-contract.md). If creation is already authorized and all choices are resolved, proceed without asking again.

## Verify the result

Read the returned agent ID and check active roster membership. Compare the saved name, display name, purpose, instructions, role, integrations, and approval mode with the proposal.

If values differ, report the saved result and the mismatch before making another change. Do not recreate or delete the agent as a rollback.

If the create response is lost, check the agent list and retrieve candidates before retrying. Follow all pages. A matching name alone does not prove the agent came from this request; use returned resource or request identifiers where available. If the outcome remains uncertain, report it rather than creating another agent. Do not treat a failed or incomplete listing as proof that creation failed.

Return the verified agent ID, organization, and saved configuration. Creation confirms the settings, not that the agent has successfully completed a task.

## Address automation

After creation, ask unless the user already supplied a preference:

“Would you like to set up automation for this agent: a schedule, an event trigger, or no automation for now?”

An unanswered automation choice does not block agent creation. Leave that choice pending if no answer is available.

If the user requested a schedule or trigger, continue with [Configure automation](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/configure-automation.md). If they declined, acknowledge manual invocation without asking again. Keep the created agent if automation setup fails.

For an explicitly requested first task, read [Requested immediate task](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/additional-outcomes.md). A one-time task does not answer the recurring-automation question.

Load automation details only when needed: [API contract](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/automation-cli-contract.md) for commands, [webhook secrets](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/automation-webhook-secrets.md) before webhook creation, and [recovery](https://skilld.dev/api/skills-raw/pulumi/agent-skills/pulumi-create-agent/references/automation-recovery.md) after an uncertain or mismatched result.
