Documentation is one of those things everyone agrees matters, and almost nobody has time to do well.
In agency work, especially, the pressure is constant. You finish a project, you move to the next one. Writing docs means reading what you built, distilling it into something consumable, and structuring it so someone else can actually use it. That takes time nobody has. So the docs either don’t get written, or they get written badly, or they get written once and never updated.
I’ve watched this pattern repeat for years. Good intentions, poor follow-through. Not because people don’t care, but because good documentation is genuinely hard. It requires a different kind of thinking than building things.
Recently, I tried something different. Instead of hoping people would write better docs, I built a system that makes it harder to write bad ones.
The problem with ad-hoc prompts
The obvious move is to ask AI to write your docs. “Write a README for this project.” “Document this API.” It works, sort of. You get words on a page.
But the output is inconsistent. One README is detailed, the next is sparse. One API doc includes authentication, another forgets it. The AI doesn’t know your standards because you haven’t told it. Every time you prompt, you’re starting from zero.
This is the same problem you’d have with a junior engineer who joins the team and hasn’t read your style guide. They’ll produce something, but it won’t match what you need. The difference is that you can hand a junior engineer a style guide. With ad-hoc prompts, there’s no equivalent.
Unless you build one.
Skills as encoded constraints
In Claude Code, you can create “skills”, reusable definitions that shape how the AI approaches a task. Think of them as encoded expertise. Instead of explaining your documentation standards every time, you write them down once, and the AI follows them automatically.
I built a set of documentation skills based on the structure from Docs for Developers. There’s a router skill that helps you pick the right type of documentation: README, how-to guide, API reference, tutorial, or troubleshooting guide. Then there’s a specialised skill for each type, with specific guidance on structure, audience, and quality checks.
When someone runs /docs-readme, the AI doesn’t just generate a README. It follows a defined structure: what the project does, how to install it, a quick start example, usage, and configuration. It checks for completeness. It uses the tone and conventions we’ve established.
The output is consistent because the constraints are consistent. The AI isn’t guessing what a good README looks like. It knows, because we told it.
The type system analogy
If you’ve worked with typed languages, this will feel familiar.
Types constrain what values can flow through a system. You declare that a function takes a string and returns a number, and the compiler enforces it. You don’t have to remember what the function expects. The type tells you. And if you pass the wrong thing, you find out immediately.
Skills do the same thing for AI tasks. They constrain the input (what information the AI needs) and the output (what structure and quality it should produce). You declare what a “how-to guide” looks like, and the AI follows that declaration.
Prompt: "Write docs for this" → Unpredictable output
Skill: HowToGuide(task, prerequisites, steps) → Structured guideCode language: HTTP (http)The skill is the type signature. It defines the shape of the work.
This matters because AI is probabilistic. Without constraints, it will produce something plausible but not necessarily what you need. With constraints, it stays within bounds. Typed inputs, predictable outputs.
Documentation that serves two audiences
Here’s what surprised me: the same reference materials that constrain AI output also help humans write better docs.
The skills include guidance on writing for different audiences: beginners who need more context, experienced developers who want quick answers. They include checklists for quality. They include templates that show what “good” looks like.
A developer who’s never written a how-to guide can read the skill definition and understand the structure. One action per step. Include verification. Limit explanation. Link to conceptual docs if needed.
The documentation about documentation serves both the human and the AI. The human learns the standards. The AI follows them. Same source of truth, two consumers.
That’s not a side effect. It’s the point. The best AI context is documentation you’d write anyway. If you’re encoding your team’s standards for AI, you’re also encoding them for new team members. The investment pays off twice.
From ad-hoc to infrastructure
The shift I’m describing is from prompts to infrastructure.
Ad-hoc prompts are like inline styles in CSS. They work, but they don’t scale. Every time you want consistent output, you have to remember to include the same instructions. When your standards change, you have to update every prompt.
Skills are like a design system. You define the patterns once. Everyone uses them. When standards change, you update the skill, and every future invocation follows the new rules.
This is why I call it a type system. Types aren’t just constraints, they’re contracts. They encode agreements about how things should work. Skills do the same thing for AI-assisted work. They’re contracts between you and the AI about what “good” looks like.
The practical takeaway
If you’re using AI for tasks that have standards, documentation, code review, content transformation, or anything with a “right way” to do it, stop relying on ad-hoc prompts.
Build skills instead. Encode your standards. Write down what good looks like, what the structure should be, and what the quality checks are. Make the AI follow the same rules you’d want a team member to follow.
The documentation skills took a few hours to build. They’ll save hundreds of hours of inconsistent output, repeated explanations, and docs that don’t get written because nobody has time to think about structure.
That’s the difference between prompting and engineering. Prompts are one-off. Skills are infrastructure.
This post explores the Constrain phase of the Controlled Acceleration Model.