Skill catalog descriptions intermittently missing from system prompt (frontmatter on disk is correct)

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?

Summary

The "available skills" list injected into the system prompt at session start
sometimes omits a skill's description: entirely (rendered as a bare
- skill-name with nothing after the colon), even though the skill's
SKILL.md frontmatter on disk has a complete, valid description: field.
Since the model only sees the catalog text (not the files), this silently
breaks natural-language auto-triggering for the affected skills — they only
work when invoked by explicit name.

Environment

• Standalone Windows binary install (not npm), ~/.local/bin/claude, ~234MB,

file dated 2026-06-27. claude --version not captured in this report —
blocked by an unrelated local shell policy on my side; happy to supply it
on request.

• Windows 11, skills sourced from: plain ~/.claude/skills/<name>/SKILL.md,

plugin-provided skills (via ~/.claude/plugins/marketplaces/...), and a
Windows junction into an external directory.

Reproduction / evidence

Across 3 separate sessions on the same machine, same ~/.claude config,
I compared each skill's description visibility in the system-prompt catalog
against its actual SKILL.md frontmatter (read directly from disk):

• 13 skills (spanning multiple unrelated sources — a plugin family, plain

standalone skills, and a junctioned external skill) showed a blank
description in the catalog while their on-disk frontmatter was fully
populated and valid YAML.

• The specific set is NOT stable across sessions: ponytail and

industrial-brutalist-ui were blank in session 1, then had full
descriptions in session 2. minimalist-ui had a full description in
session 1, then was blank in session 3. Most others (11/13) stayed
consistently blank across all 3 sessions.

• Ruled out as causes: plugin enable/disable state in settings.json

(enabledPlugins — the affected plugin was never listed there in its
entire git history, yet worked reliably for weeks before this was
noticed), directory type (regular dir vs. junction — both regular dirs
and a junction appear on both sides of the working/broken split),
YAML style (description: text single-line vs. description: > folded
block — both styles appear on both sides), and description length (a
skill with a very long single-line description renders fully elsewhere).

• Manually invoking an affected skill by exact name works correctly and

returns its full, correct instructions — confirming the file itself is
never corrupted, only the catalog's rendering of it in that session.

Impact

Any skill whose description drops out of the catalog for a given session
becomes invisible to the model's own judgment for that session — it cannot
be auto-triggered by natural language matching its stated triggers, only by
being named explicitly. This is silent (no error, no warning) and
intermittent, so it's easy to mistake for "the skill doesn't work" rather
than "the catalog lost its metadata this session."

What would help

• Any pointer to how the system-prompt skill catalog is assembled (e.g. is

there a token/length budget that silently truncates description fields
under certain conditions, or a caching layer that can serve a stale/empty
entry) would let me build a tighter, deterministic repro.

• Happy to provide the exact skill list, full session transcripts (redacted

as needed), or run additional diagnostics on request.

What Should Happen?

Summary

The "available skills" list injected into the system prompt at session start
sometimes omits a skill's description: entirely (rendered as a bare
- skill-name with nothing after the colon), even though the skill's
SKILL.md frontmatter on disk has a complete, valid description: field.
Since the model only sees the catalog text (not the files), this silently
breaks natural-language auto-triggering for the affected skills — they only
work when invoked by explicit name.

Environment

• Standalone Windows binary install (not npm), ~/.local/bin/claude, ~234MB,

file dated 2026-06-27. claude --version not captured in this report —
blocked by an unrelated local shell policy on my side; happy to supply it
on request.

• Windows 11, skills sourced from: plain ~/.claude/skills/<name>/SKILL.md,

plugin-provided skills (via ~/.claude/plugins/marketplaces/...), and a
Windows junction into an external directory.

Reproduction / evidence

Across 3 separate sessions on the same machine, same ~/.claude config,
I compared each skill's description visibility in the system-prompt catalog
against its actual SKILL.md frontmatter (read directly from disk):

• 13 skills (spanning multiple unrelated sources — a plugin family, plain

standalone skills, and a junctioned external skill) showed a blank
description in the catalog while their on-disk frontmatter was fully
populated and valid YAML.

• The specific set is NOT stable across sessions: ponytail and

industrial-brutalist-ui were blank in session 1, then had full
descriptions in session 2. minimalist-ui had a full description in
session 1, then was blank in session 3. Most others (11/13) stayed
consistently blank across all 3 sessions.

