Your Deploy Runbook Should Be a Skill, Not a Wiki Page

The agent that deploys your app at 2 a.m. will never open your wiki. It cannot browse Confluence, it will not remember the pinned Slack thread from March, and it will absolutely improvise the rollback order if the procedure lives only in a senior engineer's head. Meanwhile, the same agent already knows how to read one very specific thing on sight: a SKILL.md file sitting in a versioned directory, loaded on demand the moment its task matches the skill's description. Thirty-five-plus agent harnesses — Claude Code, Cursor, VS Code, Codex, Gemini CLI, GitHub Copilot — all read that same format today.

That is the quiet infrastructure story behind Anthropic's Agent Skills: the runbook finally has a file format the operator, human or agent, actually loads. This post converts a fleet's three core procedures — deploy, rollback, log triage — from wiki folklore into versioned skill bundles, and then draws the line skills must never cross: they carry knowledge, not authority. The governed tool surface still has to be the thing that says no.

What an Agent Skill actually is​

A skill is a directory with a SKILL.md entrypoint: YAML frontmatter (name, description) plus Markdown procedure, optionally bundled with scripts, templates, and reference files the agent can execute or read. The harness matches the task against each skill's description and loads the winner into context — progressive disclosure, so the agent carries the deploy procedure only when it is deploying, not on every turn.

The format history matters because it explains the adoption curve. Anthropic launched Skills as a Claude feature on October 16, 2025, then published the Agent Skills specification as an open standard on December 18, 2025, with a spec and reference SDK at agentskills.io. Within 48 hours Microsoft had integrated it into VS Code and OpenAI into ChatGPT and Codex CLI; by March 2026, 32 tools from competing vendors read the same files, and the ecosystem now spans 35-plus runtimes including Cursor, JetBrains Junie, AWS Kiro, and Block's Goose. The reference collection at anthropics/skills passed 100,000 GitHub stars. Anthropic ran the exact playbook it used for MCP: build something useful, open it up, let adoption do the rest.

For a fleet operator, the consequence is simple: procedural knowledge written once as a skill is portable across every harness your team uses. The runbook stops being per-tool configuration and becomes a repo artifact.

Anatomy of a deploy runbook as a skill​

Here is the core conversion. Take the deploy procedure — build, push, rollout, verify, promote — and package it as a skill directory checked into the repo next to the service it deploys:

skills/fleet-deploy/
├── SKILL.md            # frontmatter + ordered procedure with gates
├── scripts/
│   └── verify-rollout.sh   # health-check polling the agent runs, not invents
└── references/
    └── rollback-triggers.md  # when to stop the deploy and switch skills

The SKILL.md itself reads like the runbook you wish your wiki had, except the consumer is specified:

---
name: fleet-deploy
description: Deploy a service on the fleet. Use when asked to ship, release,
  roll out, or promote any app. Covers build, rollout, verification gates,
  and when to abort to the fleet-rollback skill.
---
 
# Fleet deploy
 
1. Build the service image from the pinned commit. Never deploy `:latest`.
2. Push to the fleet registry and record the digest.
3. Roll out to one canary node; wait for `verify-rollout.sh` to report
   healthy for 5 consecutive minutes before touching the rest.
4. Roll out to the remaining nodes in batches of 25%.
5. After each batch, re-run verification. On any gate failure, stop and
   follow `fleet-rollback` — do not retry the batch.
6. Promote: update the pinned digest in `fleet/services/<name>.yaml`
   via pull request. The deploy is not done until the pin PR merges.

Three properties make this different from the wiki page it replaces. First, it is loaded by matching: the agent does not need to know the runbook exists, only to be asked to deploy — the description routes the task to the procedure. Second, it bundles the executable parts: verify-rollout.sh is the same script CI runs, so the agent polls health with your check instead of improvising curl loops. Third, it is reviewed like code: a change to step 3 goes through a pull request, with diff, blame, and revert — try getting that from a Confluence edit history at 2 a.m. And because it is a file in the repo, it gets the rest of the software toolchain for free: CI can validate the frontmatter against the spec with the reference skills-ref library, lint the procedure for banned phrases ("ask Dave in chat"), and run the bundled verification script against staging on every change. A runbook that fails CI cannot silently rot; a wiki page can rot for years without anyone noticing.

