Skip to content

Reloading Skills Mid-Session in Claude Code

Claude Code can re-scan skill directories mid-session, making edited or newly installed skills available without a restart that discards accumulated context.

Claude Code v2.1.152 added two ways to re-scan skill directories inside a running session: the /reload-skills command and a SessionStart hook that returns reloadSkills: true. Both refresh the set of skills the model can invoke in place, leaving the conversation context untouched. [Source: Claude Code changelog, 2026-05-27]

Two Reload Paths

The two paths differ by who triggers them and when they fire:

Path Who triggers it When it fires
/reload-skills You (or the model) invoke it mid-session After you edit or install a SKILL.md by hand and want it live now
SessionStart hook returning reloadSkills: true A SessionStart hook At session startup or resume, after the hook itself installs skills programmatically

/reload-skills is the manual path for an authoring loop. The reloadSkills: true return is for hooks that fetch, generate, or install skills before the first turn — without it, hook-installed skills would not register until the next launch. [Source: Claude Code changelog, 2026-05-27] The same release lets a SessionStart hook set the session title via hookSpecificOutput.sessionTitle on startup and resume. [Source: Claude Code changelog, 2026-05-27]

Why It Works

Claude Code scans skill directories to build the set of skills the model can invoke. Historically this scan ran once, at launch, so the available-skills set was fixed for the session's lifetime — picking up an edit meant restarting, which discards the conversation transcript, files read into context, the active task list, and any reasoning built up so far. A reload re-runs the directory scan against the live session, swapping in the current on-disk SKILL.md set while leaving the context object intact. The causal win is decoupling capability discovery (a cheap, re-runnable directory scan) from context accumulation (expensive, lost on restart), so editing a skill no longer forces you to pay the context-rebuild cost. [Source: Claude Code changelog, 2026-05-27] This mirrors /reload-plugins, the analogous hot-reload shipped for the plugin layer in v2.1.141. [Source: Claude Code changelog, 2026-05-13]

What a Reload Preserves

A restart loses everything the model has accumulated; a reload keeps it.

  • Preserved: conversation transcript, files already read into context, the active todo/task list, sub-agent results gathered so far, and accumulated reasoning.
  • Refreshed: the set of skills discoverable from the scanned directories — newly added, edited, or removed SKILL.md definitions.

This is what collapses the authoring loop to edit → reload → test inside one session.

When This Backfires

Reloading is not always the better choice over a clean restart:

  • Short sessions with little context — with no accumulated transcript or state to protect, a restart is simpler and removes any risk of a stale registration.
  • Edits that interact with loaded context — the model retains reasoning and tool selections made before the skill set changed; a reloaded or removed skill can leave earlier in-context decisions stale, which a clean restart avoids.
  • Untrusted hook-installed skills — a SessionStart hook that fetches and installs skills from an external source then registers them via reloadSkills: true widens the trust surface, since an installed SKILL.md is model-readable instruction. Auto-installing skills from untrusted input couples external content to the agent's capability set.
  • Debugging skill triggering — when a skill mis-fires, reloading after an edit keeps prior-turn context that can mask whether the fix actually changed behaviour; a clean restart isolates the variable.

Example

Iterating on a skill without leaving the session:

# 1. Edit the skill on disk
.claude/skills/my-skill/SKILL.md   (change the description or body)

# 2. Re-scan skill directories in the running session
/reload-skills

# 3. Test the updated skill immediately — context from steps before the edit is intact

A SessionStart hook that installs a skill and registers it for the same session returns:

{
  "hookSpecificOutput": {
    "reloadSkills": true,
    "sessionTitle": "skill-authoring loop"
  }
}

Key Takeaways

  • /reload-skills re-scans skill directories mid-session; the SessionStart reloadSkills: true return does the same for hook-installed skills at startup or resume. [Source: Claude Code changelog, 2026-05-27]
  • A reload preserves session context (transcript, loaded files, task list) that a restart would discard, collapsing the authoring loop to edit → reload → test.
  • It works by decoupling the cheap directory scan from expensive context accumulation.
  • Prefer a clean restart for short sessions, edits that interact with loaded context, or isolating a trigger-debugging variable.
  • Treat hook-installed skills from untrusted sources as a widened trust surface.
Last reviewed: 2026-05-28 Applies to: claude-code@2.x
Feedback