larksuite/cli · error

host embedded skill content is invalid

Error message

host embedded skill content is invalid

What it means

ErrInvalidHostBase reports that the wrapper-provided base skill tree passed to cmd.SetEmbeddedSkillContent is malformed — bad frontmatter, invalid skill names, or similar. It is deliberately distinct from a plugin's replacement Base so diagnostics can direct the integrator (the host) to fix their content rather than suspecting a plugin. ResolveWithReferences returns it on fail-closed validation paths, and the command layer attaches a hint pointing at SetEmbeddedSkillContent.

Source

Thrown at internal/skillpolicy/resolver.go:44

}

// ErrMultipleSkillsOverlays reports that more than one plugin tried to
// customize skill content. Mirrors cmdpolicy.ErrMultipleRestricts: only
// one owner is allowed so independent plugins cannot silently overwrite
// each other's skill tree.
var ErrMultipleSkillsOverlays = errors.New("multiple plugins customized skills; only one plugin may own skill content")

// ErrNoBaseSkillContent reports that Allow or Remove was requested against an
// empty base tree. This most often means an external wrapper main omitted
// cmd.SetEmbeddedSkillContent; exposing a sentinel lets the command layer give
// the integrator that specific recovery action instead of blaming a skill-name
// typo.
var ErrNoBaseSkillContent = errors.New("build embeds no base skill content")

// ErrInvalidHostBase reports that the wrapper-provided base skill tree is
// malformed. It is distinct from a plugin's replacement Base so diagnostics
// can direct the integrator to the correct owner.
var ErrInvalidHostBase = errors.New("host embedded skill content is invalid")

// ErrUnsatisfiedSkillDependency reports that a skill retained by the final
// composed manifest declares another skill that the manifest does not retain.
// The resolver never widens Allow or overrides Remove to repair this: an
// incomplete distribution is a build-integrity error.
var ErrUnsatisfiedSkillDependency = errors.New("composed skill tree has an unsatisfied required skill")

// Resolution is the build-local result of composing embedded skill assets.
// Content serves `skills list`/`read`; References projects canonical
// CLI-authored pointers onto that same tree.
type Resolution struct {
	Content    fs.FS
	References *skillref.Resolver
}

// resolveContent is a test convenience over the production resolution path.
func resolveContent(base fs.FS, specs []PluginSkill) (fs.FS, error) {
	resolved, err := ResolveWithReferences(base, specs)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Fix the malformed content passed to cmd.SetEmbeddedSkillContent — check frontmatter delimiters and skill names.
2. Validate each base skill file's frontmatter (--- delimiters, valid name fields) before building the embed FS.
3. Rebuild and re-run resolution; the fail-closed behavior ensures nothing partially loads until the base tree is valid.

Example fix

// before: embedded SKILL.md with unclosed frontmatter
---
name: my-skill
description: ...
# content
// after
---
name: my-skill
description: ...
---
# content

// sanity-check each embedded SKILL.md's frontmatter before embedding:
for _, f := range skillFiles {
    if !hasClosedFrontmatter(f) { return fmt.Errorf("unclosed frontmatter in %s", f) }
}

if errors.Is(err, skillpolicy.ErrInvalidHostBase) {
    // host content is malformed; do not blame plugins
}

if err := execute(); err != nil {
    if errors.Is(err, skillpolicy.ErrInvalidHostBase) {
        // fix the content passed to cmd.SetEmbeddedSkillContent
    }
}

When it happens

Trigger: Resolution fails while validating the host-embedded base tree: unclosed frontmatter in a SKILL.md, or an invalid required-skill name — the fail-closed tests (TestResolve_UnclosedFrontmatterFailsClosed, TestResolve_InvalidRequiredSkillNameFailsClosed) exercise these paths.

Common situations: Hand-edited embedded SKILL.md files with broken YAML frontmatter delimiters; renamed skills leaving stale references; wrapper builds embedding content generated by an older or misconfigured tool.

Related errors

• build embeds no base skill content
• composed skill tree has an unsatisfied required skill
• Missing sheet_id for sheet {title!r}
• multiple plugins customized skills; only one plugin may own
• invalid skill reference remap

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/2b33843b90ee8d5e. Report an issue: GitHub.