charmbracelet/crush · error

description is required

Error message

description is required

What it means

Skill.Validate requires a non-empty Description; when present it must not exceed MaxDescriptionLength. An empty description means the frontmatter lacks `description:`, which the spec requires so the agent can decide when to use the skill.

Source

Thrown at internal/skills/skills.go:136

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...)
}

// Parse parses a SKILL.md file from disk.
func Parse(path string) (*Skill, error) {
	content, err := os.ReadFile(path)
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 7944b8e522)

Solutions

1. Add a concise `description:` line to the SKILL.md frontmatter
2. Shorten the description if it exceeds MaxDescriptionLength
3. Keep the description action-oriented (what the skill does and when to use it)

Example fix

// before
---
name: my-skill
---
// after
---
name: my-skill
description: Reviews Go code for lint issues before commit
---

if strings.TrimSpace(skill.Description) == "" {
	return errors.New("skill frontmatter must define a description")
}
if len(skill.Description) > skills.MaxDescriptionLength {
	return errors.New("description too long")
}

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

When it happens

Trigger: Parsing a SKILL.md without a `description:` key (or with an empty one) and calling Validate; also triggered indirectly when description exceeds MaxDescriptionLength (companion error).

Common situations: Minimal skill stubs created without frontmatter; templates copied with description removed; very long prose descriptions pasted in that blow the length cap.

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
• name exceeds %d characters
• 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/a85fd7afcd8c3669. Report an issue: GitHub.