← Back to the section

Skills: packing a methodology into an AI agent's skill

A methodology has an awkward property: it lives in people's heads and in articles, but it has to work on every PR. Between "I read how to do it right" and "the code in the repo is actually written right" there's a gap, and almost everything falls into it. A person remembers a rule at the moment they formulated it; a month later, under deadline pressure, they don't. An AI agent doesn't remember it at all: every new session starts from a blank slate — it wasn't at your standup and never read your wiki.

A skill is a way to close that gap. Take a piece of the methodology that would otherwise stay in an article or a head, and turn it into an agent skill — a rule the agent loads and applies automatically: when it writes code, when it reviews a PR, when it designs a new operation. Not "written down somewhere," but "applied every time."

This article is about skills as a concept. It belongs to the AI tooling triad alongside MCP and Memory Bank: a skill gives the agent rules (what's allowed, what isn't, how to do it right), MCP gives it hands (access to systems), Memory Bank gives it memory (project context). Here we cover the first vertex.

What a skill is

The easiest way to get it is by contrast with documentation. Documentation is text a human reads and decides whether to apply. A skill is a rule the agent applies without asking.

The difference isn't the medium (both are markdown files), it's the recipient and the moment of firing. An API style guide sits in the wiki — read once at onboarding, then forgotten. The same guide framed as a skill gets loaded by the agent at the moment it's writing a controller, and it follows it because it sees the matching context. The knowledge stops being reference material and becomes executable.

Take a concrete case. A developer asks the agent: "build a pay-order endpoint." Without a skill, the agent writes competent but average code — the kind most common in its training data: /api/payments/{id}/pay, a raw String instead of a typed identifier, an error as a bare string. With the api-design skill, which encodes the project's rules (URLs in kebab-case, version in the path /v1/, idempotency via a header, errors per RFC 9457), the agent writes the endpoint in your project's style. And the prompt isn't any longer — the rule is already loaded, no need to repeat it every request.

One piece of knowledge in two forms

This is the core of the whole section and, arguably, of the whole site. Every piece of the methodology exists twice: as an article and as a paired skill.

  • The article — for the human. To understand the subject: why it matters, what the forks are, how to choose. The article explains, argues, gives counterexamples, and honestly says when a rule doesn't apply. Its job is to build a mental model you can decide with yourself.
  • The skill — for the agent. To apply: the same subject compressed into a checkable rule with a code (API-3, AGG-X4). A skill doesn't explain or persuade — it prescribes, and cites itself in the review.

Why exactly two representations and not one? Because they have different recipients with different needs, and trying to get by with one breaks both.

Keep only the article — the agent can't apply it. Prose doesn't parse into a rule: the agent can't extract a checkable criterion from a paragraph that says "try to make URLs readable." The knowledge stays decorative — nicely written, but with no effect on the code.

Keep only the skill — the human loses understanding. Rule AGG-X4 without the article is a command with no rationale. The developer sees "AGG-X4 violation" in review, fixes it mechanically, and learns nothing. And when the rule turns out to be a poor fit for their case (it happens — rules aren't absolute), they can't judge that, because they don't know where the rule comes from or what it guards against.

The link between the forms is direct: it's literally one piece of knowledge, captured from two sides. The article is the understanding side, the skill is the execution side. Read the article yourself — you understand what the agent does, and you can argue with it on the merits. Hand the agent the skill — it holds the rule while you think about the product, not about not forgetting idempotency. That's the product-engineering setup: the human owns the meaning, the agent owns the execution, and both look at one source.

How a skill is built

No deep craft, just the shape of it. A skill is a small markdown file in three parts:

  • A name and when to apply it. "api-design — designing a REST endpoint." From this description the agent knows in what context the skill is relevant and loads it on its own.
  • The rule or instruction itself. What to do and what to avoid. Often a set of items with unique codes (API-1, API-2, …) so you can point at them precisely.
  • "Do" and "don't" examples. So the rule doesn't stay abstract: the agent (and the human) needs a specimen.

The key subtlety: rules aren't hardwired into the skill. The skill is thin — an executor-instruction. The rules themselves live as a separate corpus that changes without breaking the skills. The analogy is a linter plugin, where the rule config is separate from the engine. One source, two renders: the same file becomes an HTML article for people and is read by the agent as plain text. They physically cannot diverge, because it's one file.

A set of such skills forms an executable corpus — and it shows how it's built inside: names, rule codes, split by aspect (API, style, tests, DDD tactics).

How to write and maintain a paired skill

The recipe is short, and it also explains why the forms don't drift apart.

  1. Write the article. Work the subject out for a human: the problem, the forks, how to decide. At this stage you figure the topic out yourself — if you can't explain it, there's no skill yet.
  2. Extract a checkable rule. From the article, pull what can be checked mechanically: not "do it well," but "the identifier is a typed VO, not a String." Give it a code.
  3. Frame it as a skill. Name, when to apply, the rule, "do/don't" examples.

Then the main thing: they change together. Change your mind about a rule — you edit both the article and the skill in one move. Divergence is a bug you catch by eye: if the article says one thing and the skill does another, someone forgot the pairing. That's why we keep them next to each other, in one repository, under one review.

It's a narrow, incremental process: one aspect — one article — one skill. Not "describe all of development at once," but closing gaps one at a time, where it actually hurts.

Its place in the triad — and one powerful special case

A skill on its own is half the picture. It tells the agent how to do it right, but doesn't grant access to systems (that's MCP — the hands) and doesn't remember the decisions of your specific service (that's Memory Bank — the memory). Together the three turn the agent from "smart but a stranger" into "smart and yours": rules + access + context.

And one special case of a skill deserves its own discussion — when a set of skills works as an executable engineering standard: a versioned corpus of rules the AI applies on every PR instead of a tech-lead bottleneck, citing a specific rule with a link. That's the most powerful form of "a skill as a review capability," and it has its own article — executable standard. That's also where you'll find why it reaches where SonarQube can't.

The general backdrop under all of this is why you need a methodology at all if AI writes the code: skills are the mechanism through which a methodology stops being text and becomes the agent's behavior.

In short

  • A skill is a piece of the methodology packed as an agent skill: a rule the agent applies automatically on every PR, in review, during generation. Not documentation you read — an executable rule.
  • One piece of knowledge in two forms. The article for the human, to understand; the paired skill for their agent, to apply. One won't do: without the article the agent applies but the human doesn't understand or argue; without the skill the human understands but the agent doesn't apply.
  • The build is simple: a name, when to apply, the rule with codes, examples. The rules are a separate corpus, the skill is thin; one file renders both into an article and into an agent instruction.
  • Written in pairs: article → extract a checkable rule → frame it as a skill; from then on they change together. Divergence is a bug.
  • The triad: the skill (rules) works together with MCP (access) and Memory Bank (context). The most powerful special case is the executable standard.