claude global setup

This repo is the source of truth for my global Claude Code setup.

What this manages

• syncs repo-managed global Claude Code config from claude/ into ~/.claude by default
  • claude/CLAUDE.md → ~/.claude/CLAUDE.md (global instructions for all sessions)
  • claude/commands/*.md → ~/.claude/commands/ (custom slash commands)
• optionally installs or updates Claude Code using the official https://claude.ai/install.sh installer when requested
• can cleanly reinstall repo-managed config targets when requested
• installs missing enabled external skills declared in skills-install.json via the skills CLI, scoped to the claude-code agent and the universal canonical skills directory (~/.agents/skills/)
• removes installed external skills that are explicitly disabled in skills-install.json
• optionally runs a global skills update before syncing configured external skills

It intentionally does not touch local machine data like settings.json, settings.local.json, .credentials.json, sessions/, projects/, or prompt history in the target Claude Code directory.

What it deliberately does not manage

These areas are intentionally left per-machine:

• settings — manage ~/.claude/settings.json and ~/.claude/settings.local.json per machine
• auth — Claude Code handles auth via /login and environment variables; nothing auth-related is repo-managed

Repo layout

.
├── install.sh
├── justfile
├── skills-install.json
├── scripts/
│   └── install-skills.sh
└── claude/
    ├── CLAUDE.md
    └── commands/
        ├── clone-prompt.md
        ├── gitship.md
        ├── init-just.md
        ├── plan-progress.md
        └── setup-ci.md

Add more global Claude Code files under claude/, for example:

• claude/agents/...
• claude/skills/...

Current repo-managed slash commands include:

• /clone-prompt via claude/commands/clone-prompt.md for studying the current repo and generating reusable prompts for building a similar project
• /gitship via claude/commands/gitship.md for staging relevant work, creating a meaningful commit, and pushing, asking for confirmation only when real concerns are detected
• /init-just via claude/commands/init-just.md for creating a practical project justfile with documented tasks and a default task list
• /plan-progress via claude/commands/plan-progress.md for reviewing a plan file against current repository progress with evidence-backed status reporting
• /setup-ci via claude/commands/setup-ci.md for gathering CI requirements (Concourse or Forgejo CI) and scaffolding pipelines with testing and security gates

On install, each top-level item in claude/ is copied into ~/.claude by default.

Protected target paths that are never modified by the installer:

• ~/.claude/settings.json
• ~/.claude/settings.local.json
• ~/.claude/.credentials.json
• ~/.claude/sessions/
• ~/.claude/projects/
• ~/.claude/todos/
• ~/.claude/history.jsonl
• ~/.claude/skills/
• ~/.claude/plugins/
• ~/.claude/ide/, downloads/, backups/, cache/, shell-snapshots/, session-env/, debug/
• ~/.claude/stats-cache.json

Note: the installer replaces whole top-level targets it manages. Because commands/ is repo-managed, any machine-local slash commands in ~/.claude/commands/ that are not in this repo will be removed on install. Add custom commands to the repo instead.

Usage

From inside this repo:

chmod +x install.sh
./install.sh

Or use the helper justfile:

just                  # show available recipes
just install          # sync config and install missing skills
just install config   # sync only repo-managed files under claude/
just install skills   # install only external skills from skills-install.json
just install symlink  # sync config using symlinks instead of copies
just install update   # update Claude Code and external skills while syncing
just install full     # install/update Claude Code, then update external skills
just install clean    # reinstall repo-managed config targets from scratch
just update           # update Claude Code and external skills
just check            # validate scripts and JSON config

Options:

./install.sh --symlink            # symlink instead of copy
./install.sh --install-claude     # also install/update Claude Code via the official installer
./install.sh --update             # update Claude Code itself via claude update
./install.sh --config-only        # sync only repo-managed config files
./install.sh --clean              # remove repo-managed config targets, then reinstall them
./install.sh --update-skills      # run `npx skills update -g` before syncing configured skills
./install.sh --claude-dir ~/.config/claude

If skills-install.json exists, the installer also attempts to install each missing enabled external skill and remove each installed disabled external skill by calling ./scripts/install-skills.sh --optional:

npx skills add <repo> --skill <skill> -g -y -a claude-code -a universal
npx skills remove <skill> -g -y -a claude-code -a universal

The -a claude-code -a universal flags scope each call to the claude-code agent and the universal canonical skills directory under ~/.agents/skills/. Skills land canonically in ~/.agents/skills/<name> and are symlinked into ~/.claude/skills/<name>. This avoids agent entries in the skills CLI that fail with does not support global skill installation during auto-detection.

A skill only counts as "installed" for this repo when it is linked into ~/.claude/skills/ — skills list -g also shows skills installed globally for other agents, and those still get linked for Claude Code on install.

Keeping machines in sync

On every machine:

git pull
./install.sh

That gives you:

• latest repo-managed config (CLAUDE.md and slash commands)
• any missing enabled external skills from skills-install.json
• removal of any installed external skills explicitly disabled in skills-install.json

If you want to cleanly reinstall the repo-managed config without touching settings.json, credentials, or session state:

just install clean

If you also want to install or update Claude Code itself:

./install.sh --install-claude

If you prefer to update Claude Code itself via its built-in updater:

./install.sh --update

External skills

Declare external skills in skills-install.json as a JSON object mapping repository URLs to skill-name booleans. true means the skill should be installed if missing; false means the skill should be removed if it is currently installed.

{
  "https://github.com/anthropics/skills": {
    "frontend-design": true,
    "old-skill": false
  },
  "https://github.com/vercel-labs/skills": {
    "find-skills": true
  }
}

Current external skills config:

{
  "https://github.com/singh-gur/agent_skills": {
    "plan": true,
    "caveman": true,
    "arch-design": true,
    "draw-diagram": true,
    "spec-writer": true,
    "skill-writer": true
  }
}

During ./install.sh, each configured missing skill is installed globally for the claude-code agent via the skills CLI through ./scripts/install-skills.sh --optional. If you only want to refresh external skills, run just install skills or ./scripts/install-skills.sh. Add --update-skills if you want to run npx skills update -g first. If jq or npx is missing, external skill installation is skipped with a warning.

Slash command conventions

The commands under claude/commands/ follow Claude Code slash command format:

• frontmatter with description and optional argument-hint
• $ARGUMENTS placeholder for user-supplied arguments
• AskUserQuestion tool for interactive intake, respecting its limits: max 4 questions per call, 2-4 options per question, freeform answers via the automatic "Other" choice

Notes

• skills-install.json is optional; an empty object means no external skills are installed or removed
• skills-install.json should map repository URLs to "skill-name": true|false entries; legacy skill name arrays are still treated as enabled skills
• jq is required to parse skills-install.json
• npx is required to run the skills CLI installer
• Default Claude Code global config dir: ~/.claude
• Override with CLAUDE_CONFIG_DIR or ./install.sh --claude-dir ...
• Existing conflicting files are removed before being replaced
• --clean removes repo-managed config targets before reinstalling them and skips protected local state
• External skill install and removal failures are reported, but the installer continues with other configured skills