Claude skills: what they are and how to build your own, plus the 49 we use

A Claude skill is a folder containing a SKILL.md file: a few header lines that say what it does and when to use it, followed by the instructions. Claude only keeps each skill’s header in view and loads the rest when your request matches, so you can have dozens without filling up the context. Here you’ll build one that reviews and publishes an article using a checklist, learn how to write the description so it triggers when it should, and see how we maintain the 49 skills our assistant uses every day.

Everything technical here was checked on October 16, 2026 against Anthropic’s official documentation and the open Agent Skills specification, and we’ve used it with Claude Code 2.1.283 on a VPS running Windows Server 2022.

What a skill is and what’s inside#

Anthropic introduced Agent Skills on October 16, 2025, and on December 18, 2025 it released them as an open standard (the specification lives at agentskills.io). That’s why the same format works in Claude Code, claude.ai, and the API, and other agents that adopt the standard can read it too.

This is the minimal structure:

revisar-articulo/
├── SKILL.md        # required: header + instructions
├── CHECKLIST.md    # optional: reference material
└── scripts/        # optional: code Claude runs

The header (YAML frontmatter) has two fields that always matter:

Claude Code also supports its own fields: argument-hint, disable-model-invocation, user-invocable, model, context: fork (run it in a subagent), paths, and others. They work in Claude Code, but the documentation warns that outside it (uploading to claude.ai or the API) only name, description, license, compatibility, metadata, and allowed-tools are accepted, and one extra field makes the upload fail. If you plan to share a skill, stick to those six.

How Claude loads a skill without filling your context#

The trick is called progressive disclosure: information comes in by levels, and only when it’s needed.

Desliza para ver la figura completa

According to the official documentation, level 1 costs about 100 tokens per skill and loads when the session starts. The body is recommended to stay under 5,000 tokens and 500 lines. Supporting files cost nothing until Claude reads them, and for a script, only what it prints enters the context, not its code.

Two Claude Code details worth knowing. You can launch a skill manually by typing /name at the start of your message. And, according to the documentation, if you edit a SKILL.md, Claude Code picks up the change in the open session; you only need to run /reload-skills if you create the .claude/skills/ folder after the session has already started.

Skill, CLAUDE.md, MCP, subagent, or command: which to use#

This is the most common question, because all five “give Claude instructions.” They differ in when they load and what they’re for:

The rule we follow comes almost word for word from the documentation: if Claude should always know it, it goes in CLAUDE.md; if it only needs it for a specific task, it’s a skill. And skills and MCP don’t compete: the MCP server gives Claude the email tools, and the correo-empresa skill explains which one to use for each request and how to reply.

One last nuance: an instruction in a skill is a request, not a guarantee. If something must always hold (blocking a dangerous command), the documentation recommends a hook.

Build your first skill step by step#

We’re going to build revisar-articulo: it reviews a blog article against the style guide, fixes what it can, checks that the site builds, and doesn’t publish without a yes. It’s a trimmed-down version of the process we use for this very blog.

1. Choose where it lives. Claude Code has three main locations:

   Scope	Path	Who sees it
   Personal	~/.claude/skills/revisar-articulo/SKILL.md	You, across all your projects
   Project	.claude/skills/revisar-articulo/SKILL.md	Anyone working in that repository
   Plugin	<plugin>/skills/revisar-articulo/SKILL.md	Anyone who installs the plugin; invoked as /plugin:revisar-articulo

   If two skills have the same name, the enterprise one wins, then personal, then project. For a process tied to a specific repository, project scope is better: it travels with the code.

2. Create the folder. On Windows with PowerShell, from the project root:

   New-Item -ItemType Directory -Force ".claude\skills\revisar-articulo"

   On macOS or Linux: mkdir -p .claude/skills/revisar-articulo. The folder name must match the name field.