• Ruled out as causes: plugin enable/disable state in settings.json

(enabledPlugins — the affected plugin was never listed there in its
entire git history, yet worked reliably for weeks before this was
noticed), directory type (regular dir vs. junction — both regular dirs
and a junction appear on both sides of the working/broken split),
YAML style (description: text single-line vs. description: > folded
block — both styles appear on both sides), and description length (a
skill with a very long single-line description renders fully elsewhere).

• Manually invoking an affected skill by exact name works correctly and

returns its full, correct instructions — confirming the file itself is
never corrupted, only the catalog's rendering of it in that session.

Impact

Any skill whose description drops out of the catalog for a given session
becomes invisible to the model's own judgment for that session — it cannot
be auto-triggered by natural language matching its stated triggers, only by
being named explicitly. This is silent (no error, no warning) and
intermittent, so it's easy to mistake for "the skill doesn't work" rather
than "the catalog lost its metadata this session."

What would help

• Any pointer to how the system-prompt skill catalog is assembled (e.g. is

there a token/length budget that silently truncates description fields
under certain conditions, or a caching layer that can serve a stale/empty
entry) would let me build a tighter, deterministic repro.

• Happy to provide the exact skill list, full session transcripts (redacted

as needed), or run additional diagnostics on request.

Error Messages/Logs

Steps to Reproduce

Summary

The "available skills" list injected into the system prompt at session start
sometimes omits a skill's description: entirely (rendered as a bare
- skill-name with nothing after the colon), even though the skill's
SKILL.md frontmatter on disk has a complete, valid description: field.
Since the model only sees the catalog text (not the files), this silently
breaks natural-language auto-triggering for the affected skills — they only
work when invoked by explicit name.

Environment

• Standalone Windows binary install (not npm), ~/.local/bin/claude, ~234MB,

file dated 2026-06-27. claude --version not captured in this report —
blocked by an unrelated local shell policy on my side; happy to supply it
on request.

• Windows 11, skills sourced from: plain ~/.claude/skills/<name>/SKILL.md,

plugin-provided skills (via ~/.claude/plugins/marketplaces/...), and a
Windows junction into an external directory.

Reproduction / evidence

Across 3 separate sessions on the same machine, same ~/.claude config,
I compared each skill's description visibility in the system-prompt catalog
against its actual SKILL.md frontmatter (read directly from disk):

• 13 skills (spanning multiple unrelated sources — a plugin family, plain

standalone skills, and a junctioned external skill) showed a blank
description in the catalog while their on-disk frontmatter was fully
populated and valid YAML.

• The specific set is NOT stable across sessions: ponytail and

industrial-brutalist-ui were blank in session 1, then had full
descriptions in session 2. minimalist-ui had a full description in
session 1, then was blank in session 3. Most others (11/13) stayed
consistently blank across all 3 sessions.

• Ruled out as causes: plugin enable/disable state in settings.json

(enabledPlugins — the affected plugin was never listed there in its
entire git history, yet worked reliably for weeks before this was
noticed), directory type (regular dir vs. junction — both regular dirs
and a junction appear on both sides of the working/broken split),
YAML style (description: text single-line vs. description: > folded
block — both styles appear on both sides), and description length (a
skill with a very long single-line description renders fully elsewhere).

• Manually invoking an affected skill by exact name works correctly and

returns its full, correct instructions — confirming the file itself is
never corrupted, only the catalog's rendering of it in that session.

Impact

Any skill whose description drops out of the catalog for a given session
becomes invisible to the model's own judgment for that session — it cannot
be auto-triggered by natural language matching its stated triggers, only by
being named explicitly. This is silent (no error, no warning) and
intermittent, so it's easy to mistake for "the skill doesn't work" rather
than "the catalog lost its metadata this session."

What would help

• Any pointer to how the system-prompt skill catalog is assembled (e.g. is

there a token/length budget that silently truncates description fields
under certain conditions, or a caching layer that can serve a stale/empty
entry) would let me build a tighter, deterministic repro.

• Happy to provide the exact skill list, full session transcripts (redacted

as needed), or run additional diagnostics on request.

Claude Model

Not sure / Multiple models

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

1.0.123

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

PowerShell

