A close view of honeycomb in a wooden frame. Bees work on the cells. Some cells hold honey and some are capped with wax.

A skill is your expertise, saved for the agent.

You now have an agent on your machine, but you keep teaching it the same things every session. Skills are how you stop. This is the densest part of the curriculum and the one to spend the most time on: a skill is a folder, and that folder is how you encode your expertise so it compounds.

Bees build the same six-sided cell again and again, then fill it.

Tanush Jagdish · Part 3 of 6 · 13 min read

You now have an agent on your machine. It reads your files, runs code, and searches the web. Yet every time you sit down with it, you teach it the same things again: no em dashes, three takeaways not five, action items by person, small font, no borders. You said all of that yesterday, and you will say it again tomorrow. That repetition is the reason skills exist: if you say something twice, it belongs in a skill.

Once you start working with agents, the options multiply quickly, and skills are how you focus. In my view, they are the right abstraction and the base infrastructure for how people will work with agents.

#1What a skill is

Set the jargon aside: a skill is a folder. It contains a file called SKILL.md that describes what the skill does, usually alongside a real example of good output. Think of it as a context pack.

What are skills?Instructions for how the LLM uses its tools
You

ask for something

LLM

thinks · plans · decides

Skills

Weekly Research

SKILL.md

“read these sources, filter”

Email Drafter

SKILL.md

“use my tone, check CRM”

Meeting Prep

SKILL.md

“pull notes, check calendar”

Tools

Read / Write

files, folders, docs

Run Code

terminal, scripts, APIs

Search

web, databases, email

A skill is a set of instructions the LLM reads before acting. Without skills, the LLM guesses. With skills, it follows your playbook every time.

What skills are: instructions that tell the LLM how to use its tools. An LLM reads your skills, and your skills call the tools (read and write files, run code, search).

If you have used AI for a while, you remember prompt libraries: a prompt for a good email summary, a prompt for a meeting recap. A skill is the next step. Instead of one long string of text, it is a whole folder: the prompt, the scripts it calls, and an example of what good looks like. It puts your expertise in a form you can move from one tool, or one person, to another.

Open the folder and there is not much inside. SKILL.md is the core: what the skill does, when the agent should use it, and how to carry it out, step by step. A references folder holds the durable material: a template so the output is consistent, and one or two examples so the agent knows your quality bar. A scripts folder holds any automation, such as the Python that converts your slides to PDF.

Anatomy of a skillIt’s a folder
skills/
weekly-research/
SKILL.md← trigger + instructions
references/← domain knowledge
sources.md
template.md
scripts/← automation
fetch-data.py
SKILL.md
The brain: what the skill does, when to trigger, how to execute.
references/
Domain knowledge: approved sources and the output format to follow.
scripts/
Automation: deterministic code the agent runs instead of improvising.

Nothing exotic, just a folder Claude decides to load. SKILL.md is the brain; references and scripts are the muscle memory it reads every time.

The folder tree: skills/weekly-research/ contains SKILL.md (trigger and instructions), references/ (domain knowledge), and scripts/ (automation). A legend below the tree says what each of the three parts does.

In Claude Code, skills live in a hidden folder called .claude (on a Mac, Command-Shift-Period shows hidden folders). It is simply a folder Claude has been told to check every time. As of September 2026, the Claude apps keep skills in your account instead: you manage them under Customize, then Skills, where you can upload a skill folder as a ZIP file. Every Claude plan can use skills. Skills in your account work in chat and in Cowork, and Claude Code loads them when you sign in with the same account. Cowork does not read Claude Code’s skills folder on your machine, so a skill you built in Claude Code reaches the apps only after you add it to your account.

One mechanism makes the whole thing work. When your agent starts, it does not read every skill in full. It reads only the name and one-line description of each skill, so it knows what every skill in the folder is for before you ask. As soon as you mention something notes-related, it knows which skill applies. That is why the description matters so much: it is the matcher. Your agent reads it, decides whether the skill fits your request, and only then loads the whole folder. Most of the time the model picks the right skill on its own, and you can always force it by naming the skill.

