configure-repo

/configure:repo

End-to-end driver that brings any repo's Claude Code configuration to a healthy baseline in one command. Produces committed-ready files: .claude/settings.json (permissions + marketplace enrollment), a SessionStart hook, and scripts/install_pkgs.sh.

When to Use This Skill

Use this skill when...	Use another approach when...
Onboarding a new repo to Claude Code from scratch	Changing a single setting — use /configure:claude-plugins or /configure:web-session directly
Updating an existing repo to the latest baseline config	Diagnosing a specific hook or plugin issue — use /health:check directly
Checking what would change before committing	Running a health-only audit — use /health:check
Setting up a repo for ephemeral web sessions (claude.ai/code)	Managing plugins on an already-configured repo

Context

Detect current state and project stack:

• Existing settings: !find . -path '*/.claude/*' -maxdepth 2 -name 'settings.json' -type f
• Install script: !find . -name 'install_pkgs.sh' -path '*/scripts/*'
• Workflows: !find . -path '*/.github/workflows/*' -maxdepth 3 -name 'claude*.yml'
• Project files: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'justfile' -o -name 'Justfile' \)
• ESP indicators: !find . -maxdepth 2 \( -name 'idf_component.yml' -o -name 'sdkconfig' \)
• Pre-commit config: !find . -maxdepth 1 -name '.pre-commit-config.yaml'
• Git remote: !git remote -v

Parameters

