[BUG] skill description frontmatter not surfaced for ~50% of user-defined skills in system-reminder

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When Claude Code loads user-defined skills from ~/.claude/skills/, it includes
all skill names in the available-skills list but silently drops the description:
value for roughly half of them — showing only the bare name with no routing text.

Example: bash-script/SKILL.md has:

---
name: bash-script
description: Write or review Bash scripts. Use for automation, setup, builds,
local tooling, and data pipelines. Safe, pipe-friendly, and POSIX-aware.
---

But the system-reminder shows only:

• bash-script

While a neighbouring skill (api-and-interface-design) with identical frontmatter
structure gets its description surfaced correctly:

• api-and-interface-design: Design stable APIs and interfaces. ...

Affected: ~14 of 27 skills in one session, ~15 of 27 in another — count varies
slightly between sessions. The same pattern affects user commands and plugin
skills: preflight, quality-review, code-simplify, and claude-md-management:claude-md-improver
also lose their descriptions despite having them in their source files.

The omitted descriptions are the primary routing signal agents use to decide which
skill to invoke. Without them, skill selection degrades to guessing from the name alone.

What Should Happen?

● Every skill with a description: field in its SKILL.md frontmatter should have
that description surfaced in the available-skills list, without exception.

Expected output for all 27 skills:

• bash-script: Write or review Bash scripts. Use for automation, setup,

builds, local tooling, and data pipelines. Safe, pipe-friendly, and POSIX-aware.

• ci-cd-and-automation: Set up or modify CI/CD pipelines. ...
• ...

The description: field is the sole routing mechanism for skill selection —
it tells the agent when to invoke each skill. A skill listed without its
description is effectively invisible to intent-based routing.

Error Messages/Logs

● (none — the harness silently drops descriptions with no warning or log output)

Steps to Reproduce

Start a session with my global config: https://github.com/nothub/dotfiles/tree/e7c8ab9585be0850b8c5da270f7bd5484237230a/.claude

Or alternatively:

● 1. Create at least two skills under ~/.claude/skills/, each with a description:
field in their SKILL.md frontmatter:

~/.claude/skills/skill-a/SKILL.md
---
name: skill-a
description: Do thing A. Use when the user wants A.
---
Content here.

~/.claude/skills/skill-b/SKILL.md
---
name: skill-b
description: Do thing B. Use when the user wants B.
---
Content here.

1. Start a new Claude Code session in any project directory.

1. Observe the available-skills list in the system-reminder injected at

session start.

Expected: both skills appear with their description text.
Actual: one or more skills appear as bare names with no description.

Notes:

• Reproducible with 27 user-defined skills; ~50% lose their descriptions.
• The affected subset varies slightly between sessions.
• All SKILL.md files are structurally identical (same frontmatter keys,

same YAML format, no special characters that would break parsing).

• Verified: the files are read correctly (skill names appear), only the

description value is dropped.

• Claude Code version: 2.1.177

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.177 (Claude Code)

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Other

Additional Information

● I've done an exhaustive file-level analysis. Here's what der Gerät found:

---
Same this session: yes. 14 skills lack descriptions (vs 15 last session). Problem persists
across sessions.

What the files actually look like: All 27 SKILL.md files have correctly-formed frontmatter
with both name: and description: fields. The descriptions are there. Nothing in the files
is broken.

What I ruled out as the cause: Every file-level attribute I could measure shows no
correlation with shown vs hidden:

• Description byte length (both groups span 132–279B, with same lengths in each group)
• File line count
• Modification timestamps (all symlinks share the same mtime; source files show no pattern)
• Inode ordering
• Body structure (H1/H2 headers, presence of ## References section)
• YAML quoting style
• Symlink depth
• Frontmatter fields (tools: only in plugin skills, not local ones)

The pattern extends beyond user skills — 3 commands (code-simplify, preflight,
quality-review) and at least one plugin skill (claude-md-management:claude-md-improver)
also show names only, despite having descriptions in their files.

Most likely cause: This is a Claude Code v2.1.177 harness behavior, not a config issue. The
harness reads all skill names but drops descriptions for a seemingly arbitrary subset. The
slight count change (15 → 14) between sessions suggests the selection isn't purely
deterministic from file content — it likely depends on session context, token budget, or
internal harness state.

The files are fine. There is nothing to fix on the config side. This looks like a harness
bug worth reporting at https://github.com/anthropics/claude-code/issues — the symptom is:
description: frontmatter in SKILL.md is present but not surfaced in the available-skills
list for ~50% of user-defined skills, even though the harness successfully reads the skill
names from the same files.

✻ Brewed for 13m 31s

※ recap: Diagnosing why skill descriptions don't surface in the harness. All 27 SKILL.md
files have correct descriptions but 14 are hidden — files are fine, root cause is in the
harness. Next: file a bug report. (disable recaps in /config)

Additional Information:
Skills are symlinked into ~/.claude/skills/ via a dotfiles manager (reclink)
— each skill directory is a real directory, with SKILL.md as a symlink to the
dotfiles source. Both the symlink target and the resolved file were confirmed
readable and correctly parsed (skill names are successfully loaded from the
same files whose descriptions are dropped).

The affected set is not random-looking but also not explainable by any
observable file property: description length, body structure, file size,
modification time, inode order, and YAML formatting were all checked with
no correlation found.

The issue also affects user commands (commands/*.md) and installed plugin
skills — not only standalone SKILL.md files — suggesting the description
extraction logic is shared across all skill source types.