One distinction saves a lot of confusion: keep the skill and the knowledge base separate. Think about a person. A skill is the set of steps you follow to do the work: scan these 20 sources, check the cross-links, compile, synthesize, and write the report. It does not need your broader context. A knowledge base is the context of the person following those steps. One is the how; the other is the who and the what for. Separating them lets you hand a skill to a teammate without handing over your whole working life, which matters as soon as you start sharing. This line is a useful convention rather than a hard rule, since both are context underneath. You also do not need a skill for the internet: Claude already has web search built in. You need extra tools only to reach private sources such as your Gmail or your databases.

#2Build one on day one, but do the work first

This is the most important idea in this part, and it is the opposite of what most people do: do not start by trying to make a skill. If you sit down and say “make me a skill that writes my briefings,” you get the generic answer an LLM gives the first time you ask anything. You do not yet know what the agent needs to write a great briefing. Instead, do the real work first, with the agent, exactly as you would want the skill to do it. Once the work is done, turn the process into a repeatable skill. A process is hard to describe in the abstract; usually you have to do the work, going back and forth, to discover it.

Build your first skillZero → reusable automation

Three steps, in order. Do the real work first; only then codify it; then prove it holds on a second task.

1

Do the task live

Pick a real workflow you do repeatedly. Do it with your agent. Let it fumble. Watch where it struggles; those gaps become your skill’s instructions.

2

Ask the agent to package it

Say: “Turn what we just did into a reusable skill.” The agent creates the folder, writes the SKILL.md, and organizes the references.

3

Test on a second task

Run the skill on different input. What breaks reveals what’s missing. Fix the SKILL.md, add edge cases, refine the template.

Skills are the vehicle for learning. Building one teaches folder structure, context management, prompt engineering, and verification, all at once.

Build your first skill in three steps: do the task live, ask the agent to package it, and test it on a second task.

In practice, that means three steps. First, do a real task with the agent. Pick something you do every week, such as a budget model, a research synthesis, or a benchmarking analysis, and do it live, start to finish, with real data, until you have an output. Give feedback exactly as you would to a sharp colleague (no big fonts, no borders, three takeaways not five, no em dashes) and iterate. Second, once the output is good, package it: “Take all the feedback I gave you in this chat and turn it into a skill.” Waiting until the end matters. By then the chat holds every correction you made, and those are the corrections that would come up again tomorrow. If you give ten points of feedback today, you would give the same ten tomorrow, and the skill can absorb them all at once. Third, test it on a second real task: new input, same skill. If the output holds, you have a skill; if not, iterate. Most people need one or two rounds. Get the output you want first and make the skill second, because without the back-and-forth, you do not know what feedback to capture.

We did not always teach it this way. One consultant in our pilot spent three sessions on concepts: thinking modes, prompt structure, and context management. All of it was useful, but by his own account the sessions felt incremental. In session four, he built a skill that simulated feedback from his senior partner, ran it on a real model, and watched the output improve with each cycle. That was the session where it clicked, and his feedback was blunt:

“Bring the game changers earlier. Session 1 should feel like session 4.”

a management consultant in the pilot cohort

That feedback reshaped the curriculum. You now build on day one, and the concepts come along with the build, because one build teaches four things at once: folder architecture (where the skill lives), context management (how to write instructions the agent follows), prompt engineering (how to make the output good), and verification (how to test that it works).

A few mechanics make this easier. Use the skill-creator skill: both Claude and Codex offer a skill whose job is making good skills, with best practices built in, including progressive disclosure of context. Ask your agent to use it by name; few people write a skill entirely by hand. If you already have a template, you have half a skill: a template is a skill for humans, so hand it to the agent and ask it to turn the template into a skill. Keep skills small. Aim for the most signal in the least text; bloated skills make your agent worse, not better. Finally, decide what done looks like before you build, or you will end up making parts of a car without ever having a car to drive.

#3The enrichment loop: every correction compounds

If you take one thing from this part, take the instruction I repeat most. At the end of a chat, say: “Take everything we learned in this chat and improve our skill, so next time I do not have to tell you these things.”

The Skill Enrichment LoopEvery correction compounds
01

Use

Run the skill on a real task. The first pass gets you most of the way, not all of it.

