Naming Conventions and Metadata Patterns for Discoverable Skills
A single Skill can get away with a rough name. A library of thirty Skills cannot.
Naming and metadata patterns matter less for how any one Skill triggers - that's the description field's job - and more for how a whole team keeps its Skill library organized, scannable, and free of near-duplicates as it grows.
This page collects the patterns that keep a Skill library legible: to Claude, and to the people building and maintaining it. This is a general-purpose list of naming and metadata habits rather than a single fixed checklist - not every item will apply to every team's setup.
How to Use This List
- Apply these patterns as you name new Skills, not as a one-time audit of an existing library (though it's a reasonable audit checklist too).
- Treat the naming items as close to mandatory and the organizational items as judgment calls that scale with library size.
- Revisit this page whenever a team's Skill count grows past what fits comfortably in one folder listing.
Naming the Skill Itself
- Use verb-noun kebab-case for the
namefield.format-release-notes,summarize-support-transcript,apply-style-guideread clearly at a glance and describe an action, not a vague category. - Match the folder name to the
namefield exactly. A Skill namedpr-review-checklistshould live in a folder calledpr-review-checklist/, notpr-review/orchecklist/- mismatches make a library harder to scan and harder to search. - Avoid generic nouns as the whole name.
helper,assistant,utility, andtooldescribe nothing about what the Skill actually does, and they collide easily once a second "helper" Skill shows up. - Name the output, not the process, when the two diverge. A Skill that reads meeting notes and produces a status update is better named
draft-status-updatethanprocess-meeting-notes- the output is usually what a teammate remembers wanting. - Keep names short enough to scan in a folder listing. A name like
summarize-and-format-and-tag-support-conversations-for-reviewis accurate but unreadable; trim to the essential action and object.
Writing the description Field
- Treat the description as the primary discovery signal, not the name. The name helps a human scan a folder; the
descriptionis what Claude actually matches against a task. See Writing an Effective Skill Description That Claude Will Trigger On for the full pattern. - State the concrete output in the first sentence. "Summarizes a customer support transcript into a structured ticket" beats "helps with support," both for a human scanning descriptions and for matching real requests.
- Include a "Use when..." clause naming real trigger language. This is the single highest-leverage sentence in the whole file for keeping the Skill discoverable.
- Keep the description free of internal implementation detail. Tool names, file names, and internal step counts belong in the instructions body, not the description - they add length without adding discoverability.
Organizing a Growing Skill Library
- Group related Skills with a shared name prefix.
pr-review-checklist,pr-summary-draft, andpr-changelog-entrysort together in a folder listing and signal at a glance that they're part of one family. - Check for near-duplicate descriptions before adding a new Skill. If a new Skill's description would plausibly match the same tasks as an existing one, that overlap needs resolving - either narrow one, or fold the new task into the existing Skill as a branch.
- Keep a short index of what each Skill does, separate from the Skills themselves. As a library grows past a dozen or so Skills, a simple list - name, one-line purpose - saves a teammate from having to open every folder to find the right one.
- Retire or merge Skills that stop getting used. An unused Skill with a name similar to an active one is a common source of accidental collisions later; removing it (or merging its useful parts) keeps the library's naming space clean.
- Version informally with a short comment, not a name suffix.
pr-review-checklist-v2/fragments the library and breaks any existing references; a one-line "last updated" comment inside SKILL.md communicates the same thing without splitting the name.
Naming Bundled Files Consistently
- Give bundled reference files descriptive, self-contained names.
style-guide.mdandticket-schema.mdare clear on their own;notes.mdordata.mdrequire opening the file to know what it holds. - Prefix bundled scripts by what they do, not by the Skill they live in.
normalize-dates.pyis reusable in spirit and clear in a folder listing;helper1.pyis neither. - Reference bundled files by their exact name inside the instructions. This is as much a naming discipline as a structural one - a step that says "the reference file" instead of naming
reference.mdmakes the connection harder to verify at a glance.
FAQs
Why does naming matter if the description is what actually triggers a Skill?
The description drives triggering, but names are what a human scans when browsing a folder of Skills, and mismatched or vague names make it much harder to spot duplicates, gaps, and the right existing Skill to extend.
What's the standard format for a Skill's name field?
- Verb-noun, kebab-case:
format-release-notes,summarize-support-transcript. - The folder name should match it exactly.
Why avoid names like "helper" or "assistant"?
They describe a category, not an action, so they collide easily as a library grows and tell a scanning teammate nothing about what the Skill actually produces.
Should I include a version number in a Skill's name, like pr-review-checklist-v2?
- Generally no - it fragments the library and breaks any existing references to the original name. A short "last updated" comment inside the file communicates the same history without splitting the naming space.
How do I keep a growing Skill library from developing near-duplicate Skills?
Check new Skills' descriptions against existing ones before adding them, and keep a simple index (name plus one-line purpose) once the library grows past a dozen or so Skills.
Should bundled reference files and scripts follow their own naming pattern?
- Yes. Descriptive, self-contained names like
style-guide.mdornormalize-dates.pyare clear without opening the file, unlike generic names likenotes.mdorhelper1.py.
What belongs in the description field versus the name field?
The name is a short, scannable identifier. The description carries the actual discovery signal - what the Skill does and when it should trigger - and should stay free of internal implementation detail like tool or file names.
How should I name a group of closely related Skills?
- Give them a shared prefix, like
pr-review-checklist,pr-summary-draft, andpr-changelog-entry, so they sort together in a folder listing and visibly signal they're part of one family.
What should I do with a Skill that's stopped being used?
Retire or merge it rather than leaving it in place. An unused Skill with a name similar to an active one is a common source of accidental collisions and confusion later.
Is there a single mandatory naming checklist every team must follow?
- Not exactly - the naming patterns (kebab-case, matching folder names, avoiding generic nouns) are close to universal, but the organizational patterns (prefixing, indexing, retiring) are judgment calls that scale with how many Skills a team actually has.
Related
- Writing an Effective Skill Description That Claude Will Trigger On - the field that actually drives triggering, distinct from naming.
- Skill Design & Packaging Basics - a first working SKILL.md with a properly formed name and description.
- Common Mistakes That Make a Skill Hard for Claude to Find or Use - naming and metadata failures alongside description failures.
- Common Types of Agent Skills Teams Build First - typical Skills a naming library ends up organizing.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.