🧩 Skills: teaching a process

A “skill” is a text file that teaches the agent to do a task you repeat — like a procedure manual a company gives to a new employee.

Without a skill, you explain the same process every time. With one, you write it once and the agent follows it on its own afterward.

POP (standard operating procedure), reuse, persistent instruction.

Each skill lives in its own named folder, containing at least one file SKILL.md and, optionally, reference subfolders and scripts.

Understanding the folder structure is the first step toward creating (module 3.6) and organizing your own.

Skill folder, root file, optional subfolders.

Front matter is a short block at the top of the file, between two lines ---, with pairs like name: e description: — it's the "label" the agent reads first, before opening the rest.

It's this label that determines whether the skill is called or ignored—the central topic of module 3.4.

Front matter, metadata, structured header.

Extra documents (inside a subfolder, for example references/) with the fine details — large tables, lists of errors, long examples — that the agent opens only if the task requires it.

Keeping SKILL.md concise and moving details to a reference is what makes each skill cheaper to use — the topic of module 3.2.

Reference, details on demand, deep archive.

A skill can package ready-to-use scripts (Python, Node, shell) that the agent runs instead of writing code from scratch every time.

An embedded script is faster and more reliable than “reinventing” the logic on every call.

Embedded script, deterministic execution, WAT — tools.

A guided walkthrough of a real installed skill — front matter, body, reference — to see how the parts work together.

Seeing the complete example wraps up the theory before you build your own in module 3.6.

Case study, applied anatomy.

Context is everything the agent "has in its head" during a conversation — your message, the history, the open files. It's limited, and the fuller it gets, the more each response costs and the slower it becomes.

Progressive loading exists specifically to avoid filling this space with skills that aren’t being used.

Context, memory window, cost per token.

One token is a small piece of text (near a word) — the unit AI uses to "read" and charge for. In Level 1, only the name and description of each skill are always available, costing about 100 tokens each.

It's this inexpensive level that lets the agent “know the skill exists” without loading all of it.

Token, Level 1, always resident.

When the trigger (module 3.4) fires, the agent opens the entire SKILL.md — the complete step-by-step guide — and only then does that higher cost come into play.

Understanding this “only when needed” behavior explains why having lots of skills installed doesn’t slow everything down.

Level 2, loaded on demand.

The last level: reference files or scripts that the agent opens only if it needs that specific detail while working on the task.

This is what lets a skill have extensive documentation without costing much most of the times it’s used.

Level 3, conditional reading.

20 skills × ~100 Level 1 tokens comes to around 2 thousand fixed tokens — little compared with a context window that can handle hundreds of thousands.

This concrete number dispels the fear of "having too many skills installed."

Aggregate cost, scaling without pain.

Move large tables, error lists, and long examples to references, keeping SKILL.md as a short “executive summary.”

It's the guideline you apply when writing your own skill in module 3.6.

Lean body, in-depth reference, separation of responsibilities.

A short, unique name, plus the "trigger" phrase that says when that skill should kick in.

This is the first piece that gets read (Level 1)—if it’s weak, the skill is never called.

Name, trigger, identification.

A sentence that says exactly what the skill delivers when it’s done — “generates a CSV report,” not “helps with data.”

A vague objective leads to vague execution—clarity here prevents rework.

Objective, success criteria.

The numbered sequence of actions the agent should follow — the heart of the skill, equivalent to the “workflow” in the WAT framework (Trail 1).

It's this list that ensures repeatability—the same task produces the same result every time the skill is called.

Step by step, repeatability, workflow.

The list of extra files (Level 3, module 3.2) that the skill can consult when the step-by-step instructions aren’t enough.

Without this declared reference, the agent doesn’t know the detail is there to consult.

Declared reference, reading pointer.

Explicit restrictions—what the skill must never do without confirmation, echoing the safety rules from Track 0.6.

A written rule prevents the agent from “improvising” beyond what you authorized.

Explicit rule, limit on autonomy.

A space set aside to note what went wrong and adjust the steps—the skill isn't born perfect; it gets refined.

Prepares you for module 3.7, where this continuous improvement becomes a regular practice.

Improvement cycle, iterative refinement.

The agent compares your request with the descriptions (Level 1) of all available skills and chooses the best fit — like a book’s subject index.

Understanding how these work together explains why the right skill sometimes doesn’t activate.

Intent matching, description index.

A good description says “when to use” (trigger) and “what it does” (result), using words someone would actually type — not internal jargon.

It's the difference between a skill that triggers on its own and one that gets forgotten.

Trigger + result, in the user’s language.

Generic descriptions like “helps with documents” mean the skill is never selected because it doesn't stand out from anything else.

