Anatomy of a Skill

Anatomy of a Skill

A "skill" sounds like a small thing. It's a set of instructions that teaches an AI assistant how to do one job well — qualify a lead, draft a follow-up, audit a dataset. You could write one in an afternoon, and plenty of people do.

But a skill an assistant reaches for at exactly the right moment, runs the same careful way every time, knows when to ask before acting, and hands off cleanly to other skills — that's a designed thing. The difference between the two is almost entirely in the craft, not the length.

This post takes one of ours apart to show you that craft. We're going to put a single skill on the table and open it up piece by piece. It's an identity skill — its job is to inspect a customer's data before that data goes into building an identity graph.

A quick word on what that means, in plain terms. An identity graph is how scattered records — an email here, a phone number there, a device somewhere else — get stitched together into a picture of a single person or household. It's powerful, and it's fragile: one bad connection can wrongly fuse thousands of unrelated people into a single tangled blob. So before we build the graph, this skill goes looking for the bad connections — a "person" carrying 400 phone numbers, an email address shared by ten thousand strangers — proves they're really there, and recommends the cleanup. (Under the hood it writes and runs queries in NQL, Narrative's query language, but you don't need to follow that to follow this post.)

We picked this skill on purpose. It's not the simplest one we ship, but it shows off nearly everything we care about — and, crucially, it spends most of its time calling on other skills to get its job done.

By the end you'll see why that last detail isn't a footnote. It's the whole point.

You can read the full skill on GitHub.

1. It knows exactly when to show up

An AI assistant might have dozens of skills available at once. The first thing every skill needs is a crisp answer to a single question:

when should I be the one to step in?

So every skill carries a short description written for that decision — including the actual phrases a person would say when they need it:

"audit this dataset before the graph build,"

"find the bad connections,"

"check the data quality."

Plain language, in the user's words.

Just as important is knowing when not to step in. Our skill is explicit about it: if you want open-ended analysis, there's a different skill for that; if you just want to run a query, there's another. It even draws the line in time — this skill works before the graph is built, not after.

The discipline here is simple: a skill that's vague about when it applies will either butt in where it isn't wanted or sit silent when it's needed. Getting this one paragraph right is what lets the assistant pick the right tool out of a crowded toolbox.

2. It has a point of view

Before any of the work begins, the skill establishes who it is and what it values. Ours describes itself, roughly, as a graph-quality specialist whose priorities — in order — are:

Evidence first.

Every cleanup it recommends is backed by numbers measured on this dataset. Never a rule borrowed from a past job, never a hunch.

Cut conservatively.

Because one bad connection can collapse thousands of distinct people into one, it's careful and deliberate about what it removes.

Remove the bad, keep the good.

Sweeping, lazy fixes that throw away real data are "easy and wrong."

Notice what this isn't: there's no puffery, no "world-class expert with twenty years of experience." We've found — and the research backs this up — that dressing a skill in fake credentials does nothing for the quality of its work, and can even make it worse. What actually shapes good behavior is a clear, honest statement of priorities and the specific things the skill refuses to do. Our skill refuses to recommend a cleanup without proof of its impact. That refusal is the persona doing real work, not decoration.

3. It tells the assistant only what it needs, when it needs it

Here's the practice that does the most quiet good.

An AI assistant's attention is a finite resource — much like a person's. Bury it in a fifty-page manual and it does worse on the actual task than if you'd handed it the one page that matters. So we never load everything at once.

The skill itself is kept lean: a clear procedure and the handful of rules that apply every single time. The deep material — the full catalog of things that can go wrong with identity data, the detailed templates, the rare edge cases — is tucked away in separate reference files the skill only opens when it actually hits that situation.

The mental model we use: a good skill teaches the assistant where to look when a specific case comes up, not the contents of every possible case. Think of the main skill as a sharp table of contents, with the heavy reference material one step away. It keeps the assistant focused, and it keeps the skill easy to improve over time — a new edge case gets filed in its own reference instead of bloating the part everyone reads every time.

4. It works in the open, one step at a time, and proves its claims

Three habits govern how the skill actually runs.

It asks one question at a time.

When it needs to know something that changes its recommendations — say, whether this data will be combined with other sources later — it asks a single, focused question and waits. It walks you through the work; it doesn't hand you a form to fill out.

It won't skip the hard parts.

Certain steps are mandatory and can't be short-circuited: framing the question, listing what might be wrong, testing each of those, measuring the damage, and only then proposing a fix. A skill that can be rushed to its conclusion isn't a workflow — it's a guess with confidence.

