Runtime Skills Turn Documentation Into Capability

A workflow written in a note is advice. A workflow encoded as a skill is capability.

Summary

Most teams overestimate how much value they get from documentation alone. They write good CLAUDE.md files, collect sharp notes, and build a strong doctrine around how agents should work. Then they wonder why the agent still re-derives the same steps, forgets edge cases, or behaves inconsistently across sessions. The missing layer is runtime skills. Skills convert passive knowledge into executable behavior at the exact moment it is needed. This is the difference between a knowledge base that explains good workflows and an environment that can reliably perform them.

The Problem

Documentation is static. It sits in a file and waits to be read. A skill is active. It is discoverable, loadable on demand, scoped to a trigger, and attached to concrete tool use.

That sounds like a small difference, but it changes the whole system.

If a process exists only in prose, the agent has to:

1. Remember that the note exists.
2. Search for it.
3. Decide that it applies.
4. Read it.
5. Translate it into a tool sequence.
6. Decide what output format to produce.

Every one of those steps is a chance to drift.

If the same process exists as a skill, the agent can skip most of that search and translation cost. The trigger matches. The body loads. The procedure is already framed for execution. The expected artifacts are already specified. The agent is not improvising from doctrine. It is following a prepared path.

This is why a system can have excellent notes and still feel operationally weak. The knowledge exists, but it does not exist at the point of use.

Documentation Explains. Skills Execute.

A note and a skill are not competing formats. They serve different roles.

Documentation is where you store rationale, tradeoffs, theory, examples, and broader context. It is the place for explaining why a pattern exists and how it connects to the rest of the system.

A skill is where you compress that knowledge into a repeatable operating unit.

The skill does four things that plain documentation usually does not:

1. Routing. It tells the agent when this workflow should activate.
2. Procedure. It gives the ordered steps for execution.
3. Constraints. It tells the agent what not to do, which tools to use, and which outputs matter.
4. Output contract. It defines what the result should look like.

Without these four pieces, you do not really have reusable capability. You have reference material.

This is the same distinction as library code versus a blog post explaining the algorithm. Both are useful. Only one can be called directly inside a running system.

Why Teams Stop Too Early

Most environments stop at documentation because writing a note feels like progress. Designing a skill is stricter. You have to define triggers, steps, constraints, and outputs. That effort feels narrower, but it is where the leverage sits. An agent does not become more capable because you wrote more about context engineering. It becomes more capable when recurring tasks stop requiring fresh derivation.

The Signature of a Missing Skill

A workflow should probably become a skill when all four conditions are true:

1. It recurs.
2. The steps are mostly stable.
3. It uses tools or references specific files.
4. The output shape is predictable.

If any of those are missing, the workflow may still belong in a note. If all four are present, leaving it in prose is usually waste.

The common symptoms of a missing skill are easy to spot:

• The same instructions get repeated in chat every few days.
• The agent performs the task differently each time.
• You keep reminding the agent about tool order, formatting, or edge cases.
• The root instruction file grows because it is trying to compensate for missing runtime workflow encoding.

That last one matters. Teams often bloat CLAUDE.md or AGENTS.md with operational detail that really belongs in skills. This hurts the base context for every task, including unrelated ones. A clean system keeps universal rules in the identity file and task-shaped workflows in skills.

What a Good Skill Actually Contains

A good skill is not a giant essay. It is a compact execution surface.

At minimum it should have:

• Clear frontmatter with a strong description
• A narrow statement of when to use it
• A narrow statement of when not to use it
• Ordered steps
• Required tools or files
• Expected deliverables

That is enough to turn a vague capability into dependable behavior.

For example, a kb-search skill might encode:

• Always run qmd query and rg in parallel
• Prefer short query expansions over broad corpus dumps
• Load only the top few relevant files
• Return findings with file references
• Reindex with qmd update && qmd embed after adding new notes

None of that is novel. The value comes from the fact that it is available at runtime, consistently, without re-explaining it.

The First Skills That Usually Matter

Most systems do not need fifty skills. They need the first few that remove the highest recurring coordination cost.

For a knowledge and writing setup, the obvious starters are:

• kb-search for hybrid retrieval, controlled context loading, and consistent findings formatting
• article-from-source for turning URLs or rough notes into drafts with the right title, length, and linking conventions
• session-compact for preserving current truth and next action during long tasks
• frontmatter-backfill for adding or normalizing metadata on legacy notes

Notice what these have in common. They are not abstract concepts. They are repeated environment operations.

Skills Compound Because They Remove Re-Derivation

The deepest reason skills matter is that they convert memory into infrastructure.

Without a skill, the agent must solve the same local coordination problem again and again. Even if it succeeds each time, you still pay the navigation and interpretation cost.

Udemy Bestseller

Learn Prompt Engineering

My O'Reilly book adapted for hands-on learning. Build production-ready prompts with practical exercises.

★ 4.5/5 rating

306,000+ learners

View Course

With a skill, the solution becomes part of the environment.

That is a compounding move. The cost is paid once. Future sessions inherit the result. Skills should therefore be reviewed like code. They shape runtime behavior, and weak ones quietly inject weak execution into every future session.

The Practical Rule

If a workflow is important enough to mention repeatedly, it is important enough to encode.

Do not confuse written doctrine with live capability. A beautiful note about how to search the knowledge base is still passive knowledge until a skill makes that behavior easy to invoke at the point of use.

That is the real role of skills in context engineering. They are not a convenience feature. They are the layer that turns what the system knows into what the system can reliably do.

Related

• Progressive Disclosure of Context – Why skills load better than monolithic instructions
• Agent Skill Bootstrapping – Letting agents extend the skill layer over time
• Long-Running Agent Patterns – Skills, shell state, and compaction for extended runs
• Ship the Prompt – Packaging operational knowledge for agent use