Tencent/WeKnora · error

skill name is %d characters; maximum is %d

Error message

skill name is %d characters; maximum is %d

What it means

Skill.Validate enforces the Claude skill-spec limit on name length: a name longer than MaxNameLength runes is rejected. Length is measured in runes (not bytes), so non-ASCII names are counted fairly. This fires during skill parsing/installation (ParseSkillFile) before the skill can be registered.

Source

Thrown at internal/agent/skills/skill.go:88

	BasePath    string // Path to skill directory for later loading
}

// SkillFile represents an additional file within a skill directory (Level 3)
type SkillFile struct {
	Name     string // Filename (e.g., "FORMS.md", "scripts/validate.py")
	Path     string // Absolute path to the file
	Content  string // File content
	IsScript bool   // Whether this is an executable script
}

// Validate checks if the skill metadata is valid according to Claude's specification
func (s *Skill) Validate() error {
	// Validate name
	if s.Name == "" {
		return errors.New("skill name is required")
	}
	if n := utf8.RuneCountInString(s.Name); n > MaxNameLength {
		return fmt.Errorf("skill name is %d characters; maximum is %d", n, MaxNameLength)
	}
	if !namePattern.MatchString(s.Name) {
		return errors.New("skill name must contain only letters, numbers, hyphens, and underscores")
	}
	for _, reserved := range reservedWords {
		if strings.Contains(s.Name, reserved) {
			return fmt.Errorf("skill name cannot contain reserved word: %s", reserved)
		}
	}
	if xmlTagPattern.MatchString(s.Name) {
		return errors.New("skill name cannot contain XML tags")
	}

	// Validate description
	if s.Description == "" {
		return errors.New("skill description is required")
	}
	if n := utf8.RuneCountInString(s.Description); n > MaxDescriptionLength {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Shorten the 'name' field in SKILL.md frontmatter to MaxNameLength characters or fewer (use a kebab-case id, put the long title in 'description')
2. Rely on applyInstallName to derive a valid install id from slug/title when available
3. Regenerate the skill archive with a corrected frontmatter name
4. Check MaxNameLength in the skills package and validate the name before packaging

Example fix

# before
---
name: very-long-auto-generated-skill-name-exceeding-the-limit-value
---
# after
---
name: doc-converter
---

if n := utf8.RuneCountInString(name); n > skills.MaxNameLength {
    return fmt.Errorf("name %d runes exceeds max %d", n, skills.MaxNameLength)
}
if err := skill.Validate(); err != nil { return err }

func validSkillName(name string) bool {
    return utf8.RuneCountInString(name) <= skills.MaxNameLength
}

if err := skill.Validate(); err != nil {
    if strings.Contains(err.Error(), "maximum is") {
        skill.Name = truncateToRunes(skill.Name, skills.MaxNameLength)
        return skill.Validate()
    }
    return err
}

When it happens

Trigger: Installing/parsing a SKILL.md whose frontmatter name exceeds MaxNameLength characters — typically long auto-generated names, titles used verbatim as names, or verbose Chinese/multi-word names.

Common situations: Third-party skills with display titles in 'name'; generated skill names embedding long task descriptions; archives created by external tools without length validation.

Related errors

• model ID cannot be empty
• unknown credential field:
• member_limit must be >= 0
• cannot request upgrade to same or lower role
• E2B timeout must be at least one second

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/5f105c492ddb74d0. Report an issue: GitHub.