It insists on evidence.

This is the heart of the skill, and its rule is blunt: an unproven hunch is not a finding. Every problem it flags comes with the numbers — how many records are affected, how many people, what share of the whole — measured on your actual data. The point of view from step 2 promised evidence; this is where the skill is forced to deliver it.

There's a fourth habit we lean on across all our skills:

Show the work, and wait for a human before doing anything consequential.

For skills that send an email or post a message, that means drafting it and pausing for approval. This particular skill expresses the same instinct its own

way — it figures out the cleanup and writes the query to do it, but it stops short of running it. Whether and when to actually change the data is the customer's call. The skill produces something you can review, and then it gets out of the way.

5. Shared pieces are written once

Many of our skills need to do the same small things — confirm which company's data we're working with, explain how they'll behave if a tool isn't available, follow the same voice guidelines. Rather than rewrite that prose in every skill, we write it once and reuse it everywhere. It sounds like housekeeping, but it has a real payoff: when the underlying system changes, we update one shared piece and every skill that uses it stays correct automatically. No drift, no ten slightly different versions of the same instruction slowly falling out of sync.

6. It degrades gracefully — and runs almost anywhere

Two more habits that look like polish but are really about reach.

It bends instead of breaking.

The skill works best with full access to Narrative's tools, but if one of those tools isn't available, it doesn't crash or quietly skip something important. It falls back to a simpler mode and tells you plainly what it can't do this time.

It isn't locked to one product.

We build our skills to an open, shared standard, so the same skill can run inside many different AI assistants — not just the one we happen to use in-house. Anything specific to a particular assistant is kept off to the side, so the core skill travels cleanly to wherever a customer wants to use it.

7. The part that makes it composable

Now the payoff. Look again at what this skill actually does from start to finish, and notice how little of it the skill does alone:

To understand the shape of the data, it hands off to a profiling skill instead of inspecting everything itself.

To test its theories about what's wrong, it hands the whole batch of questions to an analysis skill, which in turn calls on a query-writing skill to do the actual work.

To produce the final cleanup, it hands that off to the query-writing skill one more time.

The skill's own contribution is the part only a graph-quality specialist can do: deciding what to suspect, how to measure the damage, and which cleanup is the careful, minimal one. Everything else — profiling, analysis, writing the queries — it borrows from skills that already do those jobs well.

This is composition, and it's the difference between a pile of one-off AI prompts and an actual system. When we make the query-writing skill smarter, every skill that leans on it gets better for free — no edits required. When the profiling skill learns to spot a new kind of problem, this skill inherits that skill instantly. Each piece stays small enough to trust because it doesn't try to do everything.

Skills are one layer of a bigger idea

Step back, and all of these habits resolve into one principle.

A skill that knows when to step in is one an assistant can choose correctly from many. A skill with a clear point of view and a careful, evidence-backed procedure is one you can trust as a building block. Telling the assistant only what it needs is what lets many skills work side by side without crowding each other out. Shared pieces keep them consistent. Running almost anywhere means a skill works wherever the customer does. And composition is the wiring that turns all those trustworthy, well-behaved pieces into workflows bigger than any one of them.

Here's the thing, though: a skill is just one layer. The same principle runs all the way down the stack.

Under the skills sit the tools and data connections they reach for (through an open standard called MCP). Under those sit the data planes where a customer's data actually lives and gets queried. The skills run inside different assistants and harnesses — the products people work in day to day. And underneath everything are the foundational models that do the reasoning, swapped in and out as better ones arrive.

The bet we're making is that every one of those layers should be a clean, swappable, dependable piece — and that none of them should try to be the whole system. A skill shouldn't be welded to one model. A model shouldn't be welded to one product. Data shouldn't be welded to one tool.

That's what we mean by Composable AI. Not one enormous model trying to hold an entire job in its head — but a stack of focused, interoperable parts you assemble to fit the problem in front of you, and recompose when the problem changes. The skill we took apart today is a graph-quality specialist that employs a profiler, an analyst, and a query writer — and it, in turn, is one part of a much larger picture.

The anatomy of a single skill, it turns out, is mostly the anatomy of how it connects to everything around it. Build each piece well — knowing when to appear, what to value, what to surface, where to stop, and how to hand off — and what you've really built is something that fits.

Curious how the rest of the library is built? Explore the open-source skills marketplace on GitHub.

‍