Hmbown/CodeWhale · error

SKILL.md is missing the leading '---' frontmatter fence

Error message

SKILL.md is missing the leading '---' frontmatter fence

What it means

parse_frontmatter_name validates that a candidate SKILL.md begins with a '---' frontmatter fence and rejects it here otherwise. The input at fault is the downloaded/copied SKILL.md file: it lacks the leading YAML frontmatter delimiter, so no name/description can be parsed; the check exists to fail early on malformed skill packages before any files are written.

Source

Thrown at crates/tui/src/skills/install.rs:1594

        return std::borrow::Cow::Borrowed(path);
    }
    let with_slash = format!("{prefix}/");
    if let Some(rest) = path.strip_prefix(&with_slash) {
        std::borrow::Cow::Owned(rest.to_string())
    } else if path == prefix {
        std::borrow::Cow::Borrowed("")
    } else {
        std::borrow::Cow::Borrowed(path)
    }
}

/// Extract `name:` and ensure `description:` exist in the SKILL.md frontmatter.
/// Also verifies the leading `---` fence so we reject malformed files early.
fn parse_frontmatter_name(bytes: &[u8]) -> Result<String> {
    let content = std::str::from_utf8(bytes).context("SKILL.md is not valid UTF-8")?;
    let trimmed = content.trim_start();
    if !trimmed.starts_with("---") {
        bail!("SKILL.md is missing the leading '---' frontmatter fence");
    }
    let after_open = &trimmed[3..];
    let close = after_open.find("---").ok_or_else(|| {
        anyhow::anyhow!("SKILL.md is missing the closing '---' frontmatter fence")
    })?;
    let frontmatter = &after_open[..close];

    let mut name: Option<String> = None;
    let mut has_description = false;
    for raw in frontmatter.lines() {
        let line = raw.trim();
        if line.is_empty() || line.starts_with('#') {
            continue;
        }
        if let Some((key, value)) = line.split_once(':') {
            let key = key.trim().to_ascii_lowercase();
            let value = value.trim().to_string();
            match key.as_str() {

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Add a leading '---' fence line at the very start of SKILL.md with a name: and description: block
2. Re-download the skill package; the file may have been truncated or corrupted
3. If authoring a skill, follow the SKILL.md frontmatter format (leading '---', name, description, closing '---')

When it happens

Trigger: Thrown at crates/tui/src/skills/install.rs:1594 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/43af76432550e519. Report an issue: GitHub.