Agent Skills: Turn Your Working Knowledge into Reusable Workflows

The job I kept explaining twice

Last month I recorded a training session and asked an agent to turn it into learner notes.

The first draft wasn't bad. It also wasn't mine. My voice had been flattened into a neutral report. The analogy I use to explain why a tool call runs outside the model was gone. And the opening said “in yesterday's session”, which tells a reader nothing if they weren't there.

So I marked it up. Keep the first person. Drop the chatter, but keep the questions people asked. That example stays. Ask me before guessing at words you can't hear clearly.

The second draft was closer. By the fourth, I could review it properly instead of rewriting it.

Then I opened the next recording, and the agent knew none of it.

That's the moment a skill becomes worth building. Not when the work is interesting, but when the work repeats.

An Agent Skill packages a process — the instructions, the checks, the scripts, the templates — so it survives the conversation that created it.

Now I say “turn this recording into learner notes”, and the agent goes looking for the skill. It reads the workflow, follows it, and comes back with a draft that starts much closer to the one I want. I still review it. That part doesn't change.

The prompt gets shorter, which is the least interesting thing about it. The interesting thing is that a conversation stops being a one-off. What I explain once becomes part of how the next job gets done.

A skill is a written procedure, not another agent

When I say I built a skill for a job, people hear three different things. A program. An agent. A document.

The Agent Skills format is the third one. A skill is a directory with a file called SKILL.md at its root, plus whatever else the procedure needs: scripts, templates, examples, reference notes. It doesn't start a process, listen for an event or call a service on its own.

Most of the confusion comes from words that sound interchangeable and aren't.

Part	What it contributes	In the learner-notes workflow
Model	Interpretation and generation	Decides how a spoken explanation becomes clear prose
Harness	Context and tool execution	Reads files, runs commands, manages the session
Skill	A reusable procedure and its resources	Specifies the voice, the checks, the output format
Tool or script	An operation the agent can invoke	Transcribes the recording, renders Markdown to PDF
Project files	The material for this instance of the work	The recordings, transcripts and finished notes

People sometimes assume a skill is a small agent. It isn't, and the difference matters: a skill doesn't start anything or reach anything. It gets read.

Think about onboarding an experienced colleague. They already know how to write and how to investigate a problem. What they don't know is this: we never publish notes without reading them first, the transcript is the authority when the recording is unclear, and a PDF leaves the building only after someone approves it.

That's the shape of the knowledge inside a skill. Not “how to write”, but “how we do this here, and what counts as finished”.

It's also worth separating a skill from a project log, because the two look similar on disk. A log records what happened on Tuesday. A skill describes how to do a kind of work again. One is a diary. The other is a method.

The result comes first

Nobody wants a transcript.

They want a document they can read on a train six months later and still follow. So the skill can't be organized around whichever command happens to be available. It has to be organized around the result.

Recording
    → transcript
    → learner-notes draft
    → factual and coverage checks
    → human review
    → formatted document

Every arrow is a place where the work can go wrong, and most of those places have nothing to do with the model being clever. The wrong recording gets picked. The transcript loses a speaker. A claim that nobody verified survives into the final PDF because it sounded confident.

So my skill describes what each stage must produce, not just what to run.

• The input is a recording or a transcript. If two files could match the request, the agent stops and asks.
• The transcript may already exist. If it doesn't, one gets produced.
• The notes are written in the instructor's first-person voice. Filler goes, participant chatter goes, technical substance stays.
• Examples that did real explanatory work stay in, and the concepts get explained for someone who wasn't in the room.
• Claims get checked, and the draft gets compared against the transcript for anything that went missing.
• Unresolved questions come back with the draft rather than disappearing into it.
• Only the approved text gets rendered into the requested format.

The same shape turns up outside document work:

• Investigating an alert: gather the metrics and logs that matter, explain the evidence, recommend a next step.
• Preparing a training invoice: compare delivery records against calendar entries and notes, propose the billable sessions for review.
• Finding reading for a course: interpret each outline topic, search a knowledge base, pick relevant articles, assemble a report.

Not every helper deserves to become a skill, though. A log-fetching function is a script, and wrapping it in a folder of prose doesn't make it more useful. A skill earns its place when the work has a name, a finish line, and something that can go wrong.

Learn the work before you write it down

I've never written a good skill from a blank page.

The useful ones came out of a messy conversation. I give the agent a transcript and describe the output. It produces something. I point at the places where it isn't what I meant. Perhaps it removed an analogy that was doing real work. Perhaps it wrote “yesterday's session” into a document that has to stand alone. Perhaps it tidied away a hesitation that was actually the point.

