Building your own Skill: from idea to reusable slash command
I caught myself, across several consecutive sessions, retyping the same instructions to Claude Code: my commit message format, which dev port to pick for a new project, the ban on the default indigo/violet gradient on a UI. At some point, repeating an instruction stops being a detail and becomes a signal: it's time to turn it into a skill.
The signal that justifies a skill#
Not every habit deserves a skill. The question I ask myself before creating one: would I give the same instruction, in the same words, on a different project, a month from now? If yes, it's a skill. If it's specific to the current task, it stays a one-off instruction in the prompt.
A concrete indicator: if you paste the same paragraph of instructions into three different sessions, it's already too late, you should have turned it into a skill by the second one.
From idea to SKILL.md#
At its core, a skill is a folder with a SKILL.md file describing when to
trigger and what to do, along with scripts or reference files if needed. I
go through skill-creator, a skill dedicated to creating other skills,
rather than writing the SKILL.md by hand from scratch: it asks the right
questions (what trigger, what expected output, what edge cases) and avoids
forgetting a section.
---
name: project-conventions
description: Standard conventions for personal/freelance projects (commits, UI, stack, copyright...). Apply by default, without waiting to be asked.
---
## When to trigger
As soon as coding, committing or designing for a personal/freelance
project, not only when explicitly reminded.
## Rules
1. Angular-format commits, never any trace of AI in the code
2. Polished UI from the first draft, no default indigo/violet gradient
3. Default stack: Next.js, TypeScript, Tailwind, VercelThis is a simplified excerpt, but it shows the essential part: the
description field isn't a summary for a human, it's what the model reads
to decide whether to load the skill. A vague description like "helps with
projects" almost never triggers on its own.
Turning it into a slash command#
A skill can trigger on its own if its description matches the context, or
be invoked explicitly via /skill-name. The two uses aren't mutually
exclusive: I systematically design my skills to work both ways, with
optional arguments for the slash command when it makes sense
(/new-project my-app --private, for example).
| Trigger mode | Who decides | Typical use case |
|---|---|---|
| Automatic (description) | The model, based on context | Convention applied without thinking (project-conventions) |
| Explicit slash command | Me, at the moment I choose | One-off action with parameters (new-project, save-config) |
What makes a skill trigger, or not#
This is the part that took the most iteration. A skill remains probabilistic by nature: nothing guarantees it will be loaded, even if it exists and would be relevant. The description needs to contain the words I would naturally use in a prompt, not a technical paraphrase. I had a dependency-checking skill that never triggered on its own as long as its description said "security audit": nobody says that in everyday language. Once reworded to "check if my dependencies are up to date, look for vulnerabilities", it started triggering correctly.
Pitfalls I've run into#
- Too broad: a skill that tries to cover every case becomes a list of vague rules, hard to follow and hard to maintain.
- Too rigid: conversely, a skill that prescribes a fixed sequence breaks on the first case its author didn't anticipate.
- Technical rather than natural description: the skill exists, but never triggers because nobody talks like its description.
A poorly triggered skill gives a false sense of security: you think you've encoded a rule, when in practice it only applies when you remember to think about it yourself. Always test automatic triggering before trusting the skill.
What it changes day to day#
I now have about a dozen personal skills: one for my project conventions, one to scaffold a new project in a single command, one to sync my todo list to my calendar, one to audit dependencies across all my repos at once. None of them were written in one pass: each started as a repeated instruction, then got refined over several sessions until it triggered reliably.
The method fits in one sentence: start from the annoyance of having repeated the same thing twice, write the description the way you'd say the need out loud, and let the skill fail to trigger a few times before fixing it. It's that iteration, not the first version, that makes a skill truly reusable.
