Claude Code Configuration Guide

Table of Contents

1. Overview

This directory contains Claude Code configuration files written in literate programming style using Org-mode. All configurations include detailed documentation explaining what they do and why.

Important: Before tangling, back up your existing .claude/ directory if you have one. Tangling will overwrite existing files.

2. File Structure

File Generates Description
01-settings.org .claude/settings.json Project settings and permissions
  .claude/settings.local.json Personal settings
02-commands.org .claude/commands/*.md Slash commands
03-skills.org .claude/skills/*/SKILL.md Agent skills
04-mcp-servers.org .mcp.json MCP server configs
05-subagents.org .claude/agents/* (future) Custom subagents
index.org - Navigation and overview
README.org - This guide

3. Usage

3.1. Before You Begin

  1. Back up existing configs: If you have .claude/ configs, back them up: 

    cp -r .claude .claude.backup
cp .mcp.json .mcp.json.backup  # if it exists
  2. Customize MCP paths: Edit 04-mcp-servers.org to update placeholder paths:
    • Change /path/to/mcp-emacs/ to your actual MCP server locations
    • Update any other project-specific paths
  3. Review settings: Check 01-settings.org for permission policies

3.2. Tangling Configurations

3.2.1. Tangle All Files (Recommended)

From the repository root: 

./tangle-claude.sh

This script tangles all org files in one command.

3.2.2. Tangle Individual File

  1. From Emacs

    Open any config file in Emacs and:

    • Run: M-x org-babel-tangle
    • Or: C-c C-v t
    • Or: C-u C-c C-v t to tangle with a different target file
  2. From Command Line
    emacs -Q --batch \
  --eval "(require 'org)" \
  --eval "(setq org-confirm-babel-evaluate nil)" \
  --eval "(find-file \"content/agents/claude-code/01-settings.org\")" \
  --eval "(org-babel-tangle)" \
  --kill

3.3. Viewing Documentation

3.3.1. HTML Export

Build the entire site: 

./build.sh

Then view in browser at public/agents/claude-code/index.html

3.3.2. In Emacs

Navigate through org files directly with:

  • C-c C-o on links to open files
  • TAB to expand/collapse sections
  • S-TAB to cycle visibility

4. Configuration Types

4.1. Project vs User Level

4.1.1. Project-Level Configurations

Location: .claude/, .mcp.json (in project root)

  • Version-controlled and shared with team
  • Use for: common commands, shared skills, project settings
  • Tangle to: Relative paths in project directory

What should be project-level:

  • Permission policies for the project
  • MCP servers everyone uses (Emacs, filesystem)
  • Common slash commands (/review, /commit-msg)
  • Team-wide skills
  • Project-specific environment variables

4.1.2. User-Level Configurations

Location: ~/.claude/ (in home directory)

  • Personal preferences, not in version control
  • Use for: personal commands, experimental skills, local tools
  • Tangle to: Absolute paths with ~/.claude/

What should be user-level:

  • Personal notification preferences
  • Local development tools
  • Experimental commands/skills
  • API keys and credentials
  • Personal MCP servers

4.2. Choosing Tangle Targets

Each code block in the org files has a :tangle directive. To switch between project and user level:

Example - Slash Command: 

# Project level (default in our configs)
#+begin_src markdown :tangle .claude/commands/my-command.md
...
#+end_src

# User level (change to home directory)
#+begin_src markdown :tangle ~/.claude/commands/my-command.md
...
#+end_src

5. Editing Guide

5.1. Adding a New Slash Command

  1. Open 02-commands.org
  2. Add a new section under appropriate category:

#+beginexample org

5.1.1. My Custom Command

Description of what this command does and when to use it. 

---
description: Brief description for command menu
argument-hint: "[what to pass]"
---

# My Custom Command

Instructions for Claude on how to handle this command.

User input: {{{ input }}}

#+endexample

  1. Tangle the file: C-c C-v t
  2. Test with /my-command in Claude Code

5.2. Creating a New Skill

  1. Open 03-skills.org
  2. Add section under appropriate category:

#+beginexample org

5.2.1. My Custom Skill

Description and use cases. 

---
name: My Skill Name
description: Clear description of when and how this skill activates
allowed-tools:
  - Read
  - Write
---

# My Skill Instructions

Detailed instructions for Claude on:
1. When to activate
2. What to do
3. How to do it

#+endexample

  1. Tangle the file
  2. Skill auto-activates based on description

5.3. Adding an MCP Server

  1. Open 04-mcp-servers.org
  2. Add server to appropriate section:

#+beginexample org

5.3.1. My MCP Server

Description of what this server provides. 

{
  "mcpServers": {
    "existing-server": { ... },
    "my-server": {
      "type": "stdio",
      "command": "/path/to/command",
      "args": ["arg1", "arg2"]
    }
  }
}

#+endexample

  1. Tangle and restart Claude Code

5.4. Modifying Settings

  1. Open 01-settings.org
  2. Update appropriate section
  3. Tangle to regenerate JSON
  4. Settings take effect on next Claude Code session

6. Best Practices

6.1. Documentation

  • Explain why, not just what - help future you understand the reasoning
  • Include examples in code blocks to demonstrate usage
  • Reference specific use cases to make it concrete
  • Note any gotchas, limitations, or platform-specific behavior

6.2. Code Blocks

  • Use appropriate language for syntax highlighting (:markdown, :json, :bash)
  • Include :mkdirp yes for nested paths to auto-create directories
  • Set :results none to avoid output cluttering the org file
  • Use descriptive section headers that explain what the config does

6.3. Organization

  • Group related configs together under the same parent heading
  • Use consistent heading levels throughout files
  • Keep examples practical and tested - don't include broken code
  • Update navigation links when adding new files

6.4. Version Control

Do commit:

  • Org source files (*.org)
  • Generated project configs (.claude/settings.json, .mcp.json)
  • Tangle script (tangle-claude.sh)

Do NOT commit:

  • Personal configs (.claude/settings.local.json)
  • Generated user configs in ~/.claude/
  • API keys or credentials

Update .gitignore: 

# Claude Code - ignore personal settings
.claude/settings.local.json

7. Troubleshooting

7.1. Tangle Paths Not Working

Symptom: Tangling doesn't create files in expected location

Solutions:

  • Ensure paths are correct (absolute vs relative)
  • Check that parent directories exist (or use :mkdirp yes)
  • Verify org-mode is properly loaded in Emacs
  • Check that the buffer has a filename (org file must be saved)
  • Try using absolute paths if relative paths don't work

7.2. JSON Syntax Errors

Symptom: Claude Code reports invalid JSON in settings or MCP config

Solutions:

  • Validate JSON after tangling: jq . .mcp.json
  • Check for trailing commas (not allowed in JSON)
  • Ensure proper escaping of quotes and special characters
  • Verify matching braces and brackets

7.3. Commands Not Appearing

Symptom: Slash command doesn't show up in / menu

Solutions:

  • Verify file is in .claude/commands/ directory
  • Check filename has .md extension
  • Restart Claude Code to reload commands
  • Check YAML frontmatter syntax (must be valid YAML)
  • Ensure description field is present in frontmatter

7.4. Skills Not Activating

Symptom: Skill doesn't automatically activate when expected

Solutions:

  • Ensure SKILL.md is in a subdirectory (e.g., .claude/skills/skill-name/SKILL.md)
  • Verify frontmatter is valid YAML
  • Check that description clearly explains when to activate
  • Make description more specific and contextual
  • Test with explicit scenarios that match the description

7.5. MCP Servers Not Working

Symptom: MCP tools not available or server fails to start

Solutions:

  • Verify paths in .mcp.json are correct (use absolute paths)
  • Check that MCP server executable exists and is executable
  • Test server command manually in terminal
  • Check Claude Code logs for specific error messages
  • Ensure Python/Node/etc runtime is available for the server
  • Verify enableAllProjectMcpServers is true in settings

7.6. Files Overwritten Unexpectedly

Symptom: Your custom edits to tangled files were lost

Explanation: Tangling regenerates files from org source. This is by design.

Solutions:

  • Always edit the org files, not the generated files
  • Use version control to track changes
  • Back up files before tangling if you have manual edits
  • Consider keeping a separate .local.json for overrides

8. Integration

This configuration is part of the larger personal knowledge base. See:

9. Resources

9.2. Examples and Inspiration