The insta agent skill: what a coding agent needs to know to run cloud infrastructure
through InstaCloud — provisioning services,
deploying apps, forking a whole environment per branch, wiring credentials into an app,
passing governance approvals, and giving several agents a sandbox each.
Skills are Markdown following the Agent Skills format, so they
work in Claude Code, Codex, Cursor, OpenCode, Copilot, Gemini CLI, Windsurf and anything
else that reads a skills/ directory.
The insta CLI installs this skill for you:
insta --agent agent setupThat copies the skill user-globally for every coding agent on the machine and registers the
InstaCloud MCP server. insta --agent project create and insta --agent project link additionally install
the stack skills a project needs (Tigris, Better Auth) into the project
itself, along with the insta --agent agent observe credential-audit hook — see
governance.md.
To install the skill on its own:
npx skills add InsForge/instacloud-skills -s instaOr copy it into your agent's skills directory:
mkdir -p ~/.claude/skills && cp -r insta ~/.claude/skills/instainsta/
├── SKILL.md entry point: the model, setup, the two non-negotiables, governance
├── cli-reference.md every command, with flags, approval gates and plan limits
└── references/
├── setup.md CLI install, auth, a first project and its services
├── deploy.md source and image deploys, ports, custom domains
├── frameworks.md deploy recipes per framework
├── storage.md S3-compatible buckets: credentials, reading and writing objects, the traps
├── branching.md branch environments and the data that comes with them
├── governance.md approvals, policy, the credential audit
├── operate.md status, triage and recovery
├── migrate.md moving an app in from Heroku/Railway/Fly/Render: the ordered cutover
├── migrate/ what each source adds to that cutover: render.md, railway.md, fly.md, insforge.md
└── mcp.md the remote insta-cloud MCP server
SKILL.md is what the agent loads first; it routes to a reference when a task needs the
detail. cli-reference.md is the canonical description of the CLI surface — the
instacloud-cli repo links here for flags rather than
keeping a second copy, and a command or flag change there is not finished until it lands
here.
InstaCloud runs two separate deployments, and each gets its own branch of this repository:
| Environment | Skill source |
|---|---|
prod |
InsForge/instacloud-skills (main) |
staging |
InsForge/instacloud-skills#devel |
insta --agent agent setup installs prod's skill text by default — bare agent setup always targets
prod (CLI ≥ 0.0.38), switching a staging-leftover machine back. insta --agent agent setup --env staging
is the explicit staging setup; it installs the #devel skill text that describes the staging
control plane.
Use the #ref form when pinning a branch by hand. owner/repo@ref looks equivalent, but
the skills tool parses @ as a skill-name filter and silently leaves you on the default
branch — while still echoing the ref back in its progress output, so it reads as though it
worked.
- Reference the
instaCLI, not provider APIs. Skills say whichinstacommand to run. Provider-specific knowledge belongs behind the CLI and the control plane. - One skill, one capability. Split large topics by task.
- Include failure modes. A skill earns its keep by teaching what goes wrong and how to recover.
- Keep examples runnable. Agents execute the code blocks.
- Include
--agentin every agent CLI invocation, including npx examples. Bare human-admin approval/configuration commands are relay-only exceptions, never instructions for the agent to run.
A skill is a SKILL.md with YAML frontmatter:
---
name: <skill-name>
description: <one line; the agent uses this to decide whether to load the skill>
---
# <title>
<instructions, examples, failure modes, the `insta` commands to run>Apache 2.0. See LICENSE.