Skill catalog: label a skill whose frontmatter does not parse by its directory, and say why

[ligon]

Companion to ligon/sucoder-skills#1 / ligon/sucoder-skills#2 (which fix the two affected skill files). This fixes the generator side so the next broken skill is visible instead of silent.

What was wrong. A SKILL.md whose YAML frontmatter fails to parse rendered in the session catalog as

- SKILL (load with `Read tool: ~/.sucoder/skills/workshop-problem/SKILL.md`)

_read_skill_metadata (sucoder/mirror.py) caught the YAMLError, set data = {}, and returned None; _readable_skill_name then fell back to path.stem, which for every Agent-Skills-style skill is the constant SKILL. Nothing was logged. Two shared skills shipped that way for ten weeks. A frontmatter that parsed to a non-mapping (a bare list) was worse: data.get raised AttributeError out of the prelude build.

Change.

• _read_skill_metadata returns SkillMetadata(name, description, error) (a NamedTuple). A present-but-unusable frontmatter yields name="" and a one-line error with file coordinates — mapping values are not allowed here at line 3, column 164 — from PyYAML's problem / problem_mark. The reader does not invent a name.
• _readable_skill_name falls back to the directory name for a SKILL.md (stem otherwise) and puts (frontmatter did not parse: …) in the description slot, so the catalog line carries the diagnosis.
• The three call sites test metadata.name rather than truthiness and logger.warning once per broken skill per launch. A catalog file with broken frontmatter keeps its generic SKILL CATALOG header rather than being renamed to its directory.

Rendered against the live ~/.sucoder/skills on this node (pre-#2 checkout):

- workshop-problem — (frontmatter did not parse: mapping values are not allowed here at line 3, column 164)
- research-writer — (frontmatter did not parse: mapping values are not allowed here at line 3, column 314)
- prior-art-ledger — Use this skill at the start of a non-trivial task in an existing code repository, …

Tests. Five added in tests/test_mirror.py: broken / valid (regression pin) / non-mapping frontmatter at the unit level, the display-name fallback, and a prelude test that a catalog referencing a broken skill renders - workshop-problem — (frontmatter did not parse: mapping values are not allowed here and that no line starts with - SKILL. Full suite: 655 passed (650 on f72f815). mypy sucoder/mirror.py under the repo's [tool.mypy]: the same two pre-existing var-annotated errors before and after, none in the changed code.

Not changed. scripts/generate_unified_skills_catalog.py does not read local frontmatter (it fetches curated remote skills), so there is nothing to fail closed there — closing out a remark I made earlier that it might.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EVtHa4ZXum7AbKRRSsSNxm