›_ Claude Code Issues
Claude Code Issues / #68677

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

Status Fixed / completed
Reported on v2.1.177
Maintainer reply None cached
Workaround ✓ Mentioned in thread ↓
Activity 5 comments · opened Jun 15, 2026 · closed Jun 17, 2026

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.

View original on GitHub ↗

5 Comments

github-actions[bot] · 4 months ago

Found 2 possible duplicate issues:

  1. https://github.com/anthropics/claude-code/issues/57515
  2. https://github.com/anthropics/claude-code/issues/24237

This issue will be automatically closed as a duplicate in 3 days.

  • If your issue is a duplicate, please close it and 👍 the existing issue instead
  • To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

nothub · 4 months ago

Stop the auto-closure. The 2 linked issues were both closed.

yurukusa · 4 months ago

This reproduces a documented-only-in-the-binary budget mechanism, not random loss. I grepped the bundled binary (@anthropic-ai/claude-code-linux-x64/claude, current install) and there are two internal settings that govern the available-skills listing:

  • skillListingBudgetFraction (default 0.01) — the fraction of the context window allotted to the entire skills listing.
  • skillListingMaxDescChars (default 1536) — the per-skill cap on the description: text (excess is silently truncated).

So the listing has a hard total budget (~1% of the context window). When the sum of the surfaced descriptions would exceed that budget, descriptions get dropped for the skills that don't fit — you keep the bare - name, but the routing text is gone. That matches your symptoms exactly:

  • "~14 of 27 / ~15 of 27" — the cutoff lands wherever the running total crosses the ~1% budget, so roughly half surface and half don't once you have enough skills.
  • "count varies slightly between sessions" — the budget is a fraction of the context window, and how much room is left for the listing shifts with whatever else is in context that session. Same skills, different remaining budget → a different cutoff.
  • It hits user commands and plugin skills too, because they share the same listing budget.

This is a testable prediction rather than a guess — you can confirm it from your side:

  • Shorten descriptions or prune skills → more of them should surface (the total drops back under budget).
  • Add skills / lengthen descriptions → fewer surface.
  • The skills that do keep their description should keep the full text (up to 1536 chars); the loss is all-or-nothing per skill at the budget boundary, not uniform truncation.

Both keys are settable in settings.json, so two workarounds until this is addressed upstream:

  1. Raise skillListingBudgetFraction (and/or skillListingMaxDescChars) to fit more — trade-off: a larger listing is re-sent every turn, so context cost goes up.
  2. Cost-neutral: put the highest-signal routing words at the start of each description, keep descriptions short, and remove skills you don't use, so the whole listing fits under the ~1% budget.

A genuinely good fix would be to expose this as documented config and/or let a skill mark itself high-priority so its description is never the one dropped — right now the drop order isn't author-controllable. (Defaults verified by inspecting the current bundled binary: skillListingMaxDescChars ?? 1536, skillListingBudgetFraction ?? 0.01. I'm not asserting any specific routing/firing-rate numbers — only the budget mechanism that drops the descriptions.)

nothub · 3 months ago

This was actually fixed by setting skillListingBudgetFraction.
Claude drops the least used skills descriptions silently, but /doctor actually can reveal the info.

github-actions[bot] · 1 month ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Related Claude Code issues

Matched on shared title terms, labels, topic and reported release — ranked so issues with real discussion come first.

Browse by topic

Browse all Claude Code issue topics →