Same pattern: rollback and log triage​

The pattern generalizes because fleet operations are mostly a small set of procedures with sharp trigger conditions. Two more skills complete the on-call trio:

fleet-rollback — description routes any "revert, roll back, undo the deploy" request here. The procedure inverts the deploy: identify the last pinned digest from fleet/services/<name>.yaml history, roll out the previous digest with the same batched verification gates, freeze new deploys until the postmortem issue exists. Its most important line is a trigger condition, not a step: if verification fails twice, page a human instead of rolling back a third time — the judgment call wiki runbooks bury in paragraph four becomes step zero.

fleet-log-triage — description matches "why is X failing, check the logs, what's erroring." The procedure encodes the query sequence your best on-call engineer runs from muscle memory: last deploy timestamp first (most incidents are deploys), then error-rate by service over the incident window, then the specific failing pod's events and previous-container logs. Bundled reference files hold the exact queries per backend, so the agent fills in service names instead of guessing query syntax.

Community precedent exists: public collections already ship sre-runbooks skills implementing Google SRE-style incident response with agent-safe execution patterns, and DevOps plugins bundle incident-management skills for on-call, postmortems, and response. The fleet trio above is the self-hosted PaaS version of an already-proven shape.

What skills can't do (and why your MCP server still says no)​

Here is the boundary, and it is load-bearing: a skill carries knowledge, not authority. The SKILL.md file is Markdown. It holds no credentials, enforces no policy, and cannot stop a compromised or confused agent from ignoring step 5. Anthropic's own framing is explicit: skills teach Claude how to do something; MCP gives Claude access to something. The deploy skill says "promote via pull request"; the thing that actually refuses a direct push to the pin file must be the tool layer — branch protection, the MCP server's allow-list, the harness permission model.

Treating skills as enforcement would also be a security hole in the other direction. Skills distribute like packages — marketplaces, git repos, .skill zips — with package-like supply-chain risk: typosquatting, repo hijack, malicious instructions buried in long files. Snyk's ToxicSkills study found prompt injection in 36% of sampled skills with 1,467 malicious payloads, and executable skill scripts carry roughly double the vulnerability risk of instruction-only skills. The ecosystem response — scanners like skillvet that quarantine risky skills before install, allowed-tools pre-approval, workspace trust boundaries — all treats the skill as untrusted content to gate, never as the gate itself.

So the architecture for deploy-from-chat is two layers, not one: versioned skills that teach the agent your procedures, over a governed MCP tool surface that holds the credentials and the veto. Runbooks that travel with the repo; refusals that live in the tools.

What changes for deploy-from-chat​

With that split in place, the deploy-from-chat roadmap stops depending on prompt folklore. Onboarding a new harness means pointing it at the skills directory, not re-teaching it your fleet. Updating the canary window from five minutes to ten is a pull request with a diff, a reviewer, and a revert button. Auditing what the agent was told to do during an incident means reading the pinned skill version from git, not reconstructing a system prompt from memory. Postmortems get sharper too: when the agent follows the skill and the outcome is still wrong, the bug is in the procedure — file it against the skill, fix the step, and every future deploy inherits the lesson. That feedback loop is what turns operations knowledge from tribal memory into a versioned asset that compounds. And because the format is an open standard with three dozen runtimes, none of this locks you to one vendor's agent — the runbooks outlive the harness.

The wiki had a good run. But documentation the operator never loads is decoration. Package the procedure as a skill, govern the tools underneath it, and the 2 a.m. deploy finally follows the runbook — because the runbook is the thing the agent reached for first.

Bex.co is the open-source, AI-native Render alternative — push a git repo, get a running HTTPS service on machines you own, with agents as first-class operators. Star the repo on GitHub or deploy your first app today.