charmbracelet/crush · error

name exceeds %d characters

Error message

name exceeds %d characters

What it means

Skill.Validate enforces the Agent Skills spec limits: a non-empty name at most MaxNameLength (64) characters. This error is appended when the SKILL.md frontmatter 'name' field exceeds 64 bytes, and is aggregated with other validation errors into the returned error. A skill failing validation is not exposed as active, so it cannot be invoked.

Source

Thrown at internal/skills/skills.go:125

// SetLatestStates stores the given states in the package-level cache so that
// GetLatestStates can return them synchronously before the first pubsub event
// 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))
	}

View on GitHub (pinned to 7944b8e522)

Solutions

1. Shorten the 'name' field in SKILL.md frontmatter to 64 characters or fewer
2. Rename the skill directory to a short name and keep name matching the directory base (names are matched case-insensitively to filepath.Base(Path))
3. Re-run discovery and confirm the skill reaches StateNormal in skills.GetLatestStates

Example fix

// before (SKILL.md frontmatter)
name: my-extremely-long-descriptive-skill-name-that-goes-on-and-on-for-many-characters

// after (SKILL.md frontmatter) — 64 chars max, alphanumeric + hyphens
name: my-long-descriptive-skill

const maxNameLength = 64
func validSkillName(name string) error {
    if name == "" { return errors.New("name is required") }
    if len(name) > maxNameLength { return fmt.Errorf("name exceeds %d characters", maxNameLength) }
    if !regexp.MustCompile(`^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$`).MatchString(name) {
        return errors.New("name must be alphanumeric with hyphens")
    }
    return nil
}

if err := skill.Validate(); err != nil {
    // Validate aggregates all issues; show them all so the user fixes the frontmatter in one pass
    return fmt.Errorf("invalid SKILL.md %s:\n%w", skill.Path, err)
}

When it happens

Trigger: Parsing a SKILL.md whose YAML frontmatter 'name' is longer than 64 characters, then calling Validate (invoked during discovery for every discovered skill file).

Common situations: Very descriptive skill names pasted from docs; auto-generated skills with long directory names mirrored into the name field; copied skill templates that keep a long placeholder name; directory-name matching rules pushing authors to long folder names.

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 %q must match directory %q
• description exceeds %d characters
• compatibility exceeds %d characters

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