How to create a Claude Code skill: two files of ten lines

For months I have been repeating the same instructions to Claude. Today I saved them once and stopped typing them.

In the video (in Spanish) we build two skills in under ten minutes. Both files are in the video repo. If you want the theory of what a skill is and how it differs from an agent, I covered it in 5 things you should know about AI Skills. I will not repeat it here: this one is hands-on.

What a skill is

A folder with one file: SKILL.md. The top has a name and a description; below it, plain-text instructions.

The description is what matters. Claude reads it to decide when to use the skill. You can also call it yourself with /name.

It lives in one of two places:

~/.claude/skills/<name>/SKILL.md: yours, for all your projects.
.claude/skills/<name>/SKILL.md: inside the repo, shared with the whole team.

Mine are written in Spanish because that is how I talk to Claude, so the SKILL.md files below stay in Spanish. Write yours in whatever language you use.

Skill 1: hackernews

I wanted to ask what is happening on Hacker News without opening the browser. This is the full file:

---
name: hackernews
description: Busca lo que está sonando en Hacker News. Úsala cuando pida noticias de tech, qué hay en HN o temas para un video.
---

Busca las historias de portada en `https://hn.algolia.com/api/v1/search?tags=front_page` con curl.
Si te doy un tema, usa `https://hn.algolia.com/api/v1/search?query=<tema>&tags=story`.

Dame las 5 más interesantes: título, puntos y link. Una línea por noticia, en español, sin relleno.

In English: fetch the front page with curl; if I give a topic, use the search URL; give me the 5 most interesting, one line each with title, points and link, in Spanish, no filler.

Nothing strange. It is how you would explain it to a person: where to look, what to do if I give a topic, and how I want the answer.

To test it I typed “¿qué hay hoy en Hacker News?” (what is on Hacker News today?), then “busca en HN algo de Rust” (search HN for something about Rust).

I never told it to use the skill. It read the description and used it on its own. That is why the sentence “Úsala cuando pida noticias de tech, qué hay en HN…” (use it when I ask for tech news, what is on HN…) is not decoration: it is the trigger.

Skill 2: mensaje-commit

I do not like writing commit messages. When I am in a hurry they end up as “fix” or “cambios”, and six months later they are useless. The file:

---
name: mensaje-commit
description: Escribe el mensaje de commit de lo que tengo en staged. Úsala cuando diga commit o pregunte qué pongo en el commit.
---

Mira `git diff --staged`. Si no hay nada, dímelo y para.
Mira mis últimos commits con `git log --oneline -10` y copia mi estilo.
Una línea corta; añade cuerpo solo si el cambio no se entiende solo.

Enséñame el mensaje antes de hacer el commit.

Two lines matter.

The git log one. Instead of explaining my style, I tell it to copy it from my commits. My style is already written in the history; describing it by hand would be worse and would go stale.

The last one. It shows me the message before committing. A skill can do things, but I decide when.

I tried it both ways: with /mensaje-commit and by asking “¿qué pongo en el commit?” (what do I put in the commit?).

Install them

Copy each folder to ~/.claude/skills/, or to .claude/skills/ inside your repo if you want the team to share them:

mkdir -p ~/.claude/skills/hackernews ~/.claude/skills/mensaje-commit
cp hackernews/SKILL.md ~/.claude/skills/hackernews/
cp mensaje-commit/SKILL.md ~/.claude/skills/mensaje-commit/

Three lessons

A vague description does not say when. “Helps with git” does not tell Claude at what moment to use the skill. Say when, in the words you use: “when I say commit”, “when I ask what to put in the commit”.

The shorter, the better it follows it. Mine are about ten lines. If you struggle to summarize yours, something is probably extra.

One skill, one task. If a skill does two things, they are two skills.

What I take from it

Two files of about ten lines each. Think about what you repeat to Claude every week: that is your next skill.

Tell me in the video comments which one you will build first, or share yours if you already have it.