Hot-Reload: 10 Questions Answered

1. Mechanics

How does it work?

• Skills are scanned from .claude/skills/ and ~/.claude/skills/ on each invocation
• No file watching daemon - it's on-demand discovery
• Skill files read fresh each time the Skill tool is called

What triggers it?

• Skill tool invocation triggers fresh scan
• User input cycle may also trigger refresh (observed: skill became available after user message)
• No time-based refresh observed

Implementation model (guess):

• Directory listing + file read on skill invocation
• Frontmatter parsed, skill registered in available list
• No caching between invocations (or very short-lived cache)

2. Model/Agent

What model runs skills?

• Same model as parent session (Opus 4.5 in our test)
• Skills are instructions injected into current context, not separate agent

Configurable?

• Not directly for non-forked skills
• With context: fork, still uses same model (see fork QUESTIONS.md)

3. Context

Fresh or inherited?

• Inherited - skill runs in current conversation context
• Skill instructions prepended to next response

What carries over?

• Full conversation history
• All previously read files
• Current working state

4. Tool Access

Default tools:

• All tools available by default (same as current session)

allowed-tools:

• Can restrict with allowed-tools frontmatter
• Format: allowed-tools: Read,Bash,Glob (comma-separated)
• YAML list format also supported (2.1.0 feature)

5. Failure Modes

Syntax errors:

• Bad YAML frontmatter doesn't crash - skill still loads
• Missing required fields (name, description) - skill may not be discovered
• Skill with no frontmatter - untested but likely loads as raw instructions

Missing skill:

• Returns "Unknown skill: X" error immediately
• Doesn't affect parent context

Error in skill execution:

• Same as any tool error - surfaces in conversation
• Skill instructions still visible in context

6. Performance

Latency:

• Near-instant for modification detection
• No observable cold start penalty
• Scan is fast (directory listing + single file read)

Token cost:

• Skill instructions added to context each invocation
• Repeated invocations accumulate if instructions are long
• Consider context: fork for verbose skills

7. Feature Interactions

With context: fork:

• Can combine: context: fork in hot-reloaded skill works
• Forked skills also hot-reload

With agent field:

• Untested (feature #3)

With hooks:

• Untested (2.1.0 added hooks in skill frontmatter)

8. Edge Cases Tested

Scenario	Result
New skill created mid-session	Works (after user interaction cycle)
Skill modified mid-session	Immediate detection on next invoke
Skill deleted mid-session	Immediate - "Unknown skill"
Bad YAML frontmatter	Lenient - still loads
Skill in .claude/skills/	Works (project-local)
Skill in ~/.claude/skills/	Not tested this session

9. Security

Trust boundary:

• Skills have same permissions as main session
• No sandboxing for non-forked skills
• allowed-tools can restrict but skill author sets this

Malicious skill risks:

• Could read sensitive files
• Could execute bash commands
• Same risk as any Claude Code operation
• Mitigated by permission system

10. Debugging

How to see what's happening:

• Skill instructions visible in response context
• Tool calls visible in conversation
• No separate skill execution log

Adding debug output:

• Add debug instructions to skill itself
• "Before executing, print your interpretation of..."

Transcript visibility:

• Full visibility for non-forked skills
• Forked skills return summary only

Use Cases: Skill Hot-Reload

Feature: Skills in ~/.claude/skills or .claude/skills are immediately available without restarting the session

---

Core Value Proposition

Hot-reload eliminates the restart tax. Before this, iterating on a skill meant:

1. Edit skill file
2. Exit claude
3. Restart claude
4. Re-establish context
5. Test skill
6. Repeat

Now it's just: edit → invoke. The session stays warm.

---

Use Cases

1. Skill Development & Iteration

Scenario: You're building a new skill and need to refine the prompt iteratively.

Without hot-reload: Each tweak requires a full restart, losing conversation context and flow state.

With hot-reload: Edit the SKILL.md in your editor, invoke again, see results immediately. Stay in flow.

Example workflow:

> /my-new-skill         # v1 - too verbose
[edit SKILL.md to be more concise]
> /my-new-skill         # v2 - better but wrong format
[edit SKILL.md to fix format]
> /my-new-skill         # v3 - perfect

---

2. Live Customization During Work

Scenario: Mid-task, you realize you need a skill that doesn't exist yet.

Example: You're debugging a complex issue and wish you had a skill that greps for error patterns and summarizes them.

> "create a skill called error-hunter that finds all ERROR/WARN/FATAL in logs"
[Claude creates .claude/skills/error-hunter/SKILL.md]
> /error-hunter         # immediately available

No context switch. No restart. The skill exists when you need it.

---

3. Team Skill Sharing (Project-Local)

Scenario: Team has project-specific workflows. Someone adds a new skill to .claude/skills/ and pushes.

git pull  # teammate added new skill

In your running Claude session:

> /new-team-skill       # just works

No restart needed to pick up team additions.

---

4. A/B Testing Skill Variants

Scenario: Trying to find the best prompt for a skill.

# Start with version A
> /code-review
[results are okay but miss security issues]

# Edit skill to add security focus
> /code-review          # now catches security issues

# Edit again to reduce verbosity
> /code-review          # concise + security aware

Rapid iteration without losing your code review context.

---

5. Emergency Skill Creation

Scenario: You're in a long session with complex context. You realize you need a repeatable workflow NOW.

Before hot-reload: "I'll make that skill later" (you won't)

With hot-reload: Create it immediately, use it immediately, refine if needed.

---

6. Skill Debugging

Scenario: A skill isn't behaving as expected.

Add debug instructions to the skill:

## Debug Mode
Before executing, print:
- What context you see
- What tools you plan to use
- Your interpretation of the task

Invoke, see what's happening, fix, remove debug, invoke again. All in one session.

---

7. Context-Aware Skill Evolution

Scenario: You're working on a specific part of the codebase and want your skill to adapt.

Start with generic skill:

# Code Helper
Help with code questions.

Mid-session, specialize it:

# Code Helper
You're working in the authentication module.
Focus on: JWT handling, session management, OAuth flows.
Ignore: unrelated modules.

The skill evolves with your work.

---

Anti-Patterns (When NOT to Use)

1. Global skills that should be stable - Don't hot-reload production workflows. Version them properly.

2. Skills with side effects - If a skill does something destructive, don't iterate carelessly.

3. Multi-user environments - If others depend on the skill, don't change it mid-session without coordination.

---

Technical Notes

• Hot-reload scans on skill invocation, not continuously
• Project-local (.claude/skills/) overrides global (~/.claude/skills/)
• Proper frontmatter (name, description) required for discovery
• The Skill tool's available list refreshes on user interaction cycles