Turn deployment runbooks into reusable skills

Spend twenty minutes reading r/coolify and you'll notice a specific arc: someone shows up, struggles for days, finally gets their app deploying, and then writes a post that lists eight or ten gotchas they wish they'd known.

The replies always thank them, and the next person to hit the same project starts fresh anyway — because the eight gotchas live in a forum post nobody finds at the right moment.

This pattern repeats across every self-host platform. Operators climb the same hill, write the same kind of post, and then watch the next operator climb the same hill. The knowledge exists; it just isn't reachable. The substrate that turns one-off discovery into compounding leverage is what's missing.

The fix isn't more documentation. It's treating deployment knowledge as a skill — a thing your tools can run, not just a thing your humans can read.

What "runbook as skill" actually means

A runbook is a sequence of human-readable steps. Useful, but inert. A skill is the same sequence, made executable by an agent or wrapped in tooling that can perform the steps with parameters.

If you treat a deployment runbook as a skill:

The eight gotchas show up as preflight checks run by the skill before the deploy starts.
The exact commands the operator figured out are embedded as the skill's actions, not as copy-paste blocks.
The skill can be invoked by name. The next deploy is "run the X skill," not "open the doc and follow ten steps."
The skill takes parameters — project name, domain, branch, secret refs — so the same logic serves many projects.
The skill emits structured output the agent or operator can inspect and learn from.

The operator still does the discovery once. After that, the discovery is reachable as code.

A concrete example: the Coolify Paperclip story

The Reddit pattern that triggered this post — someone fought through Paperclip on Coolify, hit eight specific gotchas, and packaged the whole flow as a reusable skill — is the model worth copying.

What the skill encoded:

Preflight: required env vars are set; the relevant secret IDs exist in Coolify; the upstream repo is reachable; the project's compose file matches the expected schema.
Setup: create the service in Coolify with the correct base image, the right port mappings, and the volumes that survive redeploys.
Deploy: trigger the build, watch for the specific error messages the operator saw on the first run, fail loudly when they appear with the exact remediation.
Verify: hit the health endpoint, confirm the container is the one with the new release SHA, confirm the volume is mounted, confirm the proxy is routing.
Cleanup: tag old images, prune leftover containers.

Anyone in the Coolify community can now run that skill on a new project and bypass the discovery. The first operator paid the cost; everyone after them gets the value.

Why "a doc" isn't enough

Docs are great for explaining why. They are terrible at being executed reliably six months later.

Docs rot silently. A command changes upstream. A flag is deprecated. The doc still reads like it works. The operator who follows it gets an error message at step five and has to debug their way out.

Docs don't carry parameters. A doc explains the steps for one project's setup. Translating those steps to a new project, with different names and constraints, is back to manual.

Docs assume context. "Make sure your Hetzner firewall is correct" assumes the reader knows what "correct" means. A skill can check.

Docs don't compose. Two related docs don't combine into a richer doc. Two skills compose: "deploy this app, then run the database migration skill, then warm up the cache."

The gap between "doc" and "skill" is the gap between knowing and doing. The trajectory of platform operations is toward more doing by tools, and skills are the unit of that work.

What this looks like inside a workflow

If you treat deployment as a skill space, your day-to-day shape changes in three ways.

Skills accumulate. Each tough deploy leaves a new skill behind. After a few months, the skill library covers most of the common deploy paths your team uses. New projects are mostly remix of existing skills.

Onboarding becomes "run these skills." A new operator joining a project doesn't have to learn the lore. They run the skills, and the skills perform the work the lore was supposed to encode.

Drift is detectable. When a skill stops working — because the upstream changed, or the platform got an update — you find out at runtime, not three months later in production. The skill carries its own verification.

This is genuinely different from "we have good docs." It's the difference between knowing how to do something and being able to invoke doing it.

How to start without a heavy framework

The move doesn't require a big platform. The first version of a skill can be:

A shell script with named parameters.
A YAML file the agent reads to know which steps to run.
A Makefile target with preflight checks and clear failure messages.
A Python or Node module exposed via MCP so the AI assistant can call it.

The substrate matters less than the discipline. The discipline is:

After every successful but painful deploy, write down the gotchas in one place.
Convert each gotcha into a preflight check that runs before the next deploy.
Wrap the whole flow in a single command (or skill) the next operator can invoke.
Keep the skill in source control alongside the project.
When the platform or upstream changes, update the skill, not just your memory.

Do this for three or four deploys and you'll notice the slope flatten. The pain stops compounding.

Where AI assistants fit

This is the natural shape an AI assistant can run. The assistant doesn't have to be the skill — it just has to know which skill to invoke when, with which parameters.

A typical interaction:

User: "deploy the auth-service to staging"
Assistant: identifies the right skill in the library, fills in parameters from project context, runs the skill, surfaces the output.
Skill: runs preflights, performs the deploy, runs verification, reports back.

The assistant becomes the operator's interface to the skill library. The skill is what actually does the work. The operator gets repeatability without having to type out the recipe each time.

This is the division of labor that scales. Humans figure out the hard part once. Skills encode it. Assistants invoke it. New problems get attention; old problems get a skill.

What to capture in a skill

A skill is most useful when it captures the non-obvious parts of a working flow. Worth listing what to put in vs leave out.

Put in:

Preflight checks for the conditions that broke things last time.
The exact commands, with parameters and defaults that worked.
The success criteria, including health checks and observable state.
The failure modes, with the error strings the skill should recognize.
Cleanup steps that prevent state pollution between runs.

Leave out:

General education about why deploys work. That belongs in docs.
Things the platform already does. The skill should be the delta between the platform's defaults and your project's needs.
Steps that exist only to make the operator feel in control. If a step doesn't change the outcome, it doesn't belong in a skill.

This discipline keeps skills focused. A skill that does too much becomes another doc; a skill that does just enough stays useful.

What to do this week

If you ship deploys regularly, the smallest move worth making this week:

Pick one project where the last deploy hurt.
List the gotchas you remember solving.
Write a script that runs the deploy with each gotcha as a preflight check.
Use that script for the next deploy on the same project.
After the next deploy, note any new gotchas; add them to the script.

By your fourth deploy on that project, the script has captured most of what the project's deploys actually need. You stop fighting the same eight problems. The script becomes the artifact other operators on your team — or future-you — can use.

That's how tribal knowledge graduates into infrastructure.

The short version

The Reddit pattern — paying for a deploy in days of debugging, then publishing the gotchas — is real, valuable, and undermonetized. The next move is to stop ending at "I wrote a post" and start with "I packaged the flow as a runnable skill." The skill outlives the post. It outlives the operator. It compounds across your team and your future. Skills, not docs, are the unit of deployment knowledge worth investing in.