02

Iterate

Give feedback exactly as you would to a person. “No borders. Smaller font. Three takeaways.”

03

Enrich

“Fold what we just learned back into the skill.” The correction goes to live, not to die.

↻ back to Use, one rung higher

You never teach the same lesson twice. Each pass through the loop the skill handles more on its own, and you stop doing the work and start coaching it.

The skill enrichment loop: use the skill, iterate with feedback, fold the lessons back in, and start the next run one step higher.

Here is how it plays out. On its first run, a new skill might get you halfway. You work with it, give feedback, and at the end ask it to improve the skill. Each later run gets further. You are aiming for a skill that does nearly all of the work while you nudge. In our experience, it takes four or five cycles for a skill to become consistently good.

How you give the feedback matters. I never edit a skill directly. I only talk to Claude, and I do not even tell it what to change. Instead, I give feedback on one specific example and then say: “Go through what we just did, and tell me how you would update the skill so these problems do not happen next time.” Show, do not tell; AI responds to the same approach people do. Specific feedback that the model then generalizes works far better than asking it to make the skill “very good” at something, which only produces text that says “make it very good.” That is the difference between a skill that ends up with a real instruction (“use a cycle diagram, not a bar chart, for this kind of graphic”) and one that fills up with platitudes.

Stop losing what you learn to dead chats. Think about how many AI conversations you have had where the feedback you gave vanished when the chat ended. If you say something once, it should be captured in a skill, reused, and refined over time. Every correction should be packaged into short-term memory or a long-term skill, and pruned regularly. That is what the skill abstraction gives you: a cure for babysitting, where you ask the model to change one thing and watch it change fifteen.

Set your expectations honestly: this compounds over a long horizon. My slides skill has been through well over a year of iteration and is still improving. You are compressing months of practice into a few weeks, so do not give up if the first two runs are weak. Patience pays off because of the bitter lesson: compute and model capability keep improving. Set up your data and your skills so that when models get better and compute gets cheaper, your agents get better with them. To get there, make your skills very good. However agents change, skills are how yours keep improving.

#4Your knowledge is the edge

Anyone can learn the tools in this curriculum. What no one else has is your expertise, and skills are how you encode it. Enrich your skills with your specific knowledge over time, and keep long-term memory across sessions so context builds instead of resetting. Think of it the way you would build an organization. You have a way you like presentations done, with titles and page numbers formatted a certain way. Encode it once in a skill. Then when a teammate’s agent does the work, they say “use this skill to make the presentation,” and the output comes back nearly finished.

Pick your weaponChoose enforcement by reversibility × frequency
Reversible → easy to undoIrreversible → money, data, reputation
Top-leftRare · Reversible

Just prompt well

A strong prompt is enough. The model may slip, but a do-over costs nothing and nobody gets hurt.

Examples: Drafting a Slack message, brainstorming an outline, quick text edits.

Top-rightRare · Irreversible

Reviewer sub-agent

Volume is too low to justify infrastructure; stakes are too high to ship blind. Fresh reviewer before you hit send.

Examples: A one-shot investor memo, a year-end board summary, a client-facing proposal.

Bottom-leftFrequent · Reversible

Skill + sanity validator

Build once, run many. A strong skill picks up reliably; the validator catches drift over time when pass-rate slips.

Examples: Daily research summaries, triaging inbound leads, standardized report generation.

Bottom-rightFrequent · Irreversible

Hard hook gate

Mistakes compound quickly here and are expensive to walk back. Build the gate. Do not rely on anything the model can talk its way around.

Examples: Writing to prod CRM, sending customer email, making payments, deploying code.

Two questions pick the mechanism. Map the task to one of four boxes: the recommendation follows.

Two questions choose how to enforce a task: how often it runs, and whether a mistake can be undone. Rare and reversible work needs a good prompt; rare and irreversible work needs a reviewer sub-agent; frequent and reversible work needs a skill with a validator; frequent and irreversible work needs a hook gate.

