Naming Conventions

Naming Guide

Effective naming conventions ensure discoverability, avoid conflicts, and promote composability

Why Naming Matters

Claude relies heavily on the `name` and `description` fields for autonomous activation, so clear, consistent naming reduces misinvocations and improves reliability.

Quick Reference

Element	Format	Example
Folder Name	`kebab-case`	`my-skill-folder`
YAML name	`kebab-case or snake_case`	`my-skill-name`
YAML description	`Sentence case, declarative`	`Process CSV files with validation`
Internal files	`kebab-case or snake_case`	`extract_data.py`
SKILL.md	`Exact match (required)`	`SKILL.md`

1. Skill Folder Naming

Convention

kebab-case (lowercase with hyphens)

Filesystem-friendly, consistent with URL slugs and package names; avoids spaces/camelCase issues across platforms.

Examples from Anthropic

skill-creatorgenerating-commit-messagescode-reviewersafe-file-readerdocxpdfpptxxlsx

Before and After

AVOID

My Excel Skill

USE

excel-analyzer

AVOID

data_processing_v2

USE

data-processor

AVOID

PDF_Handler

USE

pdf-processor

2. YAML Frontmatter: `name` Field

Convention

Human-readable, title-case or natural phrasing; kebab-case or snake_case common

Max Length

Max 64 characters

Role

Used internally for identification and sometimes in meta-tool commands

Best Practices

Keep unique and non-overlapping
Avoid generics like "helper" or "tool"
Match folder name loosely for consistency

Avoid

Generic names: helper, tool, utility
Overlapping names with existing skills
Very long names (>64 chars)

3. YAML Frontmatter: `description` Field

Why This is Critical

Primary trigger for Claude's activation—optimize for keyword matching with user tasks

Template

[Action Verb] [what it does]. Use when [common task/scenario].

Action Verb:Analyze, Generate, Review, Create, Process, Transform

what it does:brief description of functionality

common task/scenario:specific use cases or contexts

Examples

Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
Read files without making changes. Use when you need read-only file access.

Best Practices

Start with action verb: "Analyze...", "Generate...", "Review..."
Include trigger phrases: "Use when [common task]"
Add specificity: Mention domains/tools (e.g., "for pandas dataframes" or "BigQuery queries")

4. Internal Files and Subfolders

Standard Structure

my-skill-folder/          # kebab-case
├── SKILL.md              # Always this exact name (required)
├── scripts/              # Executable code
├── references/           # Or REFERENCE.md for single files
├── examples/             # Or EXAMPLES.md
├── templates/            # Templates with clear names
└── assets/               # Other resources

Folder Purposes

scripts/Executable code files

references/Documentation and guides

examples/Usage examples and demos

templates/File templates

assets/Images, data files, resources

Conventions

File Naming: Use kebab-case or snake_case for consistency
Examples: style_guide.md, troubleshooting.md, extract_fields.py
Markdown Headings: Match `name` loosely (e.g., # Generating Commit Messages)
Always use exact filename: SKILL.md (required, case-sensitive)

5. General Development Best Practices

Uniqueness

Ensure no overlap with existing skills

Check anthropics/skills repo before naming

Modularity

Narrow scope → specific names

Use pandas-cleaning over data-analysis

Versioning

Avoid in names/folders

Use API /v1/skills for versions instead

Testing

Verify activation in separate sessions

Observe if Claude activates correctly based on description keywords

Community Patterns

Follow established conventions

Prefer actionable, verb-noun phrases from shared skills

Start with skill-creator

Following these conventions makes Skills more reliable for autonomous use and easier to share. Start with the built-in skill-creator Skill— it enforces good structure automatically!

For official examples, explore github.com/anthropics/skills