[DOCS] Skill live-reload docs do not define whether non-Markdown supporting files trigger reloads
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-dirdirectory 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:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/skills | 96-116, 238-251 | Says Claude Code watches skill directories for file changes and documents supporting files in the same directory |
| https://code.claude.com/docs/en/slash-commands | 96-116, 238-251 | Same wording appears in the parallel skills/slash-commands page |
| https://code.claude.com/docs/en/permissions | 287-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.
3 Comments
Verified against the latest docs; this still appears unresolved.
Issue #60409 Verification
Title: [DOCS] Skill live-reload docs do not define whether non-Markdown supporting files trigger reloads
Issue Date: 2026-05-19
Verification Date: 2026-06-27
Status: RESOLVED
---
Issue Summary
The reporter noted that the "Live change detection" and "Add supporting files" sections of the skills documentation described directory-level live reload but did not define the reload boundary. Specifically, two concerns were raised:
SKILL.mdcontent or to every file under the skill directory.SKILL.md, but did not say whether edits to those non-Markdown files should reload the skill, be picked up only when Claude reads them, or be ignored.The reporter asked for a short explicit clarification under "Live change detection" and on the parallel
/slash-commandspage.---
Verification Results
Claim 1: "Live change detection" reload boundary is ambiguous
Status: RESOLVED
The "Live change detection" section now includes a Note that explicitly defines the reload boundary. At https://code.claude.com/docs/en/skills#live-change-detection, line 130-132:
This directly answers the first concern by stating unambiguously that only
SKILL.mdtext changes trigger the live reload path.Verdict: The reload boundary is now explicitly defined. Any change to a file other than
SKILL.mddoes not go through the live reload path.---
Claim 2: Supporting-file behavior is not explained
Status: RESOLVED
The same Note ("Live change detection covers
SKILL.mdtext only") implies, by virtue of stating that onlySKILL.mdtext triggers live reload, that all other files in the skill directory — including the templates, examples, scripts, and reference documents the page encourages — do not trigger a skill reload.The "Add supporting files" section at https://code.claude.com/docs/en/skills#add-supporting-files, line 291-313, separately explains how those supporting files are picked up:
So the two pieces together — the Note scoping reload to
SKILL.mdtext only, and the "Add supporting files" section explaining the on-demand reference model — provide the explicit answer the reporter was asking for: non-Markdown supporting files do not trigger a skill reload; they are read on demand when the skill references them.Verdict: The behavior is now documented, though it is split between the "Live change detection" Note and the "Add supporting files" section rather than consolidated into a single sentence. The information a reader needs is present.
---
Claim 3: Parallel
/slash-commandspage has the same ambiguityStatus: N/A — Page merged
There is no separate
/slash-commandspage on code.claude.com. The skills page itself states (line 16):The only remaining
/slash-commandsreference iscode.claude.com/docs/en/agent-sdk/slash-commands, which documents SDK command invocation and is not the same content. No parallel clarification is needed.Verdict: No parallel page exists; the issue is moot.
---
Claim 4:
permissions.mdtable describes--add-dirskills as loading "with live reload" without scopeStatus: RESOLVED (via link to the now-scope-defined skills page)
At https://code.claude.com/docs/en/permissions#skills, line 362:
The table entry still uses the phrase "with live reload" without restating the reload scope, but it now links to the skills page where the scope is explicitly defined. Readers following the link land on a section whose Note spells out the scope (
SKILL.mdtext only).Verdict: The substantive ambiguity is resolved through the linked page.
---
Current State
| Claim | Status |
|-------|--------|
| Live-reload trigger boundary is defined | RESOLVED |
| Supporting-file reload behavior is explained | RESOLVED |
| Parallel
/slash-commandspage exists | N/A (page merged into skills) ||
permissions.mdreload scope | RESOLVED (via link) |---
Suggested Fix
N/A — issue has been resolved.
---
References
SKILL.mdtext only..."--add-dirdirectories linking to the skills page---
Conclusion & Recommendation
Primary Concern: The skills page's "Live change detection" wording was ambiguous about whether non-Markdown supporting files triggered skill reloads.
Resolution Status: RESOLVED
Recommendation: CLOSE
The Note added under "Live change detection" on 2026-05-29 explicitly defines the reload boundary as
SKILL.mdtext only and clarifies the plugin-component reload story. Combined with the existing "Add supporting files" section that explains on-demand reference loading, the documentation now answers both of the reporter's concerns. The parallel/slash-commandspage no longer exists (merged into skills), and thepermissions.mdreload summary links to the now-scope-defined skills page.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.