9.0 KiB
claude-config
Global Claude Code configuration — agents, skills, and project templates.
Overview
This repo contains the global Claude Code setup used across all projects.
claude-config/
├── CLAUDE.md # Global coding preferences (style, rules, workflow)
├── agents/ # Specialized agent definitions (called by skills or orchestrators)
├── skills/ # Slash commands (/analyze, /debug, /ship-feature, ...)
└── templates/
└── project-CLAUDE.md # Template for per-project .claude/CLAUDE.md
Architecture principle:
skills/= entry points you invoke manually via/skill-nameagents/= execution units called by skills or by orchestrator agents- A skill delegates to one or more agents — it never contains logic itself
Installation
Clone the repo and symlink it into ~/.claude/:
git clone git@github.com:youruser/claude-config.git ~/claude-config
mkdir -p ~/.claude
rm -rf ~/claude/agents ~/claude/skills ~/claude/CLAUDE.md ~/claude/settings.json
ln -sf ~/claude-config/agents ~/.claude/agents
ln -sf ~/claude-config/skills ~/.claude/skills
ln -sf ~/claude-config/CLAUDE.md ~/.claude/CLAUDE.md
ln -sf ~/claude-config/settings.json ~/.claude/settings.json
Symlinks mean any update to this repo is immediately active — no manual sync needed.
Verify the skills are loaded:
claude
/skills
You should see all custom skills listed (analyze, debug, ship-feature, etc.).
Available slash commands
| Command | Description |
|---|---|
/analyze |
Deep analysis of code or a codebase before any modification |
/architect |
Design a robust and scalable system architecture |
/debug |
Find root cause and fix an issue precisely |
/implement |
Implement a feature following project conventions |
/refactor |
Improve code quality without changing behavior |
/review |
Strict code review with severity-graded issues |
/init-project |
Initialize a complete project from scratch (orchestrator) |
/ship-feature |
Deliver a feature end-to-end via multi-agent pipeline (orchestrator) |
Orchestrators (/init-project, /ship-feature) coordinate multiple agents sequentially with validation gates.
Standalone skills (/analyze, /debug, etc.) invoke a single specialized agent.
Agent pipeline (ship-feature)
/ship-feature <request>
└── ship-feature (orchestrator)
├── analyzer → understand the problem
├── designer → design the solution
├── [validation gate — waits for user approval]
├── implementer → write the code
├── reviewer → review loop (max 3 iterations)
└── tester → define test strategy
Settings and permissions
Claude Code uses three settings files to control what it can and cannot do. Each file has a different scope and purpose.
~/.claude/settings.json — global rules (all projects)
What it contains and why:
| Section | What it blocks / controls |
|---|---|
deny — secrets |
Prevents Claude from reading .env, .pem, .key, SSH keys, cloud credentials |
deny — destructive Bash |
Blocks rm -rf, git push --force, git reset --hard, chmod 777 |
deny — system access |
Blocks sudo, ssh, scp, netcat, crontab, systemctl |
deny — code injection |
Blocks curl | bash, wget | sh patterns |
ask — risky but needed |
Prompts before git push, docker run, brew/apt install |
allow — safe read ops |
Auto-approves git status/log/diff, ls, cat, grep, find |
disableBypassPermissionsMode |
Prevents switching to "no prompts at all" mode mid-session |
These rules apply to every project on your machine. They cannot be overridden by project-level settings — deny always wins globally.
.claude/settings.json — project rules (committed to git)
Copy the project template into each new project:
mkdir -p .claude
cp ~/claude-config/templates/settings/settings.json .claude/settings.json
What it contains and why:
| Section | What it allows / controls |
|---|---|
allow — build commands |
Auto-approves npm run *, cargo build/test, make, pytest, flutter *, etc. |
allow — language tools |
Auto-approves formatters, linters, type checkers (ruff, mypy, clippy...) |
allow — runtime commands |
Auto-approves node, python, php, dart within the project |
ask — database commands |
Prompts before psql, mysql, mongosh, redis-cli |
ask — deploy commands |
Prompts before make deploy, npm run deploy, cargo publish |
Only put project-specific rules here. Generic security rules belong
in ~/.claude/settings.json, not repeated per project.
Shared with the team via git — keep it stack-appropriate and avoid personal paths or machine-specific commands.
.claude/settings.local.json — personal overrides (never committed)
Copy the template and add to .gitignore:
cp ~/claude-config/templates/settings/settings.local.json .claude/settings.local.json
echo ".claude/settings.local.json" >> .gitignore
What it contains and why:
| Section | What it controls |
|---|---|
allow — trusted WebFetch |
Auto-approves fetching from specific doc domains (docs.rs, MDN, flutter.dev...) |
additionalDirectories |
Grants Claude access to directories outside the project root (personal shared libs, etc.) |
| Personal overrides | Any rule you want on your machine that shouldn't affect teammates |
This file has the highest priority of all file-based settings. Use it for anything environment-specific or personal.
.claudeignore — hard file exclusion (committed to git)
Copy to each project root:
cp ~/claude-config/templates/settings/.claudeignore .claudeignore
What it does and why it is different from deny rules:
deny rules in settings.json block specific tools from accessing files.
.claudeignore goes further — it removes files from Claude's awareness
entirely, regardless of which tool is used.
| Excluded by default | Why |
|---|---|
.env, .env.* |
Secrets must never appear in Claude's context |
*.pem, *.key, *.p12 |
Private keys and certificates |
id_rsa*, id_ed25519*, .ssh/ |
SSH credentials |
.aws/, .azure/, .gcloud/ |
Cloud provider credentials |
node_modules/, dist/, build/ |
Generated artifacts — noise, no value |
*.png, *.jpg, *.pdf, *.zip... |
Binaries Claude cannot process usefully |
*.log, *.sqlite, *.db |
Runtime state, not source |
A .env file excluded via .claudeignore cannot be read by Claude even
if a Bash(cat .env) would otherwise be allowed. Use both layers for
defense in depth.
Precedence summary
Highest
managed-settings.json — enterprise-wide, cannot be overridden
CLI flags — --allowedTools / --disallowedTools (session only)
settings.local.json — personal machine overrides
settings.json — project rules (team, committed)
~/.claude/settings.json — global user rules
Lowest
DENY always wins over ALLOW at any level.
.claudeignore applies independently of all permission rules.
Per-project setup
Each project gets its own .claude/CLAUDE.md for local context and overrides.
# In your project root
mkdir -p .claude
cp ~/claude-config/templates/project-CLAUDE.md .claude/CLAUDE.md
Then fill in the relevant sections: build commands, test commands, conventions, architecture, and any exceptions to global rules.
Override rules:
- Local
.claude/takes precedence over global~/.claude/for identical filenames - Files not defined locally fall back to global automatically
- Use local overrides only for project-specific deviations — keep global rules generic
Updating
cd ~/claude-config
git pull
Changes are immediately active via symlinks. No restart needed for agents and skills (Claude Code reloads them at the start of each session).
Adding a new skill or agent
New standalone skill (single agent):
- Create
agents/myagent.md— define role, tasks, rules, output format - Create
skills/myskill.md:
---
name: myskill
description: One-line description of what this skill does
argument-hint: <what to pass as argument>
---
Load and follow strictly:
- .claude/agents/myagent.md
Execute the MYAGENT agent on the following request:
$ARGUMENTS
New orchestrator skill (multiple agents):
- Create
agents/myorchestrator.md— define the workflow and agent call sequence - Create
skills/myorchestrator.mdreferencing all involved agents
Extending per project
If a project needs a modified version of an agent, place it in .claude/agents/:
# Override the implementer for a specific project
cp ~/claude-config/agents/implementer.md .claude/agents/implementer.md
# Edit to add project-specific constraints
The local version takes precedence. All other agents continue to load from global.