Additional Information

Summary

The "available skills" list injected into the system prompt at session start
sometimes omits a skill's description: entirely (rendered as a bare
- skill-name with nothing after the colon), even though the skill's
SKILL.md frontmatter on disk has a complete, valid description: field.
Since the model only sees the catalog text (not the files), this silently
breaks natural-language auto-triggering for the affected skills — they only
work when invoked by explicit name.

Environment

• Standalone Windows binary install (not npm), ~/.local/bin/claude, ~234MB,

file dated 2026-06-27. claude --version not captured in this report —
blocked by an unrelated local shell policy on my side; happy to supply it
on request.

• Windows 11, skills sourced from: plain ~/.claude/skills/<name>/SKILL.md,

plugin-provided skills (via ~/.claude/plugins/marketplaces/...), and a
Windows junction into an external directory.

Reproduction / evidence

Across 3 separate sessions on the same machine, same ~/.claude config,
I compared each skill's description visibility in the system-prompt catalog
against its actual SKILL.md frontmatter (read directly from disk):

• 13 skills (spanning multiple unrelated sources — a plugin family, plain

standalone skills, and a junctioned external skill) showed a blank
description in the catalog while their on-disk frontmatter was fully
populated and valid YAML.

• The specific set is NOT stable across sessions: ponytail and

industrial-brutalist-ui were blank in session 1, then had full
descriptions in session 2. minimalist-ui had a full description in
session 1, then was blank in session 3. Most others (11/13) stayed
consistently blank across all 3 sessions.

• Ruled out as causes: plugin enable/disable state in settings.json

(enabledPlugins — the affected plugin was never listed there in its
entire git history, yet worked reliably for weeks before this was
noticed), directory type (regular dir vs. junction — both regular dirs
and a junction appear on both sides of the working/broken split),
YAML style (description: text single-line vs. description: > folded
block — both styles appear on both sides), and description length (a
skill with a very long single-line description renders fully elsewhere).

• Manually invoking an affected skill by exact name works correctly and

returns its full, correct instructions — confirming the file itself is
never corrupted, only the catalog's rendering of it in that session.

Impact

Any skill whose description drops out of the catalog for a given session
becomes invisible to the model's own judgment for that session — it cannot
be auto-triggered by natural language matching its stated triggers, only by
being named explicitly. This is silent (no error, no warning) and
intermittent, so it's easy to mistake for "the skill doesn't work" rather
than "the catalog lost its metadata this session."

What would help

• Any pointer to how the system-prompt skill catalog is assembled (e.g. is

there a token/length budget that silently truncates description fields
under certain conditions, or a caching layer that can serve a stale/empty
entry) would let me build a tighter, deterministic repro.

• Happy to provide the exact skill list, full session transcripts (redacted

as needed), or run additional diagnostics on request.

SKILL.md files: 156, defects: 1
... (the 4 of 15 collisions whose copies do not agree on a description)
COLLISION evo-loop           2 files  (descriptions DIFFER)
COLLISION godmode-evolution  2 files  (descriptions DIFFER)
COLLISION access             3 files  (descriptions DIFFER)
COLLISION configure          3 files  (descriptions DIFFER)
collisions: 15

access
    [Manage Discord channel access, approve pairings, ...]   .../external_plugins/discord/skills/access/SKILL.md
    [Manage iMessage channel access, approve pairings, ...]  .../external_plugins/imessage/skills/access/SKILL.md
    [Manage Telegram channel access, approve pairings, ...]  .../external_plugins/telegram/skills/access/SKILL.md

// skill-name-collisions.js
const fs = require('node:fs'), os = require('node:os'), path = require('node:path');

const roots = process.argv.slice(2).length ? process.argv.slice(2) : [
  path.join(os.homedir(), '.claude', 'skills'),
  path.join(os.homedir(), '.claude', 'plugins', 'marketplaces'),
  path.join(process.cwd(), '.claude', 'skills'),
];

const found = [];
const walk = (d, depth) => {
  if (depth > 8) return;
  let es; try { es = fs.readdirSync(d, { withFileTypes: true }); } catch (e) { return; }
  for (const e of es) {
    const p = path.join(d, e.name);
    if (e.isDirectory() || e.isSymbolicLink()) {
      let st; try { st = fs.statSync(p); } catch (x) { continue; }   // dead junction
      if (st.isDirectory()) walk(p, depth + 1);
    } else if (e.name === 'SKILL.md') found.push(p);
  }
};
for (const r of roots) walk(r, 0);