Parameter	Description
--check-only	Report what would change without modifying any files
--skip-health	Skip the final /health:check validation step
--skip-migrations	Skip migration detection (don't offer mypy→ty etc.)

Execution

Execute this end-to-end repository configuration workflow:

Step 1: Detect project stack

Identify the stack from the context above. Produce a brief summary:

Stack detected:
  Language:   Python (uv + ruff) | Node/TypeScript | Rust | Go | ESP-IDF | ESPHome | ...
  Tools:      pre-commit, just, docker, ...
  Migrations: mypy→ty candidate | black→ruff-format candidate | flake8→ruff candidate | ESLint→Biome candidate

If --check-only, annotate all subsequent steps as "(would do)" rather than doing them.

Step 2: Configure plugins, permissions, and marketplace enrollment

Invoke /configure:claude-plugins --fix using the SlashCommand tool.

This step:

• Selects recommended plugins based on detected stack
• Writes permissions.allow (common + stack-aware) to .claude/settings.json
• Writes extraKnownMarketplaces + enabledPlugins to .claude/settings.json (critical for web sessions)
• Creates/updates .github/workflows/claude.yml and claude-code-review.yml

Step 3: Configure SessionStart hook and install script

Invoke /configure:web-session --fix using the SlashCommand tool.

This step generates scripts/install_pkgs.sh with idempotent tool installs gated on CLAUDE_CODE_REMOTE=true, and wires the SessionStart hook in .claude/settings.json.

If the project uses language-level deps (Python, Node, Rust, Go), also invoke /hooks:session-start-hook --remote-only using the SlashCommand tool to add dependency installation to the hook script.

Step 3b: Configure .gitattributes

Invoke /configure:gitattributes --fix using the SlashCommand tool. This applies the zero-risk baseline (LF normalization for shell scripts, linguist-generated for build output) and surfaces any append-only-table merge=union candidates as recommendations. See .claude/rules/gitattributes.md.

Step 3c: Configure .gitignore

Invoke /configure:gitignore --fix using the SlashCommand tool. This appends the managed Claude Code runtime-state block (.claude/worktrees/, /worktrees/, .claude/scheduled_tasks.lock, .claude/settings.local.json) so session-generated files never get committed. Additive only — existing .gitignore lines are left untouched.

Step 3d: Configure .worktreeinclude

Invoke /configure:worktreeinclude using the SlashCommand tool. This inspects the gitignored files actually present in the repo and proposes a .worktreeinclude so Claude Code copies per-environment inputs (.env, local secrets, local config) into new worktrees. It confirms the include set interactively, so run it without --fix on the happy path; skip it silently if the repo has no gitignored inputs worth copying.

Step 4: Offer migrations (unless --skip-migrations)

Detect these migratable patterns and ask whether to run each migration via AskUserQuestion:

Pattern detected	Migration to offer	Skill to invoke
.pre-commit-config.yaml contains mirrors-mypy or [tool.mypy] in pyproject.toml	mypy → ty	/migration-patterns:mypy-to-ty
.pre-commit-config.yaml contains psf/black	black → ruff-format	/migration-patterns:black-to-ruff-format
.pre-commit-config.yaml contains pycqa/flake8 or PyCQA/isort	flake8/isort → ruff	/migration-patterns:flake8-to-ruff
.eslintrc* or eslint.config.* present, no biome.json	ESLint → Biome	/migration-patterns:eslint-to-biome

For each detected pattern, ask: "Found [pattern] — offer to migrate? (y/n)". Only run the migration skill if the user confirms.

Migrations are not part of the happy path. If the user declines all migrations, continue to Step 5.

Step 5: Validate with health check (unless --skip-health)

Invoke /health:check using the SlashCommand tool.

Parse the health check output. If any checks fail:

• Report the specific failures
• Suggest how to fix them
• Continue (do not abort — the config files are still staged)

Step 6: Stage files and report

Run git status to list all created/modified files. Stage the relevant files:

git add .claude/settings.json
git add scripts/install_pkgs.sh        # if created
git add .gitattributes                 # if created/updated
git add .github/workflows/claude.yml   # if created
git add .github/workflows/claude-code-review.yml  # if created

Print a summary:

configure-repo complete
=======================
Repository: <repo-name>

Files staged:
  .claude/settings.json             [CREATED | UPDATED]
  scripts/install_pkgs.sh           [CREATED | UPDATED | SKIPPED]
  .github/workflows/claude.yml      [CREATED | UPDATED | SKIPPED]
  .github/workflows/claude-code-review.yml  [CREATED | UPDATED | SKIPPED]

Marketplace enrollment:
  .claude/settings.json → extraKnownMarketplaces.claude-plugins  ✓
  .github/workflows/claude.yml → plugin_marketplaces             ✓

Health check: PASS | WARN (<N> warnings) | FAIL (<N> failures)

Next steps:
  1. Review the staged diff: git diff --cached
  2. Commit: git commit -m "chore(claude): configure repo for Claude Code"
  3. Add CLAUDE_CODE_OAUTH_TOKEN to repository secrets
  4. Push and test: mention @claude in a PR comment

If --check-only was set, prefix the summary with "DRY RUN — no files modified".

Important Notes

• This skill is a thin orchestrator — it contains no business logic. All logic lives in its dependencies.
• Never auto-commit; always stage and let the user review with git diff --cached.
• AskUserQuestion is required for migration offers — this skill must not run on haiku model.
• extraKnownMarketplaces in .claude/settings.json is the key to surviving ephemeral web sessions.
• The SessionStart hook uses CLAUDE_CODE_REMOTE guard so it is a no-op in local sessions.

Agentic Optimizations

Context	Command
Full setup with health check	/configure:repo
Dry-run, no file changes	/configure:repo --check-only
Setup without migration prompts	/configure:repo --skip-migrations
Quick setup, skip health	/configure:repo --skip-health --skip-migrations
Stage and review	git diff --cached

Dependencies (driver freshness)

This skill orchestrates these dependencies. If any dependency's modified: date is newer than this skill's reviewed: date, run scripts/check-driver-freshness.sh and update this skill accordingly.

Dependency	File
/configure:claude-plugins	configure-plugin/skills/configure-claude-plugins/SKILL.md
/configure:web-session	configure-plugin/skills/configure-web-session/SKILL.md
/configure:gitattributes	configure-plugin/skills/configure-gitattributes/SKILL.md
/configure:worktreeinclude	configure-plugin/skills/configure-worktreeinclude/SKILL.md
/hooks:session-start-hook	hooks-plugin/skills/hooks-session-start-hook/SKILL.md
/health:check	health-plugin/skills/health-check/SKILL.md
/migration-patterns:mypy-to-ty	migration-patterns-plugin/skills/mypy-to-ty/SKILL.md
/migration-patterns:black-to-ruff-format	migration-patterns-plugin/skills/black-to-ruff-format/SKILL.md
/migration-patterns:flake8-to-ruff	migration-patterns-plugin/skills/flake8-to-ruff/SKILL.md
/migration-patterns:eslint-to-biome	migration-patterns-plugin/skills/eslint-to-biome/SKILL.md

See Also

• /configure:claude-plugins — Configure plugins, permissions, and marketplace enrollment
• /configure:web-session — SessionStart hook for infrastructure tools
• /configure:gitattributes — .gitattributes merge/diff hygiene (union merge, linguist-generated, LF)
• /configure:worktreeinclude — .worktreeinclude so worktrees inherit gitignored env/secret/config inputs
• /health:check — Claude Code configuration health check
• scripts/check-driver-freshness.sh — Detect when this driver is out of sync with its dependencies