claude-code-config

Personal agent configuration for Claude Code, installed from one source of truth — plus the VS Code extension set.

git clone --recurse-submodules https://github.com/ruhalis/claude-code-config ~/projects/claude-code-config
cd ~/projects/claude-code-config
./install.sh

./install.sh                     # every tool detected on this machine
./install.sh claude              # one tool
./install.sh claude vscode       # several
./install.sh vscode              # merge VS Code settings, install missing extensions
./install.sh skills              # only the skills
./install.sh all                 # both, detected or not
./install.sh --dry-run all       # print the plan, change nothing

Layout

core/                  source of truth: agents and skills
  agents/*.md            the specialists, in Claude's format
  skills/*/              SKILL.md skills
  skills/anatomy/        submodule: wheresryan22/anatomy, pinned (Claude Code only)
  skills/teach/          personal tutor, quizzes and Artifact lessons (written for Claude Code: uses AskUserQuestion, Agent and Artifact; package-skills.sh still packages it)
  skills/pcb-author/     the only write path for a board: Zener sources and Diode's pcb CLI, Fable only (Claude Code only; carries Diode's five skills as references, MIT, pinned in SKILL.md)
  skills/shopping/       read-only personal shopper for Kazakhstan: store reads (scripts/listing.py), landed cost in KZT, Artifact comparison pages (written for Claude Code, like teach)
adapters/
  claude/                CLAUDE.md + settings.json + keybindings.json + subagent-statusline.sh + hooks/
  vscode/                extensions.txt — extension IDs to install; settings.json — user settings (merged)
scripts/               bench.sh, check-skills.sh, package-skills.sh, skill-sync-status.sh
build/                 generated by package-skills.sh, gitignored
statusline/            submodule (Claude-only)

What lands where

	Claude Code