const chop = s => (s.endsWith('\r') ? s.slice(0, -1) : s);
const trimEnd = s => s.replace(/[ \t]+$/, '');

const by = new Map();
let defects = 0;
for (const f of found) {
  const buf = fs.readFileSync(f);
  const bom = buf.length > 2 && buf[0] === 0xEF && buf[1] === 0xBB && buf[2] === 0xBF;
  const lines = buf.slice(bom ? 3 : 0).toString('utf8').split('\n').map(chop);

  const open = !bom && lines.length > 0 && trimEnd(lines[0]) === '---';
  const close = open ? lines.findIndex((l, i) => i > 0 && trimEnd(l) === '---') : -1;
  const block = close > 0 ? lines.slice(1, close) : [];

  const get = k => {
    const idx = [];
    block.forEach((l, i) => { if (l.startsWith(k + ':')) idx.push(i); });
    if (!idx.length) return { n: 0, v: '', full: '' };
    const at = idx[idx.length - 1];
    const v = block[at].slice(k.length + 1).trim();
    // A block scalar or a wrapped quoted scalar puts the text on the following
    // indented lines. Comparing only the same-line value would call two
    // descriptions identical whenever both happen to start with ">".
    const body = [];
    if (v === '' || v[0] === '>' || v[0] === '|') {
      for (let i = at + 1; i < block.length; i++) {
        if (/^[ \t]+\S/.test(block[i])) body.push(block[i].trim());
        else if (block[i].trim() === '') continue;
        else break;
      }
    }
    const full = body.length ? body.join(' ') : v;
    return { n: idx.length, v, full, at };
  };
  const name = get('name').v.replace(/^["'](.*)["']$/, '$1') || path.basename(path.dirname(f));
  const d = get('description');

  const why = [];
  if (bom) why.push('UTF-8 BOM before ---');
  else if (!open) why.push('no --- on line 1');
  else if (close < 0) why.push('opening --- has no closing ---');
  if (open && close > 0) {
    if (d.n === 0) why.push('no description key');
    if (d.n > 1) why.push(d.n + ' description keys');
    // An empty value is only a defect when no indented body follows it: a block
    // scalar and a wrapped quoted scalar both put the text on later lines.
    if (d.n >= 1 && d.v === '') {
      // d.at is the key that actually won, which is the LAST one; findIndex here
      // would inspect the first and misjudge a file with duplicate keys.
      const next = block.slice(d.at + 1).find(l => l.trim() !== '');
      if (!next || !/^[ \t]/.test(next)) why.push('description key with no value');
      // An indented "key: value" under description is a nested mapping, not a
      // wrapped scalar, so the description loads as an object and renders blank.
      else if (/^[ \t]+[A-Za-z0-9_-]+:([ \t]|$)/.test(next)) {
        why.push('description is a nested mapping, not text');
      }
    }
    if (d.n >= 1 && /^[^"'>|]*:[ \t]/.test(d.v)) why.push('unquoted ": " in the value');
    if (block.some(l => l.indexOf('\t') >= 0)) why.push('tab inside the frontmatter');
    if (block.some(l => l.indexOf(String.fromCharCode(160)) >= 0)) why.push('non-breaking space inside the frontmatter');
  }
  if (why.length) { defects++; console.log('DEFECT    ' + name + '  ' + f + '  (' + why.join('; ') + ')'); }

  if (!by.has(name)) by.set(name, []);
  by.get(name).push({ f, d: d.full });
}

console.log('SKILL.md files: ' + found.length + ', defects: ' + defects);
let collisions = 0;
for (const [name, arr] of by) {
  if (arr.length < 2) continue;
  collisions++;
  const differ = new Set(arr.map(a => a.d)).size > 1;
  console.log('COLLISION ' + name + '  ' + arr.length + ' files' + (differ ? '  (descriptions DIFFER)' : ''));
  for (const a of arr) console.log('    [' + (a.d.slice(0, 50) || 'BLANK') + '] ' + a.f);
}
console.log('collisions: ' + collisions);
process.exit(defects + collisions ? 1 : 0);