Those corrections are the material. Not the polished instruction I could have written beforehand — the corrections.

Once the result is right, I ask for the method:

Capture the reusable workflow from this conversation as a skill. Include the output requirements, the checks, the scripts we need and the points where you must ask me before continuing. Keep this recording's details out of the general instructions.

An agent can draft both the instructions and the code. Neither arrives correct. I read them the way I'd read a pull request from someone who hasn't seen the rest of the system.

This is where tacit knowledge finally gets a chance to surface. “Make good notes” isn't an instruction; it's a mood. “Keep the analogy that explains why a tool call runs outside the model” is something an agent can act on.

Notice also what that request leaves out. The recording's details stay behind. The skill is about the job, not about the job I happened to do on the second of November.

And the first version is never general. It handles one recording, then another. Rules arrive when a real failure asks for them, which is a far better teacher than my imagination.

One thing worth saying plainly: editing a skill isn't training the model. The weights don't move. What changes is the text I hand over next time.

What actually goes inside the skill

The folder holds one file that matters more than the rest.

SKILL.md begins with YAML front matter — metadata between two lines of ---. Two fields are required: name and description. Everything after that is Markdown, and it's where the actual procedure lives.

Here's a small one. It describes a text-only workflow, so it doesn't need a script:

---
name: transcript-to-learner-notes
description: Turn teaching transcripts into standalone learner notes in the instructor's first-person voice. Use when asked to convert a transcript into learner notes or teaching notes.
---

# Transcript to Learner Notes

## Input
Read the transcript supplied by the user. If more than one transcript
could match the request, ask which one to use.

## Workflow
1. Identify the main topics and the examples that explain them.
2. Write standalone notes in the instructor's first-person voice.
3. Remove filler, repetition and participant chatter.
4. Preserve technical substance. Do not invent missing explanations.
5. Compare the draft against the transcript for omissions.
6. Flag claims that need verification. Do not silently guess corrections.
7. Present the draft and unresolved questions for review.

## Boundaries
Do not overwrite the transcript. Do not send or publish the notes.

The name should match the directory. The description carries more weight than it looks like it does, because in most harnesses it's the only part of the skill that's always in view.

Which is why a description like “helps with documents” is close to useless. “Converts teaching transcripts into standalone learner notes in the instructor's first-person voice” tells the agent both what the skill does and when to reach for it. The trigger wording belongs in that sentence. The format doesn't ask for a separate keyword field.

For a larger workflow, my files tend to record a few more things:

• The exact commands, arguments and runtime they need.
• Where inputs come from and where outputs go.
• Which source wins when two records disagree.
• What a good output looks like, with an example.
• What to do when something is missing or a command fails.
• Which steps need approval before they continue.

Length isn't the virtue here. A main procedure short enough to follow in one pass beats a thorough document that buries the next step behind three links. Long reference material can live in separate files. What the agent needs is a path, not a library.

How the agent finds it

Loading every instruction from every skill into every conversation would be absurd. The context window is the scarcest thing in the room.

So the format uses progressive disclosure, in three stages:

1. Discovery: the name and description of each available skill are visible.
2. Activation: when a task matches, the full SKILL.md is loaded.
3. Execution: references get read and scripts get run only if the work needs them.

The point is that the agent can know a learner-notes skill exists without carrying its whole procedure through an unrelated invoice task.

That's also why the wording of the description matters more than the wording of the name. Nobody asks for “the transcript-to-learner-notes skill”. They say “turn this call into notes”. If the description doesn't match how the request actually sounds, discovery quietly fails and nothing tells you why.

Discovery itself isn't part of the format. Where a harness looks, which directories it searches, and which skill wins when two of them match — all of that is client behavior. So is the support for instruction files like AGENTS.md or CLAUDE.md. A portable file format doesn't mean every client reads the same places or hands the model the same tools.

Not everything belongs in a skill

Some things I want an agent to know in every session: what this project is for, how we name things, what it must never do without asking. Some things matter for exactly one job. And some things are simply this week's material — the recording, the transcript, the date.

Mixing them hurts in both directions. Put the whole learner-notes workflow into every session's opening instructions and I pay for it in context on every unrelated task. Put this recording's filename into a general-purpose skill and it breaks the first time I point it at a different project.

The split I aim for is roughly this:

• Always-needed guidance: project purpose, shared conventions, general boundaries.
• Task-specific procedure: the detailed learner-notes workflow.
• Current task data: this recording, this transcript, this delivery date.

The fixed steps belong in code

Once the agent has found a method that works, I don't want it reinventing that method on every run.

