What is the best way to name Claude agent skills?¶
Short answer: Name skills using a verb-noun pattern that describes the action and its context, like 'writing-workflow-sops' or 'registering-building-blocks', so the name alone tells you what the skill does.
The Full Answer¶
Anthropic's official best practices recommend using gerund form (verb + -ing) as the primary naming pattern for agent skills. This clearly describes the activity or capability the skill provides. For example, processing-pdfs immediately tells you the skill handles PDF processing, and writing-documentation tells you it writes docs.
The name field in a skill's YAML frontmatter has specific technical constraints: maximum 64 characters, lowercase letters, numbers, and hyphens only. You cannot use XML tags or reserved words like "anthropic" or "claude" in the name. These constraints keep names clean, URL-friendly, and consistent across the platform.
Beyond the gerund convention, the most important principle is consistency within your skill collection. If you name one skill writing-workflow-sops, don't name the next one sop-writer or create-sops. Pick a pattern and stick with it. Consistent naming makes skills easier to reference in documentation, understand at a glance, search through, and maintain as your library grows.
Noun phrases like pdf-processing and action-oriented names like process-pdfs are acceptable alternatives, but mixing patterns within the same collection creates confusion.
Naming Examples¶
Gerund form (recommended):
| Skill Name | What It Does |
|---|---|
processing-pdfs | Handles PDF text extraction and manipulation |
analyzing-spreadsheets | Analyzes tabular data in spreadsheets |
writing-documentation | Generates documentation content |
managing-databases | Manages database operations |
testing-code | Runs and manages code tests |
Acceptable alternatives:
| Pattern | Example |
|---|---|
| Noun phrase | pdf-processing, spreadsheet-analysis |
| Action-oriented | process-pdfs, analyze-spreadsheets |
Avoid these patterns:
| Pattern | Examples | Why |
|---|---|---|
| Vague names | helper, utils, tools | Tells you nothing about what the skill does |
| Overly generic | documents, data, files | Too broad to be useful |
| Reserved words | anthropic-helper, claude-tools | Blocked by the platform |
| Inconsistent patterns | Mixing writing-docs with pdf-processor | Creates confusion in your library |
Key Takeaways¶
- Use gerund form (verb + -ing) as the default naming pattern:
writing-,processing-,analyzing- - Keep names under 64 characters using only lowercase letters, numbers, and hyphens
- Be consistent across your entire skill collection — don't mix naming patterns
- The name should tell you what the skill does without reading the description
- Avoid reserved words (
anthropic,claude) and vague names (helper,utils)