Recognizing this error is the first step toward fixing skills that “exist but never trigger.”

Generic description, ambiguity.

Two skills with similar descriptions can confuse the agent about which one to choose—a sign that one of them needs a more specific trigger.

Avoids rework when you already have several skills installed (module 3.5).

Overlapping triggers, disambiguation.

Ask for the same task in different ways (“make a summary,” “summarize this,” “TL;DR this”) and see whether the skill triggers for all of them.

This is the real test of a description’s quality—it’s not enough for it to work with the first phrase you wrote.

Variation test, trigger robustness.

A skill can be called with an explicit command (like /nome-da-skill) or simply by describing what you want in natural language.

Knowing about both options helps you choose which one to use when — a command when you want certainty, natural language when you want fluidity.

Explicit command, triggered by natural language.

A folder .claude/skills/ inside the project itself, it stores skills that exist only there—specific to that repository.

Project skills can travel with the code (versioned), so the whole team inherits the same process.

Project scope, versioned alongside the code.

A folder in your home folder (~ = "home") stores skills available in any project you open, on any of your computers.

This is where the personal processes you use all the time live, no matter which project you’re working on.

Global scope, personal folder (home).

Simple rule: if the process only makes sense within this project (e.g., deploying this specific app), it belongs in the project; if it’s something you do anywhere (e.g., generating a summary), it belongs globally.

Putting it in the wrong place is one of the most common mistakes people make when learning skills—it makes it harder to find later.

Scope criterion, specificity vs. generality.

When a project skill and a global skill have the same name/purpose, the project skill usually takes precedence in that context — it's more specific.

Avoids surprises when you expect global behavior but the project overrides it.

Scope precedence, overlap.

How the folder .claude/skills/ lives inside the repository; committing it means every colleague who clones the project automatically gets the same skills.

Turns “the way I do it” into “the way the team does it” without a single meeting.

Versioned skill, team-wide standardization.

Over time, your global folder accumulates skills—it’s worth reviewing it occasionally, deleting the ones you no longer use, and refining unclear descriptions.

Sets the stage for module 3.7, about keeping skills sharp over time.

Maintenance, periodic cleanup.

Before writing any skill, choose a task you already repeat manually today—it’s the best candidate to turn into a skill.

A skill that solves a real problem is easier to test and see the benefit of.

Skill candidate, repetitive task.

A ready-to-use block of commands that creates the skill’s folder and starter file, with the front matter already filled in.

This is literally the first practical step—pasting and running it takes away the “blank page anxiety.”

Initial structure, base template.

Fill in the body of SKILL.md using the 6-step framework from module 3.3, with the task you chose in topic 1.

This is where the theory becomes a real, testable file.

Practical application of the framework.

Open a new conversation and describe the task in natural language, checking whether the new skill is actually called.

This is the exercise’s “how to verify”—without this test, you won’t know whether the skill works.

Trigger check, manual test.

A checklist: too vague a description? Folder in the wrong place? Name duplicated by another skill?

Frustration disappears when you have a list of suspects to check instead of guessing.

Diagnosis, checklist.

With the skill working, the natural next step is to use it for real a few times and observe where it fails—module 3.7 opening.

Wraps up this track’s practical cycle before moving on to ongoing maintenance.

Real-world use, observation, transition.

Every skill starts out imperfect: you call it, watch where it gets stuck, revise the text, and call it again. The unvarnished truth: it usually only gets good around the tenth run.

Without this expectation, you give up too soon, thinking the first version should work perfectly.

Iterative cycle, realistic expectations.

Keep file names, sections, and identifiers stable within the skill, even when the content changes — this avoids breaking cross-references.

A skill whose structure changes all the time is hard to maintain and debug.

Stable ID, cross-reference.

When you already know that a reference (Level 3) will almost always be needed, you can instruct the skill to load it right away, without waiting for the agent to "discover" it needs it.

Saves a back-and-forth when Level 3 is virtually guaranteed.

Preloading, anticipating needs.

One subagent is a copy of the agent opened to handle an isolated part of the task, returning only a summary—this way, the skill can delegate heavy tasks without filling up the main context.

Complex skills (e.g., research across many files) get lighter and faster with this trick.

Sub-agent, context isolation.

Looking at it through the WAT framework from Track 1: the SKILL.md is the “workflow” (the step-by-step process), and the scripts/references are the “tools” (the tools the workflow uses).

Ties together everything you learned in both tracks—skills aren’t an isolated concept; they’re WAT applied to a specific process.

Workflow/tools mapping, track integration.

With processes taught through a skill, the next challenge is to run these automations outside your laptop—the subject of Track 4, Deployment.

Wraps up Track 3 with a clear next step in the course.

Track transition.