claude-code - ✅(Solved) Fix [BUG] ~/.claude/skills/ directory deleted on first run after 2.1.113→2.1.114 update (native binary migration)[BUG] [1 pull requests]

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…

Error Message

Warn the user if a migration is about to make destructive changes to their config directory

Error Messages/Logs

Note: The deletion appears to happen silently during first-run initialization of the new native binary. No error is shown to the user. The skills simply vanish.

PR fix notes

PR #83: feat: bkit v2.1.9 — CC v2.1.114→v2.1.116 response + 4 ENH + 100% Docs=Code sync

Description (problem / solution / changelog)

Summary

bkit v2.1.9 is a maintenance-and-response release targeting Claude Code CLI versions v2.1.114 → v2.1.116 (released 2026-04-18 to 2026-04-20). The release delivers 4 acceptance-gated ENH items (253/254/259/263), positive drift of 2 v2.1.10 roadmap items (ENH-264 infrastructure + ENH-265 full implementation), and a 100% Docs=Code synchronization across all user-facing documentation.

  • 74 consecutive compatible releases (v2.1.34 → v2.1.116; v2.1.115 skipped, 8th skipped release in the v2.1.x series).
  • Shipping QA: Match Rate 100% (15/15 acceptance criteria), Coverage 90.3%, P0 Blockers 0, Regression 0, 28 L1–L5 test cases (22 PASS / 4 environmental SKIP / 0 FAIL).
  • Runtime behavior additions are small and well-scoped (1 new lib function, 1 new env-var branch, 2 new hook-block call sites). Most of the diff is documentation, JSDoc version sync, and CC-recommended-version string propagation — this is intentional for a response release.

What actually changed at runtime (the honest summary)

CategoryFilesRuntime impact
Pure Markdown documentation (README, CHANGELOG, CUSTOMIZATION-GUIDE, AI-NATIVE-DEVELOPMENT, bkit-system/, docs/)28None (human-readable only)
`agents/*.md` (17 agents, CC recommended version string only)17Agent prompt context only (no logic change)
`lib/**/*.js` JSDoc `@version 1.6.0 → 2.0.0` single-line sync32None (comment-only)
`scripts/config-change-handler.js` (Defense-in-Depth inline comments)1None (comment-only; `DANGEROUS_PATTERNS` array unchanged)
`bkit.config.json` (`performance.promptCaching1h` declaration block)1None by itself (declaration only; code reads `process.env` directly)
Config JSON metadata (`plugin.json`, `marketplace.json`, `hooks.json`)3None (version/description)
Actual runtime code additions4Yes — see below

The 4 files with real runtime behavior changes

  1. `lib/core/io.js` (+35 lines) — New exported function `outputBlockWithContext(reason, alternatives, hookEvent)`. Enables structured block responses via CC v2.1.110+ `hookSpecificOutput.additionalContext`. Dormant unless called.
  2. `scripts/unified-bash-pre.js` (+111 lines) — ENH-264: `ALTERNATIVES_BY_PATTERN` map (rm -rf, git reset --hard, chmod 777, dd if=, sudo rm -rf, etc.) + `getAlternativesForCommand()` helper + 2 call sites: deployment-phase detection (line 144) and QA-phase detection (line 183). General Bash danger coverage remains delegated to CC runtime Layer 1 (v2.1.113 #14/#15/#16 + v2.1.116 S1); full general-purpose coverage is scheduled for v2.1.10.
  3. `hooks/startup/session-context.js` (+15 lines) — SessionStart `additionalContext` version string v2.1.8 → v2.1.9, architecture counts (37/32/19 → 39/36/21 + 2 MCP Servers), CC recommended version (v2.1.111+/72 consecutive → v2.1.116+/74 consecutive), new ENH-265 branch that reads `process.env.ENABLE_PROMPT_CACHING_1H` and emits either `✅ enabled` or `⚠️ disabled — set ...` guidance with the operational-guide link.
  4. `bkit.config.json` (+10 lines) — Declares `performance.promptCaching1h` (`recommended: true`, `envVar: ENABLE_PROMPT_CACHING_1H`, `ccMinVersion: v2.1.108`, operator note). Reference-only; the hook reads the env var directly.

ENH details

Shipped at acceptance (4 ENH, Plan-scoped)

ENHTypeSummary
ENH-253Docs + manual verification`docs/03-analysis/zero-script-qa-fork-v2116-verification.md`. Manual reproduction of GitHub #51165 (`context: fork` + `disable-model-invocation` failure) on macOS. Non-reproduction on darwin 24.6.0. bkit's sole `context: fork` skill (`zero-script-qa`, 1/39) operates normally; bkit uses `disable-model-invocation` 0/39 so the combination case is N/A. ENH-196/202 investment protected.
ENH-254Code comment + new doc`scripts/config-change-handler.js:17-29` Layer-1/Layer-2 inline comment block (no array change). New `docs/03-analysis/security-architecture.md` (5 sections): layer definitions, attack-vector matrix, user-responsibility clause ("do NOT rely on either layer alone"), change history, code references.
ENH-259Docs`CUSTOMIZATION-GUIDE.md` new ⚠️ Important Notices section + `README.md` Custom Skills warning bullet for GitHub #51234 (`/.claude/skills/` silent deletion on CC v2.1.113+ first-run). bkit itself is unaffected (uses `${CLAUDE_PLUGIN_ROOT}/skills/`); user custom skills at `/.claude/skills/` are at risk. Backup/restore commands (full + selective) + recommended plugin-bundle path guidance.
ENH-263Code + docs (Docs=Code)15-file architectural-count + CC-recommended-version correction. `@version 1.6.0` in `lib/` → 0 matches (ENH-270 acceptance). 17 agents bulk updated to v2.1.116+.

Positive drift from v2.1.10 roadmap (Plan §4.1)

ENHTypeSummary
ENH-264Code (infrastructure + partial logic)New `lib/core/io.js:outputBlockWithContext` + `scripts/unified-bash-pre.js` alternatives map + 2 phase-specific call sites. General-Bash coverage remains on the v2.1.10 roadmap — v2.1.9 is infrastructure-only for the general case.
ENH-265Code (complete)`hooks/startup/session-context.js:236-241` env-var branch + `bkit.config.json` declaration + `docs/03-analysis/prompt-caching-optimization.md` operational guide. Fully shipped; requires `ENABLE_PROMPT_CACHING_1H=1` in the user's shell before launching Claude Code to activate (CC v2.1.108+).

Bonus

ENHTypeSummary
ENH-266Docs10 additional files synced to v2.1.9 baseline (README, CUSTOMIZATION-GUIDE, AI-NATIVE-DEVELOPMENT, bkit-system/*). Architecture counts normalized to 39 Skills / 36 Agents / 43 Scripts / 101 Lib modules (11 subdirs) / 21 Hook Events / 18 Templates / 4 Output Styles / 2 MCP Servers.
ENH-270Code cleanup`grep -rn "@version 1.6.0" lib/` = 0 matches (ENH-263 acceptance criterion met).

Runtime-verified architecture baseline (measured 2026-04-21)

ComponentCountVerification
Skills3939/39 `effort` frontmatter; 1/39 `context: fork` (`zero-script-qa`); 0/39 `disable-model-invocation`, `paths`, `monitors`
Agents3613 opus / 21 sonnet / 2 haiku; 2 low / 21 medium / 13 high / 0 xhigh effort; 20/36 `disallowedTools` (55.6%); 0/36 `initialPrompt`, `hooks:`
Scripts4343/43 `node --check` clean
Lib modules10111 subdirectories: audit, context, control, core, intent, pdca, qa, quality, task, team, ui (no `adapters` subdir — prior docs myth corrected)
Hook Events21`hooks/hooks.json` keys
Templates18`templates/*.md`
Output Styles4`output-styles/*.md`
MCP Servers2`bkit-pdca-server`, `bkit-analysis-server` (16 tools combined)
BKIT_VERSION runtime2.1.9`lib/core/version.js` dynamic lookup → `bkit.config.json`

Shipping QA summary

Full report: `docs/05-qa/cc-v2114-v2116-shipping-readiness.report.md` (19,780 bytes).

L1 smoke

  • lib/ 101/101 `require()` OK
  • scripts/ 43/43 `node --check` OK
  • `BKIT_VERSION` runtime = `"2.1.9"`

L3 runtime

  • SessionStart hook `additionalContext` = 4,401 chars (under 10,000 CC cap, 44%)
  • Contains v2.1.9 ✅, v2.1.116+ ✅, 39 Skills, 36 Agents ✅, Prompt caching 1H ✅

L4 contract

  • Plan/Design acceptance criteria: 15/15 met (4 ENH × average 3.75 criteria each)
  • Docs=Code post-sync grep for legacy numbers (`38 Skills`, `32 Agents`, `88 Lib`, `93 modules`, `42 scripts`, `12 subdirectories`): 0 matches in active state (historic blockquotes preserved per Plan §5.2 DO NOT TOUCH policy).

Shipping notes (all non-blocker)

  • P2: `bkit-system/components/skills/_skills-overview.md:3` v2.1.8 tag still present; `zero-script-qa/SKILL.md` has no `allowed-tools` (intentional — fork context with `agent: bkit:qa-monitor` inheritance).
  • P3: MEMORY.md at 291 lines (over ~200 guideline); ENH-264/265 Plan §4.1 roadmap annotation should be updated.

User experience changes (end-user visible)

New in v2.1.9

  1. Prompt caching hint at session start — Every SessionStart now shows either `- Prompt caching 1H: ✅ enabled (30-40% token savings on long PDCA sessions)` or `- Prompt caching 1H: ⚠️ disabled — set ENABLE_PROMPT_CACHING_1H=1 before launching CC ...` in the version/architecture block. Setting the env var before launching Claude Code yields 30–40% token savings on multi-hour PDCA sessions (CC v2.1.108+ feature).
  2. Alternative-command suggestions on blocked destructive Bash (deployment/QA phases only in v2.1.9) — When `/pdca deploy` or QA-phase flow blocks a dangerous command, Claude now receives structured alternatives (e.g., `git clean -fdx` / `rm -rf ./dist ./build ./node_modules` / `trash ~/path`) via `hookSpecificOutput.additionalContext` and can propose a reformulated command automatically. Full general-Bash coverage lands in v2.1.10.
  3. Defense-in-Depth security transparency — New `docs/03-analysis/security-architecture.md` documents exactly which attack vectors are defended by CC runtime (Layer 1) vs. bkit config-change hook (Layer 2). Users can now make informed decisions about which layer to rely on for which threat model.
  4. Custom Skills data-loss warning — Users upgrading to CC v2.1.113+ with personal skills in `~/.claude/skills/` now see the warning in README + CUSTOMIZATION-GUIDE with backup/restore commands. bkit plugin itself is unaffected.
  5. Architecture Dashboard accuracy — Session startup now reports `39 Skills, 36 Agents, 21 Hook Events, 2 MCP Servers` (matching filesystem reality), and the `/skills` / `/agents` menus align with plugin metadata.

Changed in v2.1.9

  • CC recommended version v2.1.111+ → v2.1.116+ (74 consecutive compatible releases, v2.1.115 skipped). Users on macOS 11 should stay on v2.1.112 (issue #50383); users on non-AVX CPUs should stay on v2.1.112 (issues #50384 / #50852).
  • README badge `v2.1.111+` → `v2.1.116+`.
  • 17 agent prompts now reference v2.1.116+ recommendation context when invoked.

Unchanged (but users may notice)

  • No breaking changes to any skill, agent, slash command, or hook event.
  • No changes to `disable-model-invocation`, `context:`, or any other skill frontmatter fields in user-authored skills.
  • Session context size roughly same (~4,401 chars for SessionStart `additionalContext` with `ENABLE_PROMPT_CACHING_1H` unset, well under the 10,000-char CC cap).

Monitoring (MON-CC-06) — unchanged from v2.1.8

v2.1.113 native-binary transition 10+ regression issues + v2.1.114~v2.1.116 6 new HIGH issues = 16 issues tracked. v2.1.117+ hotfix awaited. No official v2.1.116 resolutions yet.

Environmental exceptions:

  • macOS 11: stay on v2.1.112 (#50383 dyld)
  • Non-AVX CPUs: stay on v2.1.112 (#50384/#50852 SIGILL)
  • Windows with parenthesized PATH: partial improvement on v2.1.114+ via B12 fix (#50541)

Test plan

  • L1 smoke — lib 101/101 require + scripts 43/43 `node --check` (see `docs/05-qa/evidence/v219/l1-smoke-lib-scripts.txt`)
  • L3 runtime — SessionStart mock hook probe (see `docs/05-qa/evidence/v219/session-start.stdout.json`)
  • L4 contract — 4 ENH acceptance criteria × 15 conditions (see `docs/05-qa/cc-v2114-v2116-shipping-readiness.report.md` §4)
  • Regression — 43 baseline TCs retained + v2.1.8 Round 4 matrix assertions unaffected
  • Docs=Code gap re-verification — 0 active-state legacy matches
  • Post-merge: tag `v2.1.9`, create GitHub Release, verify plugin marketplace registration

Commit breakdown

  • `feat(v2.1.9)` — 59 files, +239 / -76 (runtime code + config + 17 agents + lib JSDoc + scripts)
  • `docs(v2.1.9)` — 12 files, +435 / -56 (README, CHANGELOG, CUSTOMIZATION-GUIDE, AI-NATIVE-DEVELOPMENT, bkit-system/*, memory/ cc version history)
  • `docs(pdca)` — 17 files, PDCA artifacts (plan, design, analysis, report, qa, evidence)

Total: 88 files changed, +874 / -132 LOC.


Links

🤖 Generated with Claude Code

Changed files

  • .claude-plugin/marketplace.json (modified, +3/-3)
  • .claude-plugin/plugin.json (modified, +2/-2)
  • AI-NATIVE-DEVELOPMENT.md (modified, +10/-10)
  • CHANGELOG.md (modified, +38/-0)
  • CUSTOMIZATION-GUIDE.md (modified, +62/-12)
  • README.md (modified, +20/-9)
  • agents/bkend-expert.md (modified, +1/-1)
  • agents/code-analyzer.md (modified, +1/-1)
  • agents/cto-lead.md (modified, +1/-1)
  • agents/design-validator.md (modified, +1/-1)
  • agents/enterprise-expert.md (modified, +1/-1)
  • agents/frontend-architect.md (modified, +1/-1)
  • agents/gap-detector.md (modified, +1/-1)
  • agents/infra-architect.md (modified, +1/-1)
  • agents/pdca-iterator.md (modified, +1/-1)
  • agents/pipeline-guide.md (modified, +1/-1)
  • agents/pm-lead.md (modified, +1/-1)
  • agents/product-manager.md (modified, +1/-1)
  • agents/qa-monitor.md (modified, +1/-1)
  • agents/qa-strategist.md (modified, +1/-1)
  • agents/report-generator.md (modified, +1/-1)
  • agents/security-architect.md (modified, +1/-1)
  • agents/starter-guide.md (modified, +1/-1)
  • bkit-system/README.md (modified, +14/-14)
  • bkit-system/_GRAPH-INDEX.md (modified, +7/-5)
  • bkit-system/components/agents/_agents-overview.md (modified, +2/-1)
  • bkit-system/components/hooks/_hooks-overview.md (modified, +1/-0)
  • bkit-system/components/scripts/_scripts-overview.md (modified, +2/-1)
  • bkit-system/components/skills/_skills-overview.md (modified, +2/-1)
  • bkit-system/philosophy/context-engineering.md (modified, +4/-4)
  • bkit.config.json (modified, +9/-1)
  • docs/01-plan/features/bkit-v219-docs-sync.plan.md (added, +260/-0)
  • docs/01-plan/features/cc-v2112-v2114-impact-analysis.plan.md (added, +180/-0)
  • docs/01-plan/features/cc-v2114-v2116-impact-analysis.plan.md (added, +281/-0)
  • docs/02-design/features/bkit-v219-docs-sync.design.md (added, +227/-0)
  • docs/02-design/features/cc-v2114-v2116-impact-analysis.design.md (added, +430/-0)
  • docs/03-analysis/prompt-caching-optimization.md (added, +186/-0)
  • docs/03-analysis/security-architecture.md (added, +150/-0)
  • docs/03-analysis/zero-script-qa-fork-v2116-verification.md (added, +185/-0)
  • docs/04-report/features/bkit-v219-docs-sync.report.md (added, +258/-0)
  • docs/04-report/features/cc-v2112-v2114-impact-analysis.report.md (added, +366/-0)
  • docs/04-report/features/cc-v2114-v2116-impact-analysis.report.md (added, +397/-0)
  • docs/05-qa/cc-v2114-v2116-shipping-readiness.report.md (added, +320/-0)
  • docs/05-qa/evidence/v219/enh-263-grep-evidence.txt (added, +34/-0)
  • docs/05-qa/evidence/v219/enh-264-265-migration-notice.md (added, +56/-0)
  • docs/05-qa/evidence/v219/frontmatter-audit.json (added, +30/-0)
  • docs/05-qa/evidence/v219/l1-smoke-lib-scripts.txt (added, +27/-0)
  • docs/05-qa/evidence/v219/session-start.stdout.json (added, +21/-0)
  • hooks/hooks.json (modified, +1/-1)
  • hooks/session-start.js (modified, +2/-2)
  • hooks/startup/session-context.js (modified, +11/-4)
  • lib/core/cache.js (modified, +1/-1)
  • lib/core/config.js (modified, +1/-1)
  • lib/core/debug.js (modified, +2/-2)
  • lib/core/file.js (modified, +1/-1)
  • lib/core/io.js (modified, +33/-2)
  • lib/core/platform.js (modified, +2/-2)
  • lib/import-resolver.js (modified, +1/-1)
  • lib/intent/ambiguity.js (modified, +1/-1)
  • lib/intent/index.js (modified, +1/-1)
  • lib/intent/language.js (modified, +1/-1)
  • lib/intent/trigger.js (modified, +1/-1)
  • lib/pdca/automation.js (modified, +1/-1)
  • lib/pdca/executive-summary.js (modified, +1/-1)
  • lib/pdca/level.js (modified, +1/-1)
  • lib/pdca/phase.js (modified, +1/-1)
  • lib/pdca/template-validator.js (modified, +1/-1)
  • lib/pdca/tier.js (modified, +1/-1)
  • lib/permission-manager.js (modified, +1/-1)
  • lib/skill-orchestrator.js (modified, +1/-1)
  • lib/task/classification.js (modified, +1/-1)
  • lib/task/context.js (modified, +1/-1)
  • lib/task/creator.js (modified, +1/-1)
  • lib/task/index.js (modified, +1/-1)
  • lib/task/tracker.js (modified, +1/-1)
  • lib/team/communication.js (modified, +1/-1)
  • lib/team/coordinator.js (modified, +1/-1)
  • lib/team/cto-logic.js (modified, +1/-1)
  • lib/team/hooks.js (modified, +1/-1)
  • lib/team/index.js (modified, +1/-1)
  • lib/team/orchestrator.js (modified, +1/-1)
  • lib/team/state-writer.js (modified, +1/-1)
  • lib/team/strategy.js (modified, +1/-1)
  • lib/team/task-queue.js (modified, +1/-1)
  • memory/cc_version_history_v2113_v2114.md (added, +126/-0)
  • memory/cc_version_history_v2115_v2116.md (added, +149/-0)
  • scripts/config-change-handler.js (modified, +17/-6)
  • scripts/unified-bash-pre.js (modified, +108/-3)
RAW_BUFFERClick to expand / collapse

Preflight Checklist

  • I have searched existing issues and this hasn't been reported yet
  • This is a single bug report (please file separate reports for different bugs)
  • I am using the latest version of Claude Code

What's Wrong?

What's Wrong?

After the auto-update from 2.1.113 to 2.1.114 on April 19, 2026, my entire ~/.claude/skills/ directory was silently deleted on first run. 54 custom skills were lost with no warning and no backup of the file contents.

Timeline:

  • Last confirmed skill usage: April 19 at 7:21am (em:sovereign-analysis)
  • 2.1.114 binary symlinked: April 19 at 9:10am
  • First session after update: skills directory already gone

Evidence:

  • ~/.claude/skills/ directory does not exist and has no trace on disk
  • Skill names are preserved in ~/.claude/backups/.claude.json under skillUsage (usage metadata only — no content)
  • Session logs from April 20 confirm Claude Code itself got "Directory does not exist: /Users/macproajb/.claude/skills" on first run
  • No Time Machine, no APFS snapshots — content is unrecoverable

Suspected cause: The 2.1.113 changelog notes a switch from bundled JavaScript to a native binary. The first-run initialization of the native binary appears to have wiped the skills directory rather than preserving it.

Environment:

  • macOS
  • Updated from 2.1.113 → 2.1.114
  • Install location: ~/.local/share/claude/versions/
  • 54 skills lost, months of work, no recovery possible

What Should Happen?

What Should Happen? The ~/.claude/skills/ directory and all its contents should be preserved across updates, including major runtime changes like the JavaScript-to-native-binary migration introduced in 2.1.113. At minimum, Claude Code should:

Never delete user-created files in ~/.claude/ during an update or first-run initialization under any circumstances Back up ~/.claude/skills/ before any migration that touches the config directory, the same way it backs up .claude.json Warn the user if a migration is about to make destructive changes to their config directory Include skill file contents (not just usage metadata) in the .claude.json backup so recovery is possible if something goes wrong

Error Messages/Logs

Steps to Reproduce

Note: The deletion appears to happen silently during first-run initialization of the new native binary. No error is shown to the user. The skills simply vanish.

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

No response

Claude Code Version

2.1.114 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

No response

extent analysis

TL;DR

The issue can be mitigated by modifying the update process to preserve the ~/.claude/skills/ directory and its contents across updates, including major runtime changes.

Guidance

  • Verify that the ~/.claude/skills/ directory is being deleted during the first-run initialization of the native binary by checking the directory's existence before and after the update.
  • Consider adding a backup mechanism for the ~/.claude/skills/ directory before any migration that touches the config directory, similar to the existing backup of .claude.json.
  • Warn the user if a migration is about to make destructive changes to their config directory to prevent data loss.
  • Include skill file contents in the .claude.json backup to enable recovery in case of errors.

Example

No code snippet is provided as the issue does not require a specific code change, but rather a modification to the update process.

Notes

The issue appears to be a regression introduced in version 2.1.114, and the exact cause is suspected to be related to the switch from bundled JavaScript to a native binary. The provided information does not include enough details to determine the exact code changes required to fix the issue.

Recommendation

Apply a workaround by manually backing up the ~/.claude/skills/ directory before updating to a new version, and consider reaching out to the development team to report the issue and request a fix.

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…

Still need to ship something?

×6

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

Back to top recommendations

TRENDING

claude-code - ✅(Solved) Fix [BUG] ~/.claude/skills/ directory deleted on first run after 2.1.113→2.1.114 update (native binary migration)[BUG] [1 pull requests]