[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-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:

| 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.