Declarative Claude Code config: skills, settings, permissions, and stop hook

[bphenriques]

Summary

• Replace the single code-reviewer agent with four user-invocable skills: /review-code, /review-security, /design-review, and /deep-plan
• Add declarative settings managed via home-manager: default model (opus), permissions, and hooks
• Pre-approve safe read-only tools (Read, Glob, Grep, Agent) and common commands (git *, nix *, home-manager *, nixos-rebuild *) to reduce permission prompts
• Move the stop hook (git hygiene check) from manually-placed /root/.claude/ into Nix as claude-code-stop-hook.sh

Why skills over agents

Skills are user-invoked slash commands (/review-code) — matches the workflow of explicitly choosing a review persona. Agents are auto-delegated by Claude during conversations, which isn't the use case here. Each skill accepts $ARGUMENTS for context-specific variations (e.g., /review-code focus on Nix module patterns).

What's configured

Setting	Value	Rationale
Default model	opus	Preferred for deep thinking; switch to sonnet mid-session for execution
Allowed tools	Read, Glob, Grep, Agent, Skill	Safe read-only tools that don't need prompting
Allowed commands	git *, nix *, home-manager *, nixos-rebuild *	Common daily commands
Stop hook	Git uncommitted/unpushed check	Prevents losing work when session ends

Skills overview

Skill	Purpose	Tools
/review-code	Deep code review: correctness, idioms, simplicity, architecture	Read, Grep, Glob, Bash
/review-security	Pragmatic security review with OWASP-style checklist	Read, Grep, Glob, Bash
/design-review	Enterprise architecture review for technical design docs	Read, Grep, Glob, Bash, WebSearch, WebFetch
/deep-plan	Structured implementation planning with trade-offs and steps	Read, Grep, Glob, Bash, WebSearch, WebFetch

Test plan

• Apply config with home-manager switch and verify ~/.claude/skills/ contains the four skill directories with SKILL.md files
• Verify ~/.claude/settings.json contains the model, permissions, and hooks config
• Open a Claude Code session and confirm /review-code, /review-security, /design-review, /deep-plan autocomplete
• Verify read-only tools and git/nix commands no longer prompt for permission
• Test stop hook: make a change without committing, then let Claude finish — should block

https://claude.ai/code/session_011WgapntT1iuzZE784p9AdL