sipeed/picoclaw · error

description is required

Error message

description is required

What it means

SkillInfo.validate rejects a skill whose Description is empty. Descriptions are mandatory (they drive skill selection/recall) and must not exceed MaxDescriptionLength (1024 chars) — exceeding it produces a separate joined error ('description exceeds 1024 character').

Source

Thrown at pkg/skills/loader.go:51

type SkillInfo struct {
	Name        string `json:"name"`
	Path        string `json:"path"`
	Source      string `json:"source"`
	Description string `json:"description"`
}

func (info SkillInfo) validate() error {
	var errs error
	if info.Name == "" {
		errs = errors.Join(errs, errors.New("name is required"))
	} else {
		if err := ValidateSkillName(info.Name); err != nil {
			errs = errors.Join(errs, err)
		}
	}

	if info.Description == "" {
		errs = errors.Join(errs, errors.New("description is required"))
	} else if len(info.Description) > MaxDescriptionLength {
		errs = errors.Join(errs, fmt.Errorf("description exceeds %d character", MaxDescriptionLength))
	}
	return errs
}

type SkillsLoader struct {
	workspace       string
	workspaceSkills string // workspace skills (project-level)
	globalSkills    string // global skills (~/.picoclaw/skills)
	builtinSkills   string // builtin skills
}

// SkillRoots returns all unique skill root directories used by this loader.
// The order follows resolution priority: workspace > global > builtin.
func (sl *SkillsLoader) SkillRoots() []string {
	roots := []string{sl.workspaceSkills, sl.globalSkills, sl.builtinSkills}
	seen := make(map[string]struct{}, len(roots))

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Add a concise description (<= 1024 characters) to the SKILL.md frontmatter: 'description: ...'
2. If you also see the length error, trim the description below 1024 chars
3. Re-run the skills loader after fixing the file to confirm the skill is picked up

Example fix

# before
---
name: my-skill
---

# after
---
name: my-skill
description: Searches the web and summarizes results for the user.
---

if strings.TrimSpace(info.Description) == "" {
    return fmt.Errorf("skill %s: description is required", info.Path)
}
if len(info.Description) > skills.MaxDescriptionLength {
    return fmt.Errorf("skill %s: description exceeds %d chars", info.Path, skills.MaxDescriptionLength)
}

if err := info.Validate(); err != nil {
    if strings.Contains(err.Error(), "description is required") {
        // add a description to SKILL.md frontmatter
    }
}

When it happens

Trigger: A SKILL.md frontmatter or SkillInfo payload with no description key or an empty description string, passed through validate() during load/registration.

Common situations: SKILL.md written with only a name; description key misspelled (desc:, summary:); a generated skill whose LLM output omitted the field.

Related errors

• name is required
• host cannot be empty
• host list contains an empty entry
• channel '%s' not found or not enabled
• no media store available: %w

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/7c196aded97b13bf. Report an issue: GitHub.