🧭 The decision checklist
Before opening an editor, answer four questions. If most of your answers are "no," you don't need a skill — you need another tool, or nothing at all. This is the filter that separates a useful skill from catalog clutter.
Worth creating?
- 1.It’s a repeatable workflow, not a one-off?
- 2.Loads contextual knowledge that the model doesn’t have by default?
- 3.The output is verifiable (can you tell if it turned out right)?
- 4.It’s a task multi-step, not a 1-step query?
≥2 yeses → worth packaging. 0–1 yes → probably over-engineering.
CLAUDE.md
Rule/preference that ALWAYS applies to the project. It always costs context.
MCP
Connect to an external service (API, DB, browser). It’s a connection, not knowledge.
Subagent
Isolated/parallel work with its own context. It’s delegation.
Skill ✦
Knowledge/process that triggers ON DEMAND via the trigger. That’s our case.
📁 Structure the repository
You’ve decided it’s a skill. Now the repo needs to follow the convention that the CLI and skills.sh understand: a folder skills/ at the root, and each skill with its own SKILL.md plus optional resources. A repo can host several atomic skills.
repo structure template:
meu-repo-de-skills/
├── README.md
├── LICENSE
├── CHANGELOG.md
└── skills/
└── minha-primeira-skill/
├── SKILL.md # frontmatter YAML + corpo (<500 linhas)
├── scripts/ # executáveis sob demanda
│ └── run.sh
├── references/ # docs longas, lidas só quando preciso
│ └── deep-dive.md
└── assets/ # templates, imagens
└── template.tpl
SKILL.md — the frontmatter is the trigger:
--- name: minha-primeira-skill description: WHAT it does and WHEN to use it. Trigger when the user asks for X, mentions Y, or needs Z. Be a little pushy — the model tends not to trigger enough. --- # My First Skill Markdown body. Explain WHY, not just the steps. Point to references/ and scripts/ when you need more detail.
💡 The minimum frontmatter
Only name e description are mandatory. The description (~100 words) always stays in context — it’s the only level the model always sees, so that’s where the trigger lives. Say what it does AND when to use it.
🔀 Version with git
Git is the source of truth for the skill. Skills are installed as symlinks for the cloned repo — not frozen copies. A git push yours, plus one npx skills update of whoever installed it, propagates your new version to everyone. Treat the main as production.
the Git flow for a release:
git checkout -b ajuste-gatilho # edita skills/minha-primeira-skill/SKILL.md git add skills/minha-primeira-skill/SKILL.md CHANGELOG.md git commit -m "fix(trigger): cobre o near-miss de refactor" git push origin ajuste-gatilho # abre PR, roda evals de gatilho, merge na main → publicado
✗ Careless
- ✗Push directly to main without testing the trigger
- ✗Change the description and break anything that depended on it
- ✗No CHANGELOG—nobody knows what changed
✓ Responsible
- ✓Branch + PR + evals before merge
- ✓Documented trigger changes
- ✓CHANGELOG.md with each release
📟 npx skills add / update
The commands that make the skill available on your machine. To test locally before publishing, install from the directory path; once it’s on GitHub, install using owner/repo. E update pulls the latest versions.
essential commands:
# instalar do diretório local (teste antes de publicar) npx skills add ./skills/minha-primeira-skill # instalar de um repo público no GitHub npx skills add owner/meu-repo-de-skills # puxar a última versão de tudo que está instalado npx skills update
The local testing loop
Before publishing: run npx skills add ./..., open a session with 2-3 realistic prompts, compare behavior with-skill vs baseline (without a skill). Did you adjust the SKILL.md? Run npx skills update and test again. Publish only when the trigger and output are convincing.
💡 Symlink = free iteration
Because installation is a symlink to the folder, editing SKILL.md in place takes effect in the next session—no need to reinstall. This makes the tuning loop fast. That same symlink, after publishing, is why a bad push affects everyone right away.
🌐 Go live and appear on skills.sh
Publishing means making the repo public on GitHub with the folder skills/ in the right convention. skills.sh indexes public repos and exposes the install count. The timeline from zero to live:
Create the public repo on GitHub
With README, LICENSE, and the folder skills/ at the root. Clear repo name — it becomes part of the owner/repo that people install.
Push the tested v1
SKILL.md with validated frontmatter, resources in place, and trigger evals passing. git push on main.
Indexing on skills.sh
The directory scans public repos, and your skill appears in search results. name e description are what people read in the showcase.
Installs start counting
Each npx skills add owner/repo increases the install count — your social signal for discovery. Remember the power law: only 0.3% exceed 100k.
Naming and description sell
On the skills.sh showcase, people decide whether to install by reading only name + description. A specific name (git-commit-conventional) and a description that says what it does and when it beats a generic name (git-helper) always. It’s the same text that acts as the trigger — two birds.
⏱️ The complete timeline, from zero to publish
Bringing it all together in a single sequence you can follow today. Seven steps, from the decision to a running install count:
Decide — go through the 4-question checklist and the skill/CLAUDE.md/MCP/subagent decision tree.
Structure — create skills/nome/SKILL.md with frontmatter + a concise body.
Test locally — npx skills add ./... and compare with-skill vs. baseline on real prompts.
Refine the trigger — run should-trigger / should-not-trigger evals, adjust the description.
Version — commit, CHANGELOG, branch + PR. git push on main = published.
Go live — public repo, indexed on skills.sh, appears in search.
Measure — install count and feedback start flowing. The lifecycle begins (next module).
💡 Bridge to 5.5
Publishing the first skill is step 6. Section 5.5 wraps up the course with what comes next at scale: internal skills, security, team rollout, and how to keep skills alive without turning them into chaos.
✅ Module Summary
Next:
Module 5.5 — 🚀 Advanced Tips: Governance, Security, and Scale. Internal skills, no surprises, team rollout, and measuring adoption. Wraps up the course.