Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Skill live-reload docs do not define whether non-Markdown supporting files trigger reloads

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Root Cause

A. The reload trigger is ambiguous

Because the wording is directory-level, readers cannot tell whether live reload applies only to SKILL.md / Markdown skill content or to every file under the skill directory.

RAW_BUFFERClick to expand / collapse

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

"Live change detection" and "Add supporting files"

Current Documentation

The docs currently say:

Claude Code watches skill directories for file changes. Adding, editing, or removing a skill under ~/.claude/skills/, the project .claude/skills/, or a .claude/skills/ inside an --add-dir directory takes effect within the current session without restarting.

The SKILL.md contains the main instructions and is required. Other files are optional and let you build more powerful skills: templates for Claude to fill in, example outputs showing the expected format, scripts Claude can execute, or detailed reference documentation.

Skills can include multiple files in their directory. This keeps SKILL.md focused on the essentials while letting Claude access detailed reference material only when needed.

What's Wrong or Missing?

The page says Claude Code watches skill directories for file changes, but it does not define the reload boundary.

A. The reload trigger is ambiguous

Because the wording is directory-level, readers cannot tell whether live reload applies only to SKILL.md / Markdown skill content or to every file under the skill directory.

B. Supporting-file behavior is not explained

The same page encourages storing templates, examples, scripts, and other reference files next to SKILL.md, but it does not say whether edits to those non-Markdown files should reload the skill, be picked up only when Claude reads them later, or be ignored by the live-reload path.

This matters for skill directories that contain generated or build-produced files alongside the main skill definition.

Suggested Improvement

Add a short clarification under "Live change detection" and mirror it on the parallel /slash-commands page.

The clarification should explicitly state:

  • which files count as skill-definition changes for live reload
  • that directory-wide non-Markdown file changes do not trigger a skill reload
  • how supporting files are picked up instead when a skill references them

Example wording:

Claude Code live-reloads Markdown skill-definition files in .claude/skills/. Supporting non-Markdown files in the skill directory, such as scripts or generated artifacts, do not trigger a skill reload. Claude reads supporting files on demand when the skill references them.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageLine(s)Context
https://code.claude.com/docs/en/skills96-116, 238-251Says Claude Code watches skill directories for file changes and documents supporting files in the same directory
https://code.claude.com/docs/en/slash-commands96-116, 238-251Same wording appears in the parallel skills/slash-commands page
https://code.claude.com/docs/en/permissions287-290--add-dir skills are described as loading "with live reload" without defining reload scope

Total scope: 3 pages affected

Version context: This ambiguity surfaced while reviewing the v2.1.144 release notes.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#response parsing#generation error#database connection#vector store#embedding generation

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING