🎯 Choose a small, real-world case
Everyone’s first skill should be boring and useful, not ambitious. A convention you repeat all the time and hate repeating. The perfect example: the commit message pattern on your team. It’s concrete, has clear rules, and you’ll notice right away if it worked.
✗ Bad launch cases
- ✗"A skill that handles the entire deploy" — too big
- ✗"A generic best practices skill" — vague, doesn't trigger
- ✗Something you can't test in 1 minute
✓ Good first-time use cases
- ✓Commit convention (Conventional Commits)
- ✓Project file/branch naming conventions
- ✓Response tone in Brazilian Portuguese
💡 Let’s build this
Our case: a skill conventional-commits that makes the agent write commit messages in the format tipo(escopo): descrição whenever it commits. Small, testable, immediately useful.
🧬 The minimal anatomy of a SKILL.md
A skill is just one file: SKILL.md. Two parts. At the top, a YAML frontmatter with two required fields— name e description. Below, the Markdown body with the instructions in the imperative. That's all.
name — the identifier
Short, lowercase, with hyphens. It becomes the folder name and how you refer to the skill. E.g.: conventional-commits.
description — the trigger
The most important field. It says WHAT the skill does AND WHEN use it. This is how the agent decides to trigger it. Be explicit and even a little "pushy" — the agent tends to under-trigger.
body — the instructions
Imperative Markdown: "Write...", "Use...", "Avoid...". Explain the why instead of shouting MUSTs in uppercase. Keep it concise (<500 lines).
✍️ Write the SKILL.md (copy this)
Here’s the entire skill, ready to paste. Create the file in skills/conventional-commits/SKILL.md and paste the content below. Notice: frontmatter between ---, a description that says what and when, a short, imperative body.
skills/conventional-commits/SKILL.md
--- name: conventional-commits description: Escreve mensagens de commit no padrão Conventional Commits. Use SEMPRE que for criar um commit, sugerir uma mensagem de commit, ou rodar git commit neste repositório. --- # Conventional Commits Ao criar qualquer commit, escreva a mensagem no formato: tipo(escopo): descrição no imperativo Use estes tipos: - feat nova funcionalidade - fix correção de bug - docs só documentação - refactor mudança sem alterar comportamento - test testes - chore build, deps, config Regras: - Descrição em minúscula, no imperativo ("adiciona", não "adicionado"). - Sem ponto final. Máximo ~72 caracteres na primeira linha. - escopo é opcional; use o módulo afetado quando ajudar. Exemplo bom: feat(auth): adiciona login via magic link Exemplo ruim: Adicionei o login.
💡 The description carries the weight
Note the "Use ALWAYS when..." with three concrete triggers (create a commit, suggest a message, run git commit). This is deliberate: a vague description ("helps with commits") almost never triggers. Tell the agent exactly when to act.
📥 Install locally and see it work
You don’t need to publish anything to use it. Skills install from a local path with npx skills add ./.... Follow the timeline: from the file being created to the agent following the rule.
Create the folder and file
The path matters: the folder becomes the skill name.
$ mkdir -p skills/conventional-commits
$ $EDITOR skills/conventional-commits/SKILL.md # cole o conteúdo
Install from the local path
$ npx skills add ./skills/conventional-commits
This registers the skill with the agent (in .claude/skills/ or equivalent). The name + description now live in the context.
Trigger it with a real request
Ask the agent to commit. The description matches the context, and the skill activates on its own.
você: "commita as mudanças do login"
agente: feat(auth): adiciona login via magic link ✓
Confirm that it triggered
If the message came out in the format tipo(escopo): ... without you asking for the format, the skill worked. Done — you created and ran your first skill.
10 minutes, for real
Choose the case (1 min) → write the SKILL.md (4 min) → install (1 min) → test and adjust (4 min). No build, no deploy, no dependencies. Just a text file.
🚫 Common Beginner Mistakes
Almost every first-skill problem falls into one of these buckets. Compare both sides and adjust before blaming the agent.
✗ What kills a skill
- ✗vague description: "helps with git" — never triggers
- ✗without WHEN to use: describes what it does but not the trigger
- ✗huge body: 800 lines the agent won’t read in full
- ✗broken frontmatter: one was missing
---or incorrect indentation - ✗everything in ALL-CAPS shouting: rules without explaining why
✓ What makes it work
- ✓specific description: verb + object + 2–3 triggers
- ✓"Use when...": says exactly when to take action
- ✓concise body: only the essentials, short examples
- ✓Valid YAML: two
---, two spaces of indentation - ✓imperative + why: "Use feat for X because Y"
💡 Didn’t trigger? It’s almost always the description
If the skill exists but the agent ignores it, 9 times out of 10 the problem is a weak description, not the body. Add concrete triggers (“when committing,” “when running git commit”) and test again. This cycle of refining the description is the heart of Track 4.
🌱 Build on the minimum
You have a working skill. Now resist the urge to bulk it up. Healthy evolution is incremental: adjust the description based on what failed, add examples only when needed, and extract heavy resources into separate files (progressive disclosure) only when the body grows.
Refine the description
Triggered too often (in conversations that weren't about commits)? Tighten it. Not often enough? Add triggers. The description is what you'll change most.
Add examples on demand
Did you get a specific case wrong? Add a "good/bad" pair for that case. Don't try to predict everything in advance—let the mistakes guide you.
Version with the repo
SKILL.md is text: commit it with the project. The whole team inherits the convention, and the skill evolves in git history like any file.
the cycle, in one line:
escrever mínimo → instalar → testar → ajustar description → repetir
💡 Small and alive > large and dead
A 30-line skill you use every day and tweak every week is worth more than a 500-line one written as "complete" and never tested. Start small; let real use trim and grow it.
✅ Module Summary
Next:
1.5 — 🚀 Advanced Tips: Reading the Ecosystem Like a Pro. How to interpret install counts, find empty niches, and decide when NOT to install.