Claude Settings Template

A template repository for syncing Claude Code CLI settings across machines. Store your global instructions, agents, skills, and hooks in version control.

What This Is

Claude Code stores configuration in ~/.claude/. This template helps you:

• Keep settings in a git repository
• Sync across multiple machines
• Version control your customizations
• Share configurations with your team

Prerequisites

• Claude Code CLI installed
• Git

Quick Start

1. Use this template to create your own repository

2. Clone your new repository:

   git clone https://github.com/YOUR_USERNAME/claude-settings.git ~/repos/claude-settings
   cd ~/repos/claude-settings

3. Rename the example files:

   mv claude/CLAUDE.md.example claude/CLAUDE.md

4. Run bootstrap to create symlinks:

   chmod +x bootstrap.sh sync.sh
   ./bootstrap.sh

5. Edit your settings and commit changes

Directory Structure

claude-settings/
├── bootstrap.sh              # Creates symlinks from repo to ~/.claude
├── sync.sh                   # Copies non-symlinked files back to repo
├── claude/
│   ├── CLAUDE.md             # Global instructions (loaded every session)
│   ├── agents/               # Custom agent definitions
│   │   └── example-agent.md
│   ├── hooks/                # Lifecycle hooks (scripts)
│   ├── plans/                # Saved plans (task breakdowns)
│   ├── skills/               # Slash command skills
│   │   └── example-skill/
│   │       └── SKILL.md
│   └── plugins/
│       └── user/             # User plugin files
└── agents/
    └── skills/               # Skills for ~/.agents directory

What Each Directory Contains

Directory	Purpose
claude/CLAUDE.md	Global instructions loaded in every Claude Code session
claude/agents/	Agent definitions (specialized Claude personas)
claude/hooks/	Scripts that run at specific lifecycle events
claude/plans/	Saved implementation plans
claude/skills/	Slash commands (invoked with /skill-name)
claude/plugins/	Plugin configurations
agents/skills/	Skills for the ~/.agents directory

How the Scripts Work

bootstrap.sh

Creates symbolic links from your repository to ~/.claude/:

~/.claude/CLAUDE.md -> ~/repos/claude-settings/claude/CLAUDE.md
~/.claude/agents/*.md -> ~/repos/claude-settings/claude/agents/*.md
~/.claude/skills/* -> ~/repos/claude-settings/claude/skills/*
...

This means edits to either location update the same file.

Run once after cloning, or after adding new files to the repo.

sync.sh

Copies files that were created directly in ~/.claude/ (not symlinked) back to the repository. Useful if you:

• Created a new agent/skill in Claude Code directly
• Made changes on a machine before setting up symlinks

Run before committing to capture any local changes.

Customization Guide

Global Instructions (CLAUDE.md)

Edit claude/CLAUDE.md to set rules that apply to every session:

# My Global Settings

## Code Style
- Use TypeScript for all new code
- Prefer functional programming patterns

## Git Conventions
- Use conventional commits
- Never force push to main

Creating Agents

Agents are specialized Claude personas. Create claude/agents/my-agent.md:

---
name: my-agent
description: When to use this agent
model: sonnet
---

You are a specialist in [domain]. Your role is to...

## Responsibilities
- Task 1
- Task 2

Creating Skills

Skills are slash commands. Create claude/skills/my-skill/SKILL.md:

# My Skill

Description of what this skill does.

## Trigger

Use this skill when the user asks to:
- Do X
- Perform Y

## Instructions

1. First, do this
2. Then, do that

Invoke with /my-skill in Claude Code.

Adding Hooks

Hooks are scripts that run at lifecycle events. Create executable scripts in claude/hooks/:

• PreToolUse - Before a tool runs
• PostToolUse - After a tool runs
• Notification - When Claude sends notifications

See Claude Code documentation for hook details.

Multi-Machine Workflow

On your first machine:

1. Customize settings
2. Commit and push

On additional machines:

1. Clone the repository
2. Run ./bootstrap.sh
3. Changes sync automatically via symlinks

After creating files locally:

1. Run ./sync.sh to copy them to the repo
2. Commit and push

Tips

• Keep secrets out of version control (use .gitignore)
• Project-specific settings go in project CLAUDE.md files, not here
• Test changes in one machine before pushing

License

MIT License - See LICENSE for details.