3. Write the SKILL.md. Here’s the complete file, ready to copy:

   ---
   name: revisar-articulo
   description: Reviews a blog article (.mdx file) against the style guide and the publishing checklist, fixes what fails, checks that the site builds, and leaves it ready to publish. Use it when asked to review, go over, proofread, or publish a blog article or draft, or before calling an article finished.
   argument-hint: "[ruta-del-articulo.mdx]"
   allowed-tools: Read Grep Bash(npx astro *)
   ---
   
   # Review and publish an article
   
   Article: $ARGUMENTS (if you haven't been told which one, ask before starting).
   
   Copy this list into your response and check items off as you go:
   
   ```
   - [ ] 1. Read the article and the style guide
   - [ ] 2. Run the checklist
   - [ ] 3. Fix and rerun the checklist
   - [ ] 4. Build
   - [ ] 5. Ask for a yes and publish
   ```
   
   ## Steps
   
   1. **Read** the whole article and `contenido/guia-de-estilo.md`.
   2. **Run the checklist** in [CHECKLIST.md](CHECKLIST.md) item by item. Note each failure with its line.
   3. **Fix** anything that's about form (formatting, banned phrases, links, intro length). Anything about content (a figure without a source, a questionable fact) don't fix by making things up: mark it as pending. Go back to step 2 until there's nothing left you can fix.
   4. **Build** from the `web` folder with `npx astro build`. If it fails because of this article, fix it and repeat. If it fails because of another file, say so and don't touch it.
   5. **Publishing needs an explicit yes.** Summarize in three lines what you changed and what's still pending, and ask: "Shall I publish it?". Without a yes, don't change `draft: true` to `draft: false`.
   
   ## When you're done
   
   One sentence: which article, how many failures there were, how many are still pending, and whether it builds.
   
   <!-- aprendido:inicio -->
   ## Learned (overrides everything above)
   <!-- aprendido:fin -->

   Three choices here that aren’t decoration. $ARGUMENTS captures whatever you type after /revisar-articulo. allowed-tools pre-approves those tools for that turn only, without asking you for permission each time; it doesn’t restrict the others. And the checklist copied into the response, plus the “review, fix, repeat” loop, is the pattern Anthropic’s best practices guide recommends for multi-step tasks.

4. Add the supporting file. CHECKLIST.md, in the same folder. It’s only read in step 2, so it can grow at no cost:

   # Publishing checklist
   
   ## Frontmatter
   - [ ] `title` of 50 to 70 characters, with the keyword at the start if it sounds natural
   - [ ] `description` of 120 to 160 characters, not repeating the title
   - [ ] `category`, `tipo`, and `tags` filled in
   - [ ] Every figure in the text (price, limit, version) has its entry in `fuentes`, with a date checked
   
   ## Text
   - [ ] The first paragraph answers the search query in 2 or 3 sentences
   - [ ] No phrases banned by the guide ("in conclusion", "powerful", "crucial"...)
   - [ ] Paragraphs of 2 to 4 sentences; headings that say something
   - [ ] At least one original figure, and a table if something is compared
   
   ## Links, code, and data
   - [ ] Internal links with a trailing slash (`/que-es-mcp/`)
   - [ ] Code blocks with their language
   - [ ] No passwords, tokens, IPs, or personal email addresses

   Link to it from SKILL.md with a relative path and forward slashes (CHECKLIST.md, scripts/validar.py), even on Windows: the guide itself asks for this. And don’t chain a file that links to another that links to another: Claude may read only part of nested files.

5. Test it. Open a new Claude Code session in the project and type /: revisar-articulo should appear with its hint [ruta-del-articulo.mdx]. Then test it both ways: manually (/revisar-articulo src/content/articulos/que-es-mcp.mdx) and without naming it (“go over the MCP article before publishing it”). If the second one doesn’t trigger it, the problem is almost always the description.

We created this skill on our VPS and checked its format against the standard’s rules: a valid name that matches the folder, and a 317-character description. Watch out for one detail: argument-hint is specific to Claude Code. If you want to upload the skill to claude.ai, remove it.

The description decides whether the skill triggers#

Claude picks which skill to use by comparing your request with the descriptions. The body can be perfect, but if the description doesn’t say when to use it, it won’t load. The documentation asks for two things: what it does and when to use it, written in the third person and with the words the person asking would use.

Here’s a bad description, the kind you get when you write in a hurry:

description: Helps with email.

It doesn’t say which email, what actions, or what words people use to ask for it. This is the one from our correo-empresa skill (trimmed so we don’t publish addresses):

description: "Reads, searches, replies to, and sends the company's email (the contact inbox and the team's inboxes). Use it ALWAYS when the owner says 'the email', 'the emails', 'new emails', 'the contact email', what an email says, or asks to reply to or send an email."

It works for three reasons: it lists the verbs (read, search, reply, send), it captures the exact phrases Ferran uses to ask for it, and it leaves no room for doubt. When two skills overlap, we add the boundary inside the description. The one for stripe-cobros ends like this: “For earnings figures, use ganancias-gamzyhost instead.” That way, “how much have we made this month?” has a clear destination (earnings) and “why did this charge fail?” has another (Stripe).

Three rules we apply to all 49:

• Important stuff first. In Claude Code the listing truncates the description at 1,536 characters, and the open standard caps it at 1,024. Ours run around 200-400.
• The user’s words, not yours. If your team says “the host,” write “the host.”
• If it has side effects you don’t want by surprise, add disable-model-invocation: true: that way it only runs with /name, and its description doesn’t even take up context.

The “Learned” pattern: the skill corrects itself#

A skill written once goes stale within weeks. The fix we use in our assistant, Jarvis, is a section at the end of the skill (titled “Aprendido,” Spanish for “Learned,” in our files) where the agent itself records every correction we make. Of the 49 installed skills, 35 are ours and 14 are third-party (mostly design and animation); 19 of ours already have entries in their “Learned” section.

Desliza para ver la figura completa

Here’s how it works in practice. Every one of our skills ends with a block between two HTML comments, aprendido:inicio and aprendido:fin. When we correct Jarvis while it’s using a skill, the system adds a line inside with the date and the rule, and copies it into an APRENDIDO.md file in the same folder. The block’s heading makes the hierarchy clear: “overrides everything above.” This is a real excerpt from revisar-orden, the skill that keeps the VPS tidy (paths generalized):

<!-- aprendido:inicio -->
## Learned (the assistant has been correcting this on its own; overrides everything above)
- 2026-10-07: Also check %TEMP% and the bundle folders Remotion leaves behind when
  generating videos: they can pile up and fill drive C: to 99%. Clean them up
  along with the rest of the temp files.
- 2026-10-13: Also look for 0-byte files named after broken commands (leftovers
  from badly escaped bash); 57 were found today scattered across the projects folder.
<!-- aprendido:fin -->

You don’t need our system to copy this. Just add an instruction like this to your skill’s body:

If the user corrects you while you're using this skill, add a line at the end of the
"Learned" section with the date (YYYY-MM-DD) and the rule in one sentence, written
so it makes sense without knowing the conversation. Tell the user you did it.

That last sentence matters: the rule has to make sense without the conversation in front of you. Our skills have the occasional line that only made sense on the day it was written, and a rule nobody can understand is useless.

Common mistakes when building skills#

• A description with no “when.” Without it, the skill doesn’t trigger when it should. Include the phrases you’d use to ask for it.
• Two overlapping skills. Claude may load the wrong one. Separate their territory and write the boundary into both descriptions.
• Cramming everything into SKILL.md. Past 500 lines, move reference material into separate files and link them one level down, with no chains.
• Explaining to Claude what it already knows. The official guide puts it this way: assume Claude is smart and add only the context it doesn’t have (your paths, your steps, your exceptions).
• Invalid names. Capital letters, spaces, accented characters, or the word “claude” in name. Use lowercase and hyphens, same as the folder.
• Paths with backslashes. scripts\validar.py fails on Linux. Always use scripts/validar.py.
• Installing skills from just anyone. A skill can tell Claude to run code. Anthropic recommends using only your own or ones from trusted sources, and reviewing all their files first. We read the SKILL.md and scripts of each one before installing it.
• Expecting a skill to be a barrier. If something must never fail, it’s a hook or a permission, not a sentence in a skill.

Skills in claude.ai and the API#

The format is the same, but each surface is separate and they don’t sync with each other:

In the API, skills run without network access and can’t install packages; in Claude Code they have the same network access as any program on your machine. If you want to see well-built skills, Anthropic publishes examples and a template in its anthropics/skills repository, which you can add as a marketplace in Claude Code with /plugin marketplace add anthropics/skills.

What to do now#

1. Think of something you’ve explained to Claude three times this month. That’s your first skill.
2. Copy revisar-articulo, replace the steps with yours, and rewrite the description in your own words.
3. Add the “Learned” section from day one and review it every few weeks: whatever keeps coming up, move it into the body.

If you’re not using Claude Code yet, start with the Claude Code guide. For what it should always know, see how to write a good CLAUDE.md, and to see how skills fit into a full assistant, read how we built our own AI assistant and the real-world AI agent examples we use at GamzyHost.