# Skill Name Constraints in claude-skills: Validation Rules and Regex Patterns

> Discover skill name constraints in claude-skills. Learn validation rules and regex patterns for alphanumeric characters and hyphens to ensure compliant skill setup.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Skill names in claude-skills must match the regular expression `^[a-zA-Z0-9-]+$`, allowing only alphanumeric characters and hyphens, and must exactly match their containing directory name.**

The claude-skills repository enforces strict naming conventions to ensure reliable skill discovery and invocation by the Claude plugin. Understanding the constraints for skill names in claude-skills is essential for contributors, as the validation pipeline rejects any name violating the character set or directory synchronization rules defined in [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) and [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py).

## Character Set and Format Requirements

The specification in [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) restricts skill names to a specific character set. Only **letters (A-Z, a-z)**, **digits (0-9)**, and **hyphens (-)** are permitted. Spaces, underscores, periods, parentheses, and other punctuation characters are explicitly forbidden.

The validation script [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) enforces this through the `NAME_PATTERN` regular expression:

```python
NAME_PATTERN = re.compile(r'^[a-zA-Z0-9-]+$')

```

This regex anchors the match to the start (`^`) and end (`$`) of the string, ensuring the entire name consists exclusively of the allowed characters without any additional whitespace or special symbols.

## Directory Synchronization Rules

Beyond character validation, claude-skills requires that the **directory name containing the skill must exactly match the `name` field** defined in the skill's [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) frontmatter. This synchronization ensures the filesystem structure aligns with the metadata, preventing path resolution errors during skill invocation.

The `NameFormatChecker` class in [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) implements this validation:

```python
if name and name != skill_name:
    issues.append(ValidationIssue(
        skill=skill_name,
        check=self.name,
        severity=Severity.WARNING,
        message=f"Directory name '{skill_name}' doesn't match skill name '{name}'",
    ))

```

Here, `skill_name` represents the directory name, while `name` represents the value from the YAML frontmatter. A mismatch generates a warning during validation.

## Validation Implementation

The validation pipeline processes each skill directory under `skills/` and applies multiple checks through the [`validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/validate-skills.py) script. The name validation occurs within the `NameFormatChecker` class, which iterates through all discovered skills and verifies both the regex pattern and directory synchronization.

When a name violates the character constraints, the validator produces an explicit error message:

```python
if name and not NAME_PATTERN.match(name):
    issues.append(ValidationIssue(
        skill=skill_name,
        check=self.name,
        severity=Severity.ERROR,
        message=f"Invalid name format: '{name}'. Use only letters, numbers, and hyphens.",
    ))

```

This implementation ensures that no invalid skill names can be merged into the repository, maintaining the integrity of the skill registry.

## Valid and Invalid Examples

Understanding the practical application of these constraints requires examining concrete examples of skill definitions.

### Valid Skill Name

The following example demonstrates a compliant skill configuration in [`skills/react-expert/SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/skills/react-expert/SKILL.md):

```yaml
---
name: react-expert
description: Use when building modern React applications that need performance tuning.
license: MIT
metadata:
  author: https://github.com/yourname
  version: "1.0.0"
  domain: frontend
  triggers: react, hooks, performance
  role: expert
  scope: implementation
  output-format: code
  related-skills: vue-expert, angular-architect
---

```

This name passes validation because it contains only lowercase letters and a hyphen, matches the directory name `react-expert`, and conforms to the `^[a-zA-Z0-9-]+$` pattern.

### Invalid Skill Names

The following examples violate the naming constraints:

**Contains space and period:**

```yaml
---
name: react.expert v2
---

```

This fails validation because spaces and periods are not allowed in the character set. The validator returns: "Invalid name format: 'react.expert v2'. Use only letters, numbers, and hyphens."

**Directory mismatch:**

```

skills/
└─ vue-expert/
     └─ SKILL.md   (contains name: react-expert)

```

This configuration generates a warning: "Directory name 'vue-expert' doesn't match skill name 'react-expert'."

## Summary

- Skill names in claude-skills must match the regular expression `^[a-zA-Z0-9-]+$`, permitting only alphanumeric characters and hyphens.
- The directory name under `skills/` must exactly match the `name` field in the skill's [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) frontmatter.
- The validation script [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) enforces these rules through the `NameFormatChecker` class, generating errors for invalid characters and warnings for directory mismatches.
- No spaces, underscores, periods, or other punctuation are permitted in skill names.

## Frequently Asked Questions

### Can skill names in claude-skills contain underscores?

No. The validation regex `^[a-zA-Z0-9-]+$` explicitly excludes underscores. Only letters, numbers, and hyphens are permitted. If you attempt to use a name like `python_expert`, the validator will reject it with an error message indicating that only letters, numbers, and hyphens are allowed.

### What happens if the directory name doesn't match the skill name?

The validation script generates a warning rather than an error. The `NameFormatChecker` class in [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) compares the directory name against the `name` field in [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md). If they differ, it appends a `ValidationIssue` with `Severity.WARNING` and the message "Directory name '{skill_name}' doesn't match skill name '{name}'". While this won't block validation, it indicates a synchronization issue that should be corrected.

### Is there a maximum length limit for skill names?

No explicit length limit is enforced by the validation regex or the [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) specification. However, practical conventions within the repository suggest keeping names concise and readable, typically using short descriptive phrases like `react-expert` or `python-debugger`. Extremely long names would function technically but would be unwieldy in command-line usage and YAML frontmatter.

### Are skill names case-sensitive?

Yes, skill names are case-sensitive in both the filesystem and the validation logic. The regex `^[a-zA-Z0-9-]+$` allows both uppercase and lowercase letters, treating them as distinct characters. Therefore, `React-Expert` and `react-expert` would be considered different names. However, the repository convention appears to favor lowercase names with hyphens for consistency and cross-platform filesystem compatibility.