fix(skills): readable, actionable SKILL.md frontmatter diagnostics

[Uking-xxx]

Brings the SKILL.md frontmatter diagnostic fix (reported and authored by @Hylouis233 in #236) onto main as a clean, reviewable branch.

Fixes #236.

What changed

SKILL.md frontmatter syntax errors and the "missing description" error are now emitted as a single line that names the file, points at the line and column a user actually edits, states the parser reason, and adds a fix hint for the common unquoted-colon mistake.

Before:

  ~/.claude/skills/search-first/SKILL.md
    Nested mappings are not allowed in compact mappings at line 2, column 14:

description: Search first: look before you write code
             ^

After:

  ~/.claude/skills/search-first/SKILL.md: invalid YAML frontmatter at line 3, column 14: Nested mappings are not allowed in compact mappings — description contains an unquoted ":" — wrap the value in double quotes

• packages/coding-agent/src/utils/frontmatter.ts gains describeFrontmatterError() and formatFrontmatterError():
  • Flattens the yaml package's multi-line message onto one line, dropping the quoted source snippet and caret, and reads the location from linePos with a regex fallback on the headline.
  • Shifts parser line numbers by YAML_TO_FILE_LINE_OFFSET = 1, since the opening --- is always line 1 and the YAML block always begins on line 2.
  • Detects the unquoted ": " inside the description scalar by inspecting the parser's recovered tree, so comments, quoted and block scalars, 10:30-style values, URLs and flow collections are left alone.
  • parseFrontmatter's normalization is factored into extractFrontmatter, which the detector reuses so both see identical content.
• packages/agent-core/src/harness/skills.ts and packages/coding-agent/src/core/skills.ts use formatFrontmatterError for parse_failed, and their validateDescription prefixes the file path.
• apps/cli/src/ui/interactive-mode.ts no longer prints the path twice: when a diagnostic message already starts with its path, the remainder is appended to the formatted path line instead of being emitted on a second indented line.

Scope: which skills load or fail is unchanged — message text only. Severity stays warning and the parse_failed / invalid_metadata codes are unchanged, so consumers filtering on those codes still work.

Provenance

Cherry-picked from the author's fork (Hylouis233/Step-Code#3), rebased onto current main. Commit authorship is preserved. The fork branch also carried two unrelated commits (an i18n feat and an ultracode feat); those are deliberately excluded here so this branch contains only the #236 fix — 10 files, +490/−30.

Verification

Reproduced the issue against this branch in an isolated HOME with the exact three files from the report (two unquoted-colon descriptions, one with no frontmatter block), then confirmed the new output:

[Skill conflicts]
  ~/.claude/skills/omc-learned/weapp-researcher/SKILL.md: frontmatter is missing "description" — add e.g. description: "..."
  ~/.claude/skills/search-first/SKILL.md: invalid YAML frontmatter at line 3, column 14: Nested mappings are not allowed in compact mappings — description contains an unquoted ":" — wrap the value in double quotes
  ~/.claude/skills/verification-loop/SKILL.md: invalid YAML frontmatter at line 3, column 14: Nested mappings are not allowed in compact mappings — description contains an unquoted ":" — wrap the value in double quotes

All five reported problems are addressed: line number corrected, source snippet and caret dropped, message on one line, quoting hint added, path merged.

• pnpm install --frozen-lockfile and pnpm build — clean.
• tsgo --noEmit — exit 0.
• biome check on the 8 changed/added .ts files — Checked 8 files. No fixes applied.
• vitest --run test/frontmatter.test.ts test/skills.test.ts (coding-agent) — 55 passed.
• vitest --run test/harness/skills.test.ts (agent-core) — 11 passed.
• vitest --run test/interactive-mode-diagnostics.test.ts (apps/cli) — 4 passed.
• Guard scripts, all exit 0: check:pinned-deps, check:ts-relative-imports, check:layer-direction, check:ui-layer, check:tui-no-ai, check:coding-agent-entry-freeze, check:contracts-deps-empty, check:derived-compat-only, check:no-provider-dispatch.
• Hint detector probed against ~20 real-world shapes (quoted values, block scalars, 10:30, URLs, # comments, flow collections, nested mappings, CRLF, BOM, non-ASCII) — no false positives or missed cases.

Notes

Diagnostics keep warning severity and the existing parse_failed / invalid_metadata codes, so nothing downstream breaks. Only the message text changes.