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 name field. format-release-notes, summarize-support-transcript, apply-style-guide read clearly at a glance and describe an action, not a vague category.
• Match the folder name to the name field exactly. A Skill named pr-review-checklist should live in a folder called pr-review-checklist/, not pr-review/ or checklist/ - mismatches make a library harder to scan and harder to search.
• Avoid generic nouns as the whole name. helper, assistant, utility, and tool describe 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-update than process-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-review is 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 description is 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, and pr-changelog-entry sort 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.md and ticket-schema.md are clear on their own; notes.md or data.md require opening the file to know what it holds.
• Prefix bundled scripts by what they do, not by the Skill they live in. normalize-dates.py is reusable in spirit and clear in a folder listing; helper1.py is 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.md makes the connection harder to verify at a glance.

FAQs

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.