So pick a real recurring workflow, not a toy. People in the program have built an HR-policy extraction skill that synthesized more than 50 Russian-language documents; a project-setup skill that turns a messy data dump into a structured project folder and a plain-language briefing; a notes-filing skill that takes photos of handwritten notes, reads and classifies them, and files them as PDFs that keep their handwritten character; and a budget-allocation skill built by a data analyst who, once it worked, opened 22 sessions in a single day and ran agents in parallel.

Do not reach for a skill for everything, though. Start from the problem you need to solve today, not from the brain you want to build. If you need to make a great sales deck repeatedly, make a skill; memory does not help much there. If you want a useful to-do reminder every day, a skill will not help, because that is a context and memory problem. A great sales deck eventually needs both (the skill holds the design template, and memory holds the last four meetings with the client), but early on, the skill is almost always the fastest way to get the job done. Skills are the easiest place to start, and their impact is outsized.

One principle recurs once you build real skills: do not make the agent recreate the human artifact step by step. Use the model where it is strong. My slides skill is the origin story. I gave up on getting good PowerPoint files out of the model and asked for a PDF that looked right, however it got there. It reached for HTML, because HTML and CSS are formats it knows well and they let it control every pixel. Then I folded the PDF conversion into the same skill, and it went from idea to slide in one step. This works because models have seen far more web code than PowerPoint internals, so they lay out a slide well in HTML and poorly in a raw slide file. Spreadsheets follow the same logic: the problem is the analysis, not the Excel file. Excel is a means to an end, and the model is often better at writing Python. An agent does not have to do a task the way people always have. Use the model for what it does well instead of patching around what it does badly.

#5Keep your skills sharp: curation and surgery

A folder of skills needs upkeep; left alone, it decays. Your first lever is tuning the trigger. Because the description is what the agent matches against, give it examples of when to fire: “Always use the weekly-research skill when someone asks what happened over the last week, even if they phrase it as what happened yesterday.” Examples make sure the skill gets picked up.

Make your skill impossible to ignoreThe description is the matcher

Adherence starts with selection. Claude matches the user’s intent against each skill’s description field. Weak descriptions get skipped; strong ones get picked up and loaded. This is the cheapest intervention in the stack.

Beforeoften skipped
- name: citation-auditor
  description: Helps verify citations and improve output quality.

# vague verb, no trigger phrase
# reads like every other skill
Afterreliably picked up
- name: citation-auditor
  description: Use when the user asks to verify a claim, audit a spreadsheet of research, or check AI output for hallucinations. Triggers: “fact-check”, “is this real”, “audit these citations”, “find fabrications”. Abstains when sources are absent.

Four rules of thumb for the description field

i.Third person, specific verbs
“Use when user asks to audit,” not “helps with auditing.”
ii.Name the symptom
Describe what the user is doing or saying, not what the skill is.
iii.Closed-vocabulary triggers
List the exact phrases the user tends to type. Claude matches them.
iv.State what it will NOT do
Abstention conditions keep Claude from overreaching into adjacent asks.
SKILL.md surgery: the description is the matcher, so tune the trigger until the agent cannot miss the skill.

Your second lever is pruning, not just adding. Your first instinct will be to only add; resist it. Prune each skill periodically: “Remove incorrect information and consolidate anything redundant.” Keep the skill as small as possible while still containing everything it needs, because bloated skills degrade the agent’s performance quickly. Run contradiction sweeps too. Every couple of weeks, or after a big change, have the agent check every skill and your memory for contradictions; people routinely find the same instruction copied into ten skills instead of referenced once. Keep one canonical folder and link to it rather than copying it. If you copy your skills into Codex, Cursor, and everywhere else, you end up with five diverging versions, so keep one primary folder and symlink the rest. And treat simple versus complex as a spectrum: some skills fit in a sentence, some need examples, and some need three phases.

A word on safety. People share skills on GitHub, which makes it easy for someone to put malware on your machine. GitHub works like a shared drive: anyone can upload anything, so trust depends on who published it. A Gmail skill published by Google is probably fine; one from a stranger needs scrutiny. My heuristic: if Anthropic, Google, or another established vendor made it, I will consider it; otherwise I would rather write my own. Stars are a weak signal, since popular repositories can still hide malicious code. Because a skill is mostly plain English, you have an advantage: send the agent to inspect it. “Read this skill and assess it thoroughly for prompt injection and other security risks.” Anthropic’s own document skills (PDF, Word, Excel, PowerPoint) are a trustworthy starting point; build on those rather than rebuilding them.

