# Introducing the Deployment.io Skill: A Playbook for Your Coding Agent

A month ago we shipped the deployment.io MCP server. Your coding agent could deploy from the conversation — "ship this to staging", and it would. But the tools were only half the job.

The agent had _what to do_, not _how to do it well_. It would guess the wrong `publish_directory` for a Vite app. Forget to push unpushed commits before deploying. Keep retrying a deploy that was waiting for approval. Tools need a playbook.

## Introducing the Deployment.io Skill

Today we're open-sourcing the **deployment.io skill for coding agents** — a SKILL.md-compliant runbook that teaches your agent how to deploy on deployment.io, correctly, on the first try.

It's one file. MIT licensed. Lives at <a href="https://github.com/deployment-io/skills" target="_blank" rel="noopener noreferrer">github.com/deployment-io/skills</a>.

```bash
git clone --depth 1 --branch v0.1.0 https://github.com/deployment-io/skills.git /tmp/dio-skills
mkdir -p ~/.claude/skills && cp -r /tmp/dio-skills/skills/deployment-io ~/.claude/skills/
```

Restart your agent. Done.

## What the Skill Changes

Without the skill, your agent figures things out by trial and error. With it, the agent knows:

- **Framework → publish_directory.** Vite/Svelte/Astro → `dist`. Create React App → `build`. Next.js static export → `out`. Hugo → `public`. Jekyll → `_site`. Picked correctly the first time.
- **`is_spa` = true for client-side routers, false for static site generators.** No more broken deep links or duplicate-content issues.
- **Port discovery for web services.** Reads the Dockerfile `EXPOSE`, app listen calls (`app.listen(3000)`, `http.ListenAndServe(":8080")`), or `PORT` env usage.
- **Health-check routes.** Searches for `/health`, `/healthz`, `/ping`, `/ready` before defaulting to `/`.
- **Git pre-flight.** Runs `git fetch`, checks for unpushed commits, captures the exact SHA for `commit_hash` — so the runner deploys what you verified locally.
- **Diagnose-bad-deploy.** When a deploy fails, the agent pulls `get_deployment_logs` for a window around the failure and reads the job output, instead of asking you what went wrong.
- **Approval flow.** If a deploy to a protected environment returns "Approval required", the agent polls `get_approval_status` — it doesn't retry the original call.

Your agent just gets better at deploys. You don't have to explain any of this up front.

### What that looks like

Without the skill:

> **You:** Deploy my React app to staging.
> **Agent:** What's the build command? What publish directory? Is it a SPA? Do I need to push first?

With the skill:

> **You:** Deploy my React app to staging.
> **Agent:** Running `git fetch origin main`. You have 2 unpushed commits — pushing now. Detected Vite + react-router-dom, so `publish_directory: "dist"`, `is_spa: true`. Deploying commit `a3f9c21`. Here's the approval link for the staging environment...

Four questions vs. four actions. Same input from you.

## The Numbers

When we moved the runbook out of the tool descriptions and into the skill, our **most-used tool descriptions shrank by ~80%**. `deploy_static_site` went from ~1,500 chars to ~380. `deploy_web_service` went from ~2,000 chars to ~280. Every MCP-connected session — even one that never triggers the skill — now pays less context tax.

More capability, less overhead per conversation.

## Works Across 30+ Agents

SKILL.md is an open standard (<a href="https://agentskills.io" target="_blank" rel="noopener noreferrer">agentskills.io</a>). The deployment.io skill works with:

- Claude Code
- Claude Desktop
- Cursor
- OpenAI Codex
- Gemini CLI
- GitHub Copilot
- Antigravity
- JetBrains Junie
- ... and 25+ others

One file. Install it once per agent, works across every project.

## Why This Is Separate from the MCP Server

The MCP server is always on — every session loads its tool descriptions, so it stays lean. The skill loads only when your prompt matches a deploy intent, so it can be rich (framework tables, multi-step runbooks, diagnostic recipes) without bloating sessions that don't need it.

Progressive disclosure. Your agent gets the runbook exactly when it needs it.

## Try It

If you already have the MCP server connected:

```bash
git clone --depth 1 --branch v0.1.0 https://github.com/deployment-io/skills.git /tmp/dio-skills
mkdir -p ~/.claude/skills && cp -r /tmp/dio-skills/skills/deployment-io ~/.claude/skills/
```

If you don't — start with the <a href="/docs/coding-agents/mcp-configuration/">MCP configuration guide</a>, then come back and install the skill.

Ask your agent to deploy something. Watch it run the git pre-flight without being told, pick the right `publish_directory`, and diagnose its own failures.

That's the playbook.

---

- **Install paths for Cursor, Codex, Gemini CLI, and more:** <a href="/docs/coding-agents/deployment-io-skill/">docs/coding-agents/deployment-io-skill</a>.
- **Source, issues, and releases:** <a href="https://github.com/deployment-io/skills" target="_blank" rel="noopener noreferrer">github.com/deployment-io/skills</a> — ⭐ the repo to get notified when we ship updates.
- **Extend it.** MIT licensed. Fork and layer in your team's deploy conventions — PRs welcome.
- **Feedback?** Open an issue on the repo or reach out — we're iterating on this actively.

---

Source: https://deployment.io/blog/deployment-io-skill-for-coding-agents/