charmbracelet/crush · error

name must be alphanumeric with hyphens, no leading/trailing/

Error message

name must be alphanumeric with hyphens, no leading/trailing/consecutive hyphens

What it means

Skill.Validate rejects names that do not match namePattern: lowercase/direct alphanumeric with hyphens, and no leading, trailing, or consecutive hyphens. This keeps skill names valid as identifiers and directory names.

Source

Thrown at internal/skills/skills.go:128

// arrives.
func SetLatestStates(states []*SkillState) {
	latestStatesMu.Lock()
	latestStates = cloneStates(states)
	latestStatesMu.Unlock()
}

// Validate checks if the skill meets spec requirements.
func (s *Skill) Validate() error {
	var errs []error

	if s.Name == "" {
		errs = append(errs, errors.New("name is required"))
	} else {
		if len(s.Name) > MaxNameLength {
			errs = append(errs, fmt.Errorf("name exceeds %d characters", MaxNameLength))
		}
		if !namePattern.MatchString(s.Name) {
			errs = append(errs, errors.New("name must be alphanumeric with hyphens, no leading/trailing/consecutive hyphens"))
		}
		if s.Path != "" && !strings.EqualFold(filepath.Base(s.Path), s.Name) {
			errs = append(errs, fmt.Errorf("name %q must match directory %q", s.Name, filepath.Base(s.Path)))
		}
	}

	if s.Description == "" {
		errs = append(errs, errors.New("description is required"))
	} else if len(s.Description) > MaxDescriptionLength {
		errs = append(errs, fmt.Errorf("description exceeds %d characters", MaxDescriptionLength))
	}

	if len(s.Compatibility) > MaxCompatibilityLength {
		errs = append(errs, fmt.Errorf("compatibility exceeds %d characters", MaxCompatibilityLength))
	}

	return errors.Join(errs...)
}

View on GitHub (pinned to 7944b8e522)

Solutions

1. Rewrite the name using only alphanumerics and single interior hyphens (e.g. `code-review-helper`)
2. Remove leading/trailing hyphens and collapse consecutive hyphens
3. Make the name match the skill's directory name (see companion name/directory mismatch error)

Example fix

// before
name: Code Review
// after
name: code-review

var nameRe = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
if !nameRe.MatchString(skill.Name) {
	return fmt.Errorf("invalid skill name %q", skill.Name)
}

if err := skill.Validate(); err != nil {
	return fmt.Errorf("invalid skill name: %w", err)
}

When it happens

Trigger: A SKILL.md with `name: My Skill`, `name: -foo-`, `name: foo--bar`, or names with underscores/spaces is parsed and validated.

Common situations: Naming a skill with spaces or underscores out of habit; pasting a display title into the name field; renaming a directory without updating the frontmatter name.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• name is required
• description is required
• name exceeds %d characters
• name %q must match directory %q
• description exceeds %d characters

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/43a6acb469e43585. Report an issue: GitHub.