warpdotdev/warp · error · ValueError

SKILL.md missing frontmatter (no opening ---)

Error message

SKILL.md missing frontmatter (no opening ---)

What it means

parse_skill_md() in create-skill's utils.py splits SKILL.md on newlines and requires the very first line (after strip) to be '---', the YAML frontmatter opening delimiter. Any file not opening with --- is rejected before name/description parsing, because frontmatter is the only place the skill's name and description are read from.

Source

Thrown at resources/bundled/skills/create-skill/scripts/utils.py:13

"""Shared utilities for skill-creator scripts."""

from pathlib import Path



def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
    """Parse a SKILL.md file, returning (name, description, full_content)."""
    content = (skill_path / "SKILL.md").read_text()
    lines = content.split("\n")

    if lines[0].strip() != "---":
        raise ValueError("SKILL.md missing frontmatter (no opening ---)")

    end_idx = None
    for i, line in enumerate(lines[1:], start=1):
        if line.strip() == "---":
            end_idx = i
            break

    if end_idx is None:
        raise ValueError("SKILL.md missing frontmatter (no closing ---)")

    name = ""
    description = ""
    frontmatter_lines = lines[1:end_idx]
    i = 0
    while i < len(frontmatter_lines):
        line = frontmatter_lines[i]
        if line.startswith("name:"):
            name = line[len("name:"):].strip().strip('"').strip("'")

View on GitHub (pinned to e72fd7aacb)

Solutions

1. Make line 1 exactly --- and close the block with a second --- line
2. Put name: and description: inside the block (the parser handles > and | multiline indicators for long descriptions)
3. Re-save as UTF-8 without a BOM — lines[0].strip() still fails on a BOM-prefixed first line

Example fix

# before
# My Cool Skill

Some intro text.

---
name: my-skill

# after
---
name: my-skill
description: Does one thing well.
---

# My Cool Skill

from pathlib import Path

lines = (skill_path / 'SKILL.md').read_text(encoding='utf-8').splitlines()
if not lines or lines[0].strip() != '---':
    raise ValueError(f'{skill_path}/SKILL.md must open with a --- frontmatter block')

try:
    name, description, content = parse_skill_md(skill_path)
except ValueError as e:
    # report the skill directory alongside the parser's message
    raise SystemExit(f'{skill_path}: {e}') from e

When it happens

Trigger: SKILL.md starting with a blank line, a UTF-8 BOM, a heading like '# My Skill', or prose; calling parse_skill_md on a directory holding a README-style markdown instead of a frontmattered SKILL.md.

Common situations: Hand-written skills pasted from chat output that lost the frontmatter; editors or scaffolds inserting content above the delimiter; files saved with a BOM by Windows editors.

Related errors

• SKILL.md missing frontmatter (no closing ---)
• Invalid repo format: '{}'. Expected 'owner/repo' or 'https:/
• unexpected argument '--skill' found
• Failed to parse saved prompt ID '{id}': {err}
• {error_prefix} '{run_id}': {err}

AI-assisted analysis of warpdotdev/warp@e72fd7aacb (2026-08-16). Data as JSON: /api/errors/01411665f218bea4. Report an issue: GitHub.