Why a skill that works in Claude Code silently vanishes in DSH (the exact mechanism, measured on rc.6)

[sjh9714]

A skill can sit on disk, work every day in Claude Code, and be completely absent from DSH's catalog. No error, no log line, the agent just never sees it. We hit this while building a migration tool and traced the mechanism through the rc.6 source. Sharing it here because the failure is invisible by design and the fix is one character.

The mechanism. Claude Code reads SKILL.md frontmatter with a lenient line-based parser, so everything after the first colon becomes the value. DSH hands the same block to the full yaml npm parser as an open object. In spec YAML, a second ": " on a plain scalar line is a syntax error (Nested mappings are not allowed in compact mappings). The parse throws, DSH catches it per skill and moves on. The skill is simply not cataloged.

description: Priority order: check the cache first    # vanishes in DSH, fine in Claude Code
description: 'Priority order: check the cache first'  # fine in both

Colons without a following space (10:30, foo:bar) are safe, that is a valid plain scalar.

Two traps stacked on top.

1. The catalog is snapshotted per session (Skill loader returns 'unknown or no longer available' for skills that exist on disk (session catalog snapshot) #1650). Fixing the frontmatter mid-session changes nothing you can see, you need a new session to re-scan.
2. The scanner follows symlinks with stat semantics, so a symlinked skill behaves exactly like a local one, including this failure. Copying the file will not fix it.

Related upstream discussion, #1401. Full writeup with every safe shape (quoting, block scalars, the no-frontmatter case) is here, https://github.com/sjh9714/dsh-movein/blob/main/docs/skill-vanish.md

If you moved your setup over with dsh-movein, the dry run warns on this shape before anything moves, and the new doctor command (v0.5.0, shipped today) checks skills already inside DSH roots any time,

npx dsh-movein doctor

Until the parser question in #1401 lands on a resolution, detection is the practical answer. Happy to add other vanish shapes to the check if you have hit one.

[zoahdev]

Landed a fix for the exact mechanism you traced:

zoahdev/deepseek-harness@fix/skill-frontmatter-unquoted-colon

parseFrontmatter now catches only the BLOCK_AS_IMPLICIT_KEY YAML error (the "second : on a plain scalar" shape) and falls back to a line-based read — value is everything after the first colon, surrounding quotes stripped — so description: Priority order: check the cache first catalogs instead of vanishing. Genuinely malformed YAML (description: [unclosed) still skips the skill.

The "fix is one character" framing undersells it slightly — the safe fix is the narrow fallback, not changing one character in every author's frontmatter. Your dsh-movein doctor detection still pairs well with this: it catches the shape pre-move, and this patch stops DSH from dropping it post-move.

[sjh9714]

Verified, the approach reads right. Catching only BLOCK_AS_IMPLICIT_KEY and falling back to a line-based read is the correct narrow fix, it repairs the Claude-Code-compatible shape without resurrecting genuinely broken YAML. And fair point on my one-character framing, quoting fixes one file while your fallback fixes the whole class.

Two things from our side.

1. Test vectors. dsh-movein's fixtures cover the shapes we've seen in the wild (unquoted : , single/double-quoted variants, block scalars, no frontmatter at all, colon without a following space). Happy to contribute them as cases for your branch, they live in test/test.mjs and lib/scan.mjs (riskyFrontmatter).

2. Reaching the maintainers. This repo takes no external PRs and has issues disabled, so a fork branch alone may never be seen. Posting the branch link plus the BLOCK_AS_IMPLICIT_KEY analysis into [Bug] skill frontmatter 含「冒号+空格」的 description 未加引号时被静默忽略，catalog 完全无感知 / Skills with colon-containing unquoted description are silently dropped from the catalog #1401 (the canonical thread for this bug) is probably the highest-odds path to upstream adoption, the maintainers have picked community analyses from there before.

Until a fix ships in a release, doctor keeps flagging the shape on rc.6 hosts, so the two layers stay complementary exactly as you said.