anthropics/skills · error · ValueError

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

Error message

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

What it means

parse_skill_md() reads skills/<name>/SKILL.md and requires YAML frontmatter; it raises this ValueError when the first line is not `---`. Without an opening delimiter there is no frontmatter block, so name/description cannot be extracted.

Source

Thrown at skills/skill-creator/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 f6656c1256)

Solutions

1. Make line 1 of SKILL.md exactly `---`, then `name:` and `description:` lines, then a closing `---`
2. Check for a BOM or leading blank line: `head -c 20 SKILL.md | xxd` — re-save as UTF-8 without BOM
3. Scaffold new skills with the skill-creator tooling instead of authoring the file from scratch

Example fix

# before (SKILL.md)
# My awesome skill
Does things.
# after
---
name: my-awesome-skill
description: Does things.
---

# My awesome skill

def has_frontmatter(skill_path: Path) -> bool:
    with (skill_path / "SKILL.md").open(encoding="utf-8-sig") as f:  # utf-8-sig strips a BOM
        return f.readline().strip() == "---"

try:
    name, desc, content = parse_skill_md(path)
except ValueError as e:
    print(f"{path}: invalid SKILL.md — {e}")  # report file so the fix is obvious
    continue

When it happens

Trigger: Calling parse_skill_md(path) on a SKILL.md that starts with a BOM, a title like `# My Skill`, a blank first line, or plain prose instead of `---` on line 1 (only surrounding whitespace is tolerated via .strip()).

Common situations: Hand-written skill files that skip frontmatter; copy-paste from a rendered markdown view that dropped the delimiters; editors saving a UTF-8 BOM before the first `---`; leading blank lines inserted by a formatter.

Related errors

• SKILL.md missing frontmatter (no closing ---)
• {word} not found (not an unpacked .docx?)
• parent comment {parent_id} not found
• relationship target is not a POSIX part name: {target!r}
• relationship target resolves to nothing: {target!r}

AI-assisted analysis of anthropics/skills@f6656c1256 (2026-08-14). Data as JSON: /api/errors/b194ab056007588f. Report an issue: GitHub.