charmbracelet/crush · error

description exceeds %d characters

Error message

description exceeds %d characters

What it means

Skill.Validate() limits the Description field to MaxDescriptionLength (1024) characters because descriptions are injected into system prompts/agent context and must stay compact. This error is thrown when len(s.Description) > 1024 after parsing SKILL.md frontmatter.

Source

Thrown at internal/skills/skills.go:138

	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
	}

	skill, err := ParseContent(content)
	if err != nil {

View on GitHub (pinned to 7944b8e522)

Solutions

1. Shorten the `description:` field in SKILL.md frontmatter to under 1024 characters, keeping it to a concise when-to-use summary
2. Move detailed instructions, examples, and workflows into the markdown body of SKILL.md (skill.Instructions)
3. Trim boilerplate or duplicated text from the description

Example fix

// before
// description: This skill does X. It works by... [1500 chars of prose including full examples]
// after
// description: Use this skill to do X when the user asks for Y. See body for detailed workflow.

const maxDescription = 1024
if len(strings.TrimSpace(frontmatter.Description)) > maxDescription {
	return fmt.Errorf("description is %d chars, limit %d", len(frontmatter.Description), maxDescription)
}

skill, err := skills.Parse(path)
if err != nil {
	return fmt.Errorf("skipping skill %s: %w", path, err) // log and continue with other skills
}

When it happens

Trigger: Calling Validate() on a Skill whose Description exceeds 1024 characters, typically after Parse/ParseContent reads a SKILL.md whose `description:` frontmatter value is too long.

Common situations: Writing multi-paragraph prose into the description instead of a one-liner; embedding usage examples or full instructions in the description (those belong in the body); auto-generated descriptions from long docstrings.

Related errors

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

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