Using a Skill: When to Invoke and How to Name

# Using a Skill: When to Invoke and How to Name Skills are not for everything. The mistake people make after writing their first skill is writing ten more — one for every situation, most of which they'll never invoke. Here's what you'll get from the next 15 minutes: a clear filter for when a skill is the right move, and a naming pattern that makes your skills usable long after you wrote them. ## The filter A skill earns its place when two things are both true: **It's high-friction without one.** If you find yourself re-explaining the same context at the start of sessions — "I'm working on the API layer, always check for workspace_id scoping, use the Supabase MCP before writing migrations" — that friction compounds. Every session, you pay it again. A skill eliminates it. **It runs more than twice.** If you only do it once, write the prompt inline. Skills have maintenance cost. They deserve it only for workflows you run over and over. The failure mode is the catch-all skill. Someone writes a skill called `my-project-context` and dumps 600 words of project documentation into it. The skill fires on vague triggers, conflicts with other context, and becomes noise rather than signal. That's CLAUDE.md's job. ## When not to write a skill **One-off work.** You need to convert a CSV to JSON once. Don't write a skill. Write the prompt, do the work, move on. **Context that belongs in CLAUDE.md.** Your stack, your conventions, your environment variables — that's project memory, not a skill. Put it where it lives. **Anything that needs different instructions each time.** A skill is a fixed procedure. If the procedure changes based on inputs, you want a prompt, not a skill. ## The difference between a good skill and a bad one **Bad skill — vague, catch-all:** ```yaml --- name: help-me description: Helps with various coding tasks triggers: - help - code - assist --- # Help Me You are a helpful assistant. Help with coding tasks. ``` This skill fires on the word "help" — which you type constantly. The body has no instructions. It's describing the skill, not running a workflow. **Good skill — precise, instructional:** ```yaml --- name: add-api-route description: Scaffold a new Next.js API route with Zod validation, error handling, and workspace scoping triggers: - add api route - new api route - scaffold api route --- # Add API Route You are scaffolding a new Next.js App Router API route for a multi-tenant app. ## Process 1. Ask for the route name and HTTP method if not provided. 2. Create the file at `app/api//route.ts`. 3. Import and use the Zod schema pattern from existing routes in `app/api/`. 4. Always include workspace_id scoping before returning any data. 5. Include a specific error class — never return a bare `{ error: "something went wrong" }`. ``` The trigger phrase "add api route" is something you'd naturally type. The body tells Claude exactly what to do, in order. ## Naming conventions that hold up Names get unwieldy fast if you don't have a pattern. Use verb-noun format: - `write-migration` not `migration` or `migration-helper` - `add-component` not `component` or `react-component-generator` - `debug-this` not `debugging` or `debug-helper-workflow` - `review-pr` not `pr` or `code-review` The verb matters. It tells you at a glance what the skill does when invoked. `write-migration` fires when you're about to write something. `review-pr` fires when you're about to review something. You can scan a list of 12 skills and immediately know which one to reach for. Match the trigger to how you'd naturally phrase the request. If you'd type "debug this" when something breaks, the trigger should be `debug this`. Don't make people remember an arbitrary incantation. ## Installing and checking what's loaded Skills live at: - `~/.claude/skills//SKILL.md` — global, applies everywhere - `.claude/skills//SKILL.md` — project-only Run `/skills` in a Claude Code session to see everything that's loaded. If a skill isn't showing up, check the file path and frontmatter format. --- Now you can apply this to: - Auditing any existing skill library you've built — cut anything that fires too broadly or runs fewer than twice - Naming conventions for team skill libraries where multiple people need to find and invoke the right skill fast - The decision before you write a new skill: high-friction recurring task, or one-off work that belongs inline