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

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 and scripts/validate-skills.py.

Character Set and Format Requirements

The specification in 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 enforces this through the NAME_PATTERN regular expression:

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 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 implements this validation:

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 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:

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:

---
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:

---
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 frontmatter.
• The validation script 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 compares the directory name against the name field in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}