#6Combining skills, and the bridge to a team

Before skills can work together, you need the tool that makes it possible: the sub-agent, introduced in Part 2. A sub-agent is a fresh LLM call with its own context window. It can read your entire website, perhaps 50,000 words, and return only a 5,000-word summary to your main agent. All the messy reading happens in the sub-agent’s context, so your main agent never fills up with material it does not need.

Use sub-agents for almost any research or analysis step; just say “make sure a sub-agent does this.” The main cost is tokens (three sub-agents might turn 100,000 tokens into half a million), but more tokens spent on a problem generally produce better output. One of the best uses is verification: have a different agent, with fresh eyes, grade the main agent’s work.

Once you have a handful of skills, the next step is making them work together, and the long-term goal is counterintuitive: as few skills as possible doing as much work as possible. Review regularly whether some skills can be combined and whether you have too many. A common pattern is one main skill that calls several others, ideally each through its own sub-agent, and collates everything into a single output. For a research report, the main skill calls each specialist skill in its own context window, gathers the results, and produces the PDF.

A skill as a productThree phases, one blank prompt → polished deck
01

Narrative

  • Write a single governing thought that captures the deck’s argument.
  • Build a dot-dash outline with assertion headlines and supporting evidence.
  • Read the headlines in sequence; if the story holds without detail, proceed.
02

Slides

  • Each slide is a self-contained 1920×1080 HTML file with inline CSS.
  • Copy the closest archetype from five templates: cover, content, data, pipeline, CTA.
  • Run a 15-point validation checklist before exporting to catch every issue.
03

PDF

  • Puppeteer renders each slide at 2× retina scale with screen-mode CSS preserved.
  • Slides merge via pdf-lib into one combined deck or individual page files.
  • One command: point at the directory, get a print-ready PDF back.
Customizable levers: swap without touching the skill’s logic
Narrative
Arc
SCR
Slides
Accent
#426d7a
Display font
Inter
Body font
Inter
PDF
Scale
2× retina

A mature skill is one main skill calling several others, ideally each through a sub-agent, collating everything into a single output. You change the levers; the pipeline does the work.

A finished skill as a product workflow: the /slides pipeline runs in three phases, from narrative to polished deck.

Here is a worked example. A site-grading skill for real estate rated locations on seven criteria, including natural-gas proximity, fiber, tax abatements, community sentiment, nearby data centers, and water. We built each criterion as a swappable stub, starting with web search and replacing it with a custom domain skill later, one criterion at a time. Its live run spawned seven sub-agents, one per criterion. To upgrade a criterion, we asked Claude to walk through how it currently handled it and then swapped in a better skill. For community sentiment, we reused an existing Reddit-research skill rather than building a new one. Knowing when to split one skill into two is the mirror image. Start with a single PowerPoint skill; if the visuals are what you keep fighting, pull diagrams into their own skill, because diagrams are complex and domain-specific in their own right. Build skills as a set, not as one monster skill. A consulting workflow might combine a project-setup skill, separate analysis skills, and a cleanup skill, because it is too much for one. You learn to build one good skill, then several, and then how to combine them into an agent.

Everything you build here is portable, because a skill is just a folder. You can keep it in Google Drive, Dropbox, or GitHub, send it to a teammate, and they can drop it into their own agent. As of September 2026, Claude’s Team and Enterprise plans also let you share a skill inside the app with specific colleagues, or publish it to the whole organization. Later updates reach everyone who uses the skill. That portability points toward the later parts. Once your skills can move, your team can share them: one shared repository where an improvement you make today reaches everyone tomorrow. That is the path to the team and institutional brain in Part 6. Long-term memory, which lets context build instead of resetting and sits behind every enrichment cycle, is the personal brain in Part 4, which comes next.

The research behind this part.

Continue with the next part.

Want to go faster on your real work?

Coaching is the same method with someone beside you. It is by referral or invitation, and we are at capacity. We write back as capacity opens.