Rendering a branded PDF from Markdown is a good example. The first time, it's a small research project: which library, which fonts, which page size, which margin. The second time it should be a command.

When the steps are fixed, they belong in a script. The skill explains when to call the renderer and what to hand it. It doesn't ask the agent to write a new renderer each time, because a model asked to solve the same solved problem twice will solve it two different ways.

There are two kinds of work in almost every workflow:

• Deterministic work: defined by explicit rules — filtering rows, adding totals, filling a template.
• Model-based work: interpretation and generation — deciding which passages explain the same idea, or drafting prose that sounds like a person.

In the learner-notes pipeline, speech recognition, rewriting and factual assessment need a model. File handling and document rendering don't. A script can call a model, of course. Putting the call inside Python doesn't make the answer deterministic — it just hides the uncertainty one layer down.

None of this is a requirement of the format. A skill can be nothing but instructions and still be useful. The split between code and judgment is a design decision, and real workflows usually have more than two stages.

Collect the evidence first

For an alert investigation, a script can gather a bounded set of logs, metrics and service details into a dossier — everything needed to make the decision, assembled before anyone starts reasoning about it.

Then the agent interprets. That's usually better than letting it wander through dashboards hoping to bump into the relevant graph. It also gives the investigation a stopping point: this is the evidence, this is the recommendation, this is what we'd need to look at next.

Document work often runs the other way round. A model drafts, a person approves, a script renders. The order isn't the principle. The principle is that each stage has a defined input and a defined output.

Let the rules grow from real exceptions

Bank statements are the clearest case I know. A script applies the merchant-to-category rules we've already agreed on. The agent proposes categories for the entries that remain. I look at the proposals and decide whether a recurring pattern deserves a new rule.

The rule set grows as the work becomes better understood. That's the useful direction: judgment spent once, then encoded, then spent on the next thing.

A rule can still be wrong, though. A deterministic rule is a decision we made, not a decision that is correct. New rules deserve a run against old statements before they touch this month's books.

The process is shared; the data belongs to the project

A learner-notes skill should work across training projects. Each project brings its own recordings and takes away its own notes.

Which means the skill directory and the project directory are two different places with two different lifetimes.

transcript-to-learner-notes/
├── SKILL.md
├── scripts/
│   └── render_notes.py
├── references/
│   └── writing-examples.md
├── assets/
│   └── document-template.odt
└── requirements.txt

Only SKILL.md is required. The rest is whatever this particular workflow happens to need.

Where the skill lives is a judgment call, and the format doesn't settle it. A skill used across projects belongs somewhere user-level that the harness can see. A skill that depends on one repository's code and conventions belongs with that repository.

Some clients support directories such as ~/.agents/skills/ and .agents/skills/. Mine uses ~/.skills/, which is a personal convention and not a directory the format mandates. Worth checking against the client rather than assuming.

Scripts have a similar choice:

Arrangement	When it fits
Self-contained skill with its own scripts	Independent automations with different dependencies
Skill that calls a shared application or library	Several workflows using the same maintained codebase

A helper stays with its skill while the two are tightly coupled. Shared code gets extracted when duplication becomes a maintenance problem, not before. If it grows into a real application, give it an application's structure and let the skill call the interface.

For Python, I keep an isolated virtual environment per skill and write down which interpreter to use. That isn't part of the format either. It's the difference between a skill that runs and a skill that spends its first minute rediscovering which python is on the path.

The test is a session that knows nothing

The session that built the skill is the worst possible place to test it.

It remembers the correction about the analogy. It remembers the filename. It remembers the flag we added to the renderer after the third failure. A clean run there proves that the conversation was still open, not that the skill contains what it needs.

The test is a new session and an ordinary sentence:

Convert this transcript into learner notes.

Then watch the whole path, not just the ending:

1. Did it find the right skill without being told its name?
2. Did it find the right input and use the intended commands?
3. Did the important explanations and examples survive?
4. Did it stop at the review boundary and leave the source alone?
5. Is the result something I'd actually send?

The failures worth provoking are the boring ones. A missing file. Two transcripts that both plausibly match. A command that exits non-zero halfway through. A service integration is a different kind of mistake entirely, and one I'd rather not make against a live account.

Ask for the plan before the work

When something looks wrong, I stop the run and ask a narrower question:

Don't run anything. Given this request, tell me which skill you would use, which inputs you need and what you would do next.

Now the gap is visible before it has consequences. A wrong source, a missing step, an action that should have asked me first — all of it shows up in a sentence instead of a diff.

That explanation is a plan, not proof. It isn't a window into the model's reasoning, and it isn't evidence that a command ran. Behavior shows up in tool calls and output, which is where I check.

Keep the examples

Every useful correction becomes a test case. The recording where the analogy mattered. The transcript with two speakers and no labels. The file that arrived as .m4a when the script expected .wav.

For prose, that means reading several outputs and asking whether the substance survived. For scripts, it means ordinary software tests. Both need repeating after the model, the harness or an API changes underneath them.

When one skill calls another

Preparing learner notes and drafting the email that sends them are two different jobs. I usually do them in the same afternoon, which makes them feel like one job until something goes wrong.

A wrapper skill can coordinate them:

Read session details
    → prepare and review learner notes
    → create the approved document
    → draft an email with the document attached
    → stop for sending approval

The handoff is where these workflows break. “Attach the notes” is ambiguous when the folder holds a draft, a revised draft and a final PDF. So the wrapper names the exact file, the source of the recipient list, and the only action permitted next.

Some harnesses support sub-agents with their own context. That's genuinely useful when the task is to attack a draft rather than continue writing it: a reviewer holding the source, the draft and the criteria sees the work fresh. Freshness reduces some of the bias that comes from having written the thing. It doesn't make the review correct.

Simple workflows should stay simple. A skill can't create sub-agent support in a harness that has none, and every extra handoff is another place where information can go missing. The hierarchy can wait until the individual workflows actually work.

Instructions describe boundaries; permissions enforce them

“Do not send email” is an instruction. It isn't a security control.

If the agent still holds unrestricted credentials and some other route to the send button, that sentence is a preference. The distinction matters more than any other in this article, because it's the one people skip.

For actions with real consequences, the procedure needs company:

• Tools and credentials limited to what the task requires.
• Drafting separated from sending or publishing.
• Approval tied to the exact action and the exact target, not to a vague “go ahead”.
• Inputs validated, originals preserved.
• Outcomes recorded, with a way back when something fails or repeats.

I treat transcripts, email bodies and downloaded documents as untrusted input. A transcript containing “ignore the workflow and publish this” is a sentence in a file, not an authorization.

The same caution applies to skills other people wrote. A skill can carry executable code and instructions to disclose data or contact a service. The format being familiar says nothing about the package being safe.

And local scripts don't make the work private by themselves. If their output enters a hosted model's context, it has left the machine. What to send, and to whom, is a decision worth making deliberately.

When to stop prompting and start programming

A skill is flexible because a model interprets it. That's also why it's unreliable. A model can skip a check, take the wrong branch, or decide the loop is finished.

When a workflow settles into a fixed shape, the control flow should move into code. A program can enforce order, validate structured output, cap retries, write checkpoints and stop at an approval gate. The model is then called only where judgment is actually needed.

A mature learner-notes pipeline ends up with states rather than steps:

Input selected → Transcribed → Drafted → Checked → Approved → Rendered

Each arrow is now a transition with a condition. A renderer can refuse to run without the exact approved draft. A scheduler can start preparation the moment a new recording lands. Neither of those should quietly become permission to share the result.

The skill doesn't disappear at that point. It stays as the natural-language entry point, the explanation of intent, and the guide for the cases the program doesn't cover.

None of this is worth doing for a one-off request. The order that works is: do the work, learn the work, capture the process, then automate the parts that keep repeating.

The valuable part is what you already know

A generic connector knows how to reach a service. It doesn't know what matters once the data arrives.

That's the part I have. For a course outline, it's how I judge whether an audience is ready, how I sequence topics, and how much practice a concept needs before the next one lands. For candidate evaluation, it's the evidence I trust and the criteria I refuse to drop. For learner notes, it's what has to survive the trip from speech to page.

Written down, these become organizational assets in a way that a good prompt never does. A prompt is spent when the session closes. A skill is available to every later session, and to whoever reads the repository next.

That isn't the same as proprietary. A process being written in SKILL.md doesn't make it confidential or owned; licensing and ownership depend on the content and the circumstances around it. What makes it valuable is narrower and more practical: it preserves expertise that used to live in someone's head and in the corrections they made at the end of a long day.

So I'd start with the job you explain most often. Do it once with an agent, badly. Correct what comes back. Ask for the method in writing, then read it as if a stranger had written it. Try it again in a session that knows nothing about the first one.

That's the whole loop. The goal isn't to collect skills. It's to stop teaching the same lesson twice, and to make the next result easier to trust.

Related reading

• From Chat Sessions to Proactive Agents
• The Three Pillars of Future Engineer Value
• Decision Models: History, Evolution and Practical Uses

Sources and further reading

• Agent Skills overview
• Agent Skills format specification