Instructions	~/.claude/CLAUDE.md (symlink to adapters/claude/CLAUDE.md)
Agents	~/.claude/agents/*.md
Skills	~/.claude/skills/
Settings	settings.json (merged copy)
Keybindings	keybindings.json (merged copy)
Statusline	statusline/ (submodule)
Hooks	~/.claude/hooks/guard-main-session.sh and ~/.claude/hooks/guard-kicad-edit.sh (symlinks to adapters/claude/hooks/)
Subagent rows	~/.claude/subagent-statusline.sh (symlink to adapters/claude/subagent-statusline.sh): the agent panel shows type model effort · task · tokens per running subagent, wired by subagentStatusLine in settings.json

Symlinked items track repo edits live. The two copies — settings.json and keybindings.json — are copies precisely because Claude Code rewrites settings.json in place when you change the theme or model, and a symlink would push those edits back into the repo. Re-run install.sh to update them: it backs up the live file, then merges the repo over it, so the repo wins on every key it declares and the live file keeps the rest, with model, modelSettings, effortLevel and autoMode staying as Claude Code last wrote them (the repo only seeds them when absent). A key removed from the repo is not removed from the live file because the merge never deletes, so remove it by hand or with /config.

Plugin updates

Each plugin updates on its own channel:

Plugin	How it updates	Why
claude-plugins-official (clangd-lsp, frontend-design)	Claude Code auto-update, on by default for that marketplace	official marketplace
kicad-happy	Claude Code auto-update: "autoUpdate": true on its extraKnownMarketplaces entry. It runs in an interactive session a few minutes after the first message; /reload-plugins or a restart applies it	release-tagged, and kicad-review calls only analyze_schematic.py / analyze_pcb.py --output. After a major version, rerun the analyzers on a known board
text-to-cad	Its own CAD server: patch releases (0.11.x) install themselves once nothing is running; minor releases wait for cad update or the installer again. cad update auto off stops it. Claude Code reads the plugin in place from ~/Library/Application Support/cad/plugin (text-to-cad@text-to-cad, a local catalog the installer registers), so it has no extraKnownMarketplaces entry. First install, or moving to a new minor: curl -fsSL https://texttocad.dev/install.sh | sh -s -- --only claude --no-telemetry, then check pcb-enclosure against the new cad skill	before 1.0 a minor release renames commands (0.8 to 0.11 renamed cadgen, skills and env vars)
hyperframes	manual: claude plugin marketplace update hyperframes, then claude plugin update hyperframes@hyperframes	the marketplace clone is a hand-made sparse shallow clone (the full repo is about 513 MB and the clone timed out), and an auto-update may re-clone it in full
Diode pcb CLI (not a plugin)	its shim auto-updates pcbc within the workspace's pcb-version lane (0.4) on any call	upstream behaviour; pcb-author records the version per round

Claude Code's own updater, and with it the plugin pass, is off under DISABLE_AUTOUPDATER=1, DISABLE_UPDATES=1 or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 unless FORCE_AUTOUPDATE_PLUGINS=1 is also set.

Skills and claude.ai

core/skills/ is the only place skills are edited. The installed skill directory holds symlinks to it, so an edit is live the moment it's made. After adding or renaming a skill, ./install.sh skills relinks just the skills (no settings copy) and names any skill still missing from ~/.claude/skills/.

The claude.ai copies are separate. claude.ai, Cowork and cloud sessions use the skills uploaded to your claude.ai account; Claude Code can download those into ~/.claude/skills/synced/ but never uploads, so a local edit does not reach them. settings.json sets syncClaudeAiSkills: false, so Claude Code no longer loads those copies next to the repo skills; that also drops Anthropic's claude.ai skills (docx, pdf, pptx, xlsx, skill-creator and the rest) from Claude Code. After changing a skill, re-upload it for the claude.ai side:

scripts/check-skills.sh                # lint every skill; exit 1 on any FAIL
scripts/package-skills.sh esp-idf      # -> build/skills/esp-idf.skill
# upload build/skills/esp-idf.skill in claude.ai under Customize > Skills, in place of the old copy
scripts/skill-sync-status.sh           # after the next sync: in-sync, drifted or not-on-claude.ai
scripts/bench.sh                       # does the installed setup behave as claimed; --live adds claude -p runs

core/skills/anatomy is the exception: a submodule pinned to an upstream commit (40 MB, needs Node 20.10+ and Chrome), so it is Claude Code only and never packaged or uploaded. Don't edit it in place; update it with git -C core/skills/anatomy fetch && git -C core/skills/anatomy checkout <commit>, then commit the new pin.

Never edit files under synced/: the next sync replaces them and the repo never sees the change. If skill-sync-status.sh --diff shows a claude.ai-side edit worth keeping, make it in core/skills/ and upload again.

• check-skills.sh needs only bash and python3. It fails a skill whose frontmatter breaks the Agent Skills spec (a key outside name, description, license, compatibility, metadata, allowed-tools; name not the directory name; description over 1024 characters; compatibility over 500; a non-string metadata value), a script that does not parse or whose --help breaks, a bundled path SKILL.md names that does not exist, or a missing version-pin file. It warns about __pycache__ and .DS_Store. Last it checks every ~/.claude/skills/<name>/<path> reference in the Markdown under ~/projects, because other repos call the bundled scripts by those paths. The header of the script lists every rule.
• package-skills.sh packages only skills that pass the check, with the root folder named after the skill and the same exclusions as skill-creator's packager (__pycache__/, *.pyc, .DS_Store, evals/). An unchanged skill packages to a byte-identical file.
• install.sh runs check-skills.sh and skill-sync-status.sh after any install that links skills. Both only report.
• bench.sh checks that the install matches this README: every symlink points into the repo, the live settings carry the guard hook, the deny list, the cache TTL and the subagent env, the agent frontmatter pins the documented models and effort, and the guard hook decides correctly on synthetic input. --live adds nine headless claude -p sessions (API cost, a few minutes) in a throwaway repo whose CLAUDE.md holds a sentinel word: the main session and a general-purpose subagent must know it, Explore must not, the guard hook must deny pytest in the main session and allow it in a subagent, git clean -fd must stay blocked under bypassPermissions, and modelUsage must show haiku for Explore, sonnet for general-purpose and fast-executor, and opus for deep-reasoner. --keep leaves the transcripts and the hook-input log for inspection. Run it after an install or a settings change.

What the skills read from a project

The skills hold workflow and boundaries; project facts live in the project, in CLAUDE.md (or CLAUDE.local.md) sections with one greppable key: value per line. A skill that finds its section missing works the facts out, then offers to write the section.

Section	Read by	Keys
## Boards	esp-idf	<board name>: <serial port>
## Hardware	kicad-review, pcb-author, pcb-enclosure, robotics-research-brief	kicad:, pins: (the firmware pin header), mcu:, fab:, note:
## Print (optional)	pcb-enclosure	printer:, nozzle:, material:; absent means 0.4 mm nozzle, PLA or PETG
## Motors	motor-bench	rule:, rig:, program:, send:, probe:, moves:, stop:, user-only:, kill:, limits:, watchdog:, supply:, direction:, log:
## Experiments	rl-advisor	log:, run-id:, runs:, metric:, eval:, framework:
## Where things run	robotics-research-brief	robot, GPUs and VRAM, Jetson, simulator versions

Keep this order, ## Boards first and short: esp-idf reads a fixed 12 lines after its heading, and motor-bench reads up to the next heading. The sections also connect skills: when firmware changes the header ## Hardware names as pins:, esp-idf hands back to kicad-review's pin diff, and a flash or reset of a board wired to ESCs or drivers follows motor-bench as well as esp-idf. led-animation reads the free-form CLAUDE.md section on the renderer and the host tooling's README instead; isaac reads the pin from CLAUDE.md, .gitmodules and STATUS.md. rl-advisor answers the RL theory and design questions around a run and keeps its record (in aquila the ledger row and its EVIDENCE §9 row, elsewhere an entry in the template of references/isaac-lab-log.md); its references/aquila-map.md digests only the durable facts of aquila (structure, locked hyperparameters, method, closed results with their EVIDENCE section); the moving state (shipped student, open decisions, pending verdicts) stays in verro/STATUS.md and verro/EVIDENCE.md and the digest points at it by row ID, so refresh the digest only when a lever is kept or a campaign closes, not per run.

VS Code settings and extensions

adapters/vscode/settings.json holds the VS Code user settings this repo cares about (today: workbench.secondarySideBar.defaultVisibility: hidden, so the Chat / Claude Code side bar starts closed). ./install.sh vscode merges it into ~/Library/Application Support/Code/User/settings.json (~/.config/Code/User/ on Linux) the way the Claude settings are merged: the repo wins on the keys it declares, every other live key stays, the old file goes to the backup folder, and on a fresh machine the file is simply copied. Keep the repo file plain JSON, with no comments: the merge runs through jq. A live file that jq can't parse (VS Code accepts comments and trailing commas), a symlinked one, or a live file on a machine without jq is left alone with a warning, never replaced. This step doesn't need the code CLI. Toolbar buttons hidden with a right-click are kept in VS Code's internal state database rather than settings.json, so they don't carry over.

adapters/vscode/extensions.txt lists extension IDs, one per line, # comments allowed. ./install.sh vscode — or a bare ./install.sh when VS Code is detected — installs whichever are missing in a single code --install-extension call, always at the latest marketplace version; nothing is pinned. Extensions already on the machine are never removed, including ones the list doesn't mention. Those are reported instead, so you can add them:

installed here but not in extensions.txt: publisher.name

To capture what you've installed since, append the new IDs from code --list-extensions to the file. The installer needs the code CLI: it looks on PATH first, then inside the macOS app bundle. If neither is found it warns and skips — run Shell Command: Install 'code' command in PATH from the Command Palette and re-run.

Backups and safety

Anything pre-existing is backed up to ~/.agent-config-backups/<timestamp>/<tool>/, never deleted.

Swept — ~/.claude/agents/ and ~/.claude/skills/ are owned by this repo. Anything not from here is backed up and removed, so after install they mirror the repo exactly. The exceptions are ~/.claude/skills/synced/ (skills Claude Code downloads from claude.ai) and ~/.claude/skills/.trash/, which belong to Claude Code and are left alone.

Each link line says new, exists (already that link) or replace, so --dry-run shows what a run would change.

Cleaning developer caches

scripts/cleanup.sh is opt-in and not run by install.sh. With no flags it only reports cache sizes. --purge clears the safe caches (brew, npm, uv, Xcode DerivedData, unavailable simulators). --purge-heavy also offers Docker images and model weights, each behind a y/N prompt unless --yes is given. Add --dry-run to print what would run.

Agents & orchestration

adapters/claude/CLAUDE.md makes the main agent an orchestrator that delegates what would flood its context or can run in parallel, and keeps the rest: understanding the request, planning and design decisions, the edits whose shape is still open, reading agent reports, integrating and reporting. The rule states the price of a subagent first (a fresh context, and only a summary back), following Anthropic's Fable 5.2 prompting guide, where a cost-first delegation rule cut delegation by about a third at the same task success. Work that would return more than a screen of output or sweep many files goes to an agent before it starts; a lookup with a known target, the one document a decision rests on, and a short-output step of up to about five tool calls stay in the main session. Tests, builds, validation batches, benchmarks, smoke tests and checksum reruns are never run in the main session. On a Fable main session, plans and design decisions stay there too, and deep-reasoner gathers the evidence. Fable runs at high (modelSettings); xhigh is not used for orchestration, because at xhigh and max Fable 5.2 starts subagents to review its own work, on top of the delegation here. The section also splits work by context rather than by role, and keeps workflows to one per request once the user opts in. It routes to specialists, each with a pinned model so nothing inherits the session model (CLAUDE_CODE_SUBAGENT_MODEL=sonnet covers general-purpose; the built-in Plan ignores that variable and inherits the session model):

• deep-reasoner (Opus at xhigh, read-only) — any investigation that spans several files or runs, and complex debugging. On an Opus or Sonnet main session it also makes the hard design decisions, plans for large or risky changes and algorithm choices; on a Fable main session those stay with the orchestrator and deep-reasoner gathers the evidence.
• fast-executor (Sonnet at medium) — boilerplate, patterned edits across separate files, fixes whose shape is already decided, tests; it runs the targeted test for what it touched.
• verifier (Sonnet at medium, read-only) — runs every test suite, build, batch and smoke test on the orchestrator's behalf and returns pass/fail with the decisive lines; at milestones, after long unattended work or on high-stakes changes it also checks the integrated result against the acceptance criteria.
• video-maker (Sonnet at high) — every HyperFrames round (scaffold, check, snapshot, preview, render, GIF export) is delegated to it, never the main session; the only agent with the Skill tool, because its job is the hyperframes plugin; local renders only, no cloud render, publish or paid generation unless the brief asks.
• Explore (Haiku at low, read-only) — broad fan-out searches; returns file:line locations, overrides the built-in Explore agent.

The rule is enforced, not only stated: adapters/claude/hooks/guard-main-session.sh is a PreToolUse hook on Bash (wired in settings.json with onFailure: block) that denies test and build commands in the main session (pytest, npm test, cargo test/build, go test, ctest, ninja, make test/check/all, cmake --build, and idf.py build-type actions such as build, app, bootloader and size whatever options come first, so idf.py -C "<dir>" build is caught) and names the verifier in the denial. It also denies the HyperFrames CLI in the main session, in command position only (bare hyperframes, or through npx, bunx, pnpx, pnpm dlx or npm exec, so grep hyperframes still passes), with a denial reason that names video-maker. Flash, monitor and menuconfig stay allowed. The hook ignores heredoc bodies and quoted strings when matching, so a commit message or note that mentions pytest passes; a test command hidden inside quotes (e.g. bash -c "pytest") is not caught, which is acceptable since the guard backs up an instruction rather than resisting an adversary. Calls from subagents carry agent_id in the hook input and pass through. GUARD_MAIN_SESSION_OFF=1 in settings env disables it. Without jq the hook fails closed: it exits 1, so onFailure: block stops the call. settings.json also carries a short permissions.deny list (git commit and git push in any form (also with -C <dir>), gh pr create, force pushes in any flag order, git reset --hard, git clean -f, rm -rf of ~ or /, and desktop-commander's two terminal tools, which the Bash-only hook can't see) that applies in every permission mode and to subagents, subagentPromptCacheTtl: "1h" so long fan-outs keep their prompt cache, and maxTurns on fast-executor (60) and verifier (80) so a runaway run returns partial, resumable output.

A second hook, adapters/claude/hooks/guard-kicad-edit.sh (PreToolUse on Edit|Write|Bash|mcp__.*[Kk][Ii][Cc][Aa][Dd].*, also onFailure: block), lets only Claude Fable 5.2 or later change a board. It guards Edit and Write on *.kicad_sch, *.kicad_pcb, *.kicad_pro, *.kicad_sym, *.kicad_mod, *.kicad_wks, *.kicad_dru and *.zen; shell redirects, tee and sed -i/perl -i into those files; the writing subcommands of Diode's pcb CLI (layout, import, apply, new, fmt, fix, migrate, route, embed-step, unless the segment carries --check); pcb-component-gen; kicad-cli <sch|pcb|sym|fp> upgrade; text-to-cad's board edit API (kicad_pcb.edit / kicad_sch.edit, inline or in any existing *.py the command names, as in cad run board.py); and the writing tools of a KiCad MCP server (by verb in the tool name). text-to-cad's own pcb skill is also denied for every model by Skill(text-to-cad:pcb) in permissions.deny, because it saves boards in KiCad's nightly format. The hook input has no model field, so the hook reads the model from the transcript: the last assistant message of the session file, or of <session>/subagents/agent-<agent_id>.jsonl for a subagent. Two consequences follow from reading the previous message rather than the one issuing the call: a subagent's very first tool call has no model on record and is denied, and the first call after /model is judged by the old model. Anything other than Fable 5.2 or later (claude-fable-5-2 and up; Fable 5.1 scored below Opus 5.5 on BenchCAD 2.1), including an unknown model, is denied with a reason that names the pcb-author skill and how to hand the edit to Fable. It is best effort on Bash (a script that writes the files itself is not seen), and GUARD_KICAD_OFF=1 in settings env disables it. The write path is the pcb-author skill; kicad-review stays read-only and gates what pcb-author produces. Diode's pcb CLI is not installed by install.sh: run its installer yourself (~/.local/bin/pcb).

Delegation is mandatory for validation because the main session's context is the scarce resource: a session that runs its own batches fills up with output and loses the thread of the task, and that costs more than the extra tokens the agents spend. The specialists have no Skill tool (except video-maker): esp-idf hands them a restricted prompt block instead, and hardware actions (flashing, resets, motors) stay with the main session.

settings.json also turns on Claude Code's advisor tool with advisorModel: fable. The orchestrator consults it before committing to the plan for a large or risky change, when an error keeps recurring, and before reporting a milestone done. The advisor reads only the transcript, so an investigation that needs files still goes to deep-reasoner and pass/fail still comes from verifier. Subagents inherit it, which gives the Opus and Sonnet agents a Fable advisor at their own decision points, billed as Fable usage; Explore and verifier are told never to call it. A Fable 5.2 main session accepts only Fable 5.2 as its advisor (Claude Code 2.1.321 or later), which is why the setting is fable: with opus a Fable session starts with no advisor and says so at launch. /advisor writes to the home settings copy, which the next install overwrites.

Agents are linked from core/agents/*.md as-is; model: and effort: in their frontmatter apply directly.