Managing Cross-Repository Configuration

When working across multiple repositories (e.g., your marketplace repo, vLLM, llama stack, etc.), you need a clear strategy for where to store configurations, learnings, and skills to ensure consistency without duplication.

Three-Tier Architecture

Claude Code supports three tiers of configuration, each with specific use cases:

1. Global Configuration (~/.claude/CLAUDE.md)

Use for:

• •Personal coding style preferences
• •General development patterns you prefer across all projects
• •Your personal workflow preferences
• •Cross-language, cross-project knowledge
• •Tool usage preferences
• •Communication style preferences

Benefits:

• •Automatically available in ALL repositories
• •No installation or setup needed
• •Single source of truth for personal preferences
• •Simplest approach for most user preferences

Example content:

# Python code style
- Always put imports at the top of the file, not within methods
- Use descriptive variable names over comments

# General preferences
- Prefer Edit tool over Write for existing files
- Keep commit messages concise and action-oriented

2. Plugin Skills (in marketplace/plugin repos)

Use for:

• •Domain-specific expertise (e.g., PR review patterns, testing strategies)
• •Shareable, reusable capabilities
• •Structured knowledge for specific problem domains
• •Workflow patterns others might benefit from

Benefits:

• •Versioned and organized by domain
• •Shareable across teams
• •Available wherever marketplace is installed
• •Can be distributed and maintained separately

When to use:

• •Creating reusable capabilities for specific domains
• •Knowledge that should be version-controlled
• •Patterns that could benefit others
• •Structured workflows with multiple steps

3. Project-Local Configuration (.claude/CLAUDE.md in project)

Use for:

• •This specific codebase's architecture patterns
• •Project-specific conventions and decisions
• •Team agreements for this repository
• •Codebase-specific context

Benefits:

• •Only applies to this repository
• •Can be committed to version control
• •Shared across team members
• •Won't interfere with other projects

Example content:

# This Project's Patterns

- Authentication uses JWT tokens stored in httpOnly cookies
- All API routes go through middleware/auth.ts
- Database migrations use Prisma in prisma/migrations/

Decision Framework

When deciding where to store configuration or learnings, ask:

Is this personal preference? → Global (~/.claude/CLAUDE.md)

• •Coding style you prefer
• •Your workflow patterns
• •How you like tools to be used

Is this shareable domain knowledge? → Plugin Skill

• •PR review techniques
• •Testing strategies
• •Deployment patterns
• •General best practices

Is this specific to one codebase? → Project-Local (.claude/CLAUDE.md)

• •Where files are located in this repo
• •This project's architecture decisions
• •Team conventions for this codebase

Cross-Repository Consistency

To ensure consistency across all repositories:

For Personal Preferences

Use ~/.claude/CLAUDE.md exclusively. This automatically applies everywhere you use Claude Code.

For Domain Knowledge

Create plugin skills in a marketplace repository:

1. •Develop skills in your marketplace source repo
2. •Version and commit skills
3. •Install marketplace globally or per-project
4. •Skills available wherever marketplace is installed
5. •Update skills in source repo, push changes
6. •Other repos get updates when they reload

For Project-Specific Patterns

Use project-local .claude/CLAUDE.md committed to that repository's version control.

Implementation Pattern: The /learn Command

A well-designed /learn command should:

1. •Identify the learning type from the conversation
2. •Ask the user which tier is appropriate:
   • •Global: Personal preferences
   • •Plugin Skill: Domain expertise
   • •Project-Local: This codebase's patterns
3. •Save accordingly:
   • •Global: Append to ~/.claude/CLAUDE.md
   • •Plugin: Use skill-builder to create/update skill
   • •Project: Append to .claude/CLAUDE.md in current repo
4. •Confirm where the learning was saved

This ensures learnings are:

• •Scoped appropriately
• •Discoverable where needed
• •Not duplicated across tiers

Common Anti-Patterns

DON'T:

• •Store personal preferences in project-local files (won't follow you)
• •Store project-specific patterns globally (pollutes other projects)
• •Create plugin skills for one-off project patterns
• •Duplicate the same guidance across multiple tiers

DO:

• •Use the simplest tier that meets your needs
• •Default to global for personal preferences
• •Use plugins for reusable, shareable knowledge
• •Keep project-local truly project-specific

Validation

To verify your configuration architecture:

1. •Test global application: Check that ~/.claude/CLAUDE.md preferences apply in a new, unrelated repository
2. •Test plugin availability: Verify plugin skills work in projects where the marketplace is installed
3. •Test isolation: Confirm project-local settings don't leak to other repositories
4. •Check for duplication: Ensure the same guidance doesn't exist in multiple tiers

Example Scenario

Situation: You learn a better way to write commit messages while working on vLLM.

Decision process:

• •Is this how YOU prefer all commit messages? → Global
• •Is this a general best practice for commit messages? → Plugin Skill
• •Is this how vLLM specifically wants commits? → Project-Local

Most likely: Global (~/.claude/CLAUDE.md) because commit message style is typically a personal preference that should apply everywhere you work.

Working with Git Worktrees

When frequently context-switching between multiple PRs or bugs, git worktrees provide a better workflow than stashing or multiple clones.

Why Worktrees?

Use worktrees when:

• •You need to switch between multiple branches/PRs frequently throughout the day
• •You want separate working directories for each branch
• •You don't want to stash/commit WIP when context-switching

Benefits over alternatives:

• •Each worktree is a separate directory with its own branch
• •Share the same .git repository (saves space vs multiple clones)
• •No need to stash/commit when switching contexts
• •Claude Code can work independently in each worktree

Basic Worktree Usage

# Create worktree for existing branch
git worktree add ../myrepo-feature-x feature-x

# Create worktree with new branch
git worktree add ../myrepo-bugfix -b bugfix/issue-123

# List all worktrees
git worktree list

# Remove worktree when done
git worktree remove ../myrepo-feature-x

Sharing .claude Configuration Across Worktrees

Scenario 1: Team project where .claude/ is committed

No special setup needed! The .claude/CLAUDE.md file is in version control, so all worktrees automatically share the same configuration through git.

Scenario 2: Large OSS project where .claude/ cannot be committed

Use symlinks to share your project-local configuration across worktrees:

# In your main worktree (keep the real .claude directory here)
ls .claude/CLAUDE.md  # Verify it exists

# In each additional worktree
cd ../myrepo-feature-x
rm -rf .claude  # Remove if it exists
ln -s /full/path/to/main-worktree/.claude .claude

# Prevent accidental commits
echo ".claude" >> .git/info/exclude

Automation Script for OSS Projects

Create a script to automate worktree creation with shared .claude/:

#!/bin/bash
# create-worktree.sh
PROJECT_NAME=$(basename $(git rev-parse --show-toplevel))
MAIN_WORKTREE=$(git rev-parse --show-toplevel)
BRANCH=$1
WORKTREE_DIR="../${PROJECT_NAME}-${BRANCH}"

# Create the worktree
git worktree add "$WORKTREE_DIR" -b "$BRANCH"

# Symlink .claude directory
cd "$WORKTREE_DIR"
rm -rf .claude
ln -s "${MAIN_WORKTREE}/.claude" .claude

# Exclude from git
echo ".claude" >> .git/info/exclude

echo "Worktree created at $WORKTREE_DIR with shared .claude config"

Usage:

./create-worktree.sh feature/new-optimization

Worktree Configuration Strategy

With worktrees, your three-tier configuration works seamlessly:

1. •

   Global (~/.claude/CLAUDE.md)

   • •Automatically available in all worktrees
   • •No setup needed
2. •

   Plugin Skills (from marketplace)

   • •Available wherever marketplace is installed
   • •Works the same in all worktrees
3. •

   Project-Local (.claude/CLAUDE.md)

   • •Committed projects: Shared automatically via git
   • •Uncommitted (OSS): Shared via symlinks

Common Worktree Mistakes

DON'T:

• •Use multiple full clones (wastes space and creates sync issues)
• •Create separate .claude/ directories in each worktree (causes divergence)
• •Forget to symlink .claude/ in OSS projects

DO:

• •Use worktrees for frequent context-switching
• •Symlink .claude/ for OSS projects where you can't commit configuration
• •Keep one "main" worktree with the real .claude/ directory
• •Add .claude to .git/info/exclude in OSS projects

Ensuring Critical Skills Are Always Available

Plugin skills are model-invoked based on description matching. For critical workflow information you want guaranteed in every session, use a hybrid approach.

Hybrid Pattern: Global + Plugin

When to use:

• •A plugin skill contains critical day-to-day workflow information
• •You want core concepts available in every session, every project
• •You need detailed guidance available on-demand

Implementation:

1. •

   Brief essentials in global config (~/.claude/CLAUDE.md):

   • •Key reminders and principles
   • •Quick reference to core concepts
   • •Pointer to the detailed skill
2. •

   Comprehensive details in plugin skill:

   • •Full workflows and examples
   • •Decision frameworks
   • •Automation scripts
   • •Edge cases and anti-patterns

Example:

# In ~/.claude/CLAUDE.md (always loaded)

# Claude Code Configuration
- Three tiers: Global (~/.claude/CLAUDE.md), Plugin Skills, Project-Local (.claude/CLAUDE.md)
- For detailed guidance, use the cross-repo-config skill

# Git Worktrees for Context-Switching
- Use git worktrees (not multiple clones) for frequent PR/bug switching
- In OSS projects: symlink .claude/ from main worktree
- For automation scripts, use the cross-repo-config skill

Benefits:

• •Global config ensures core concepts are always present ✅
• •Skill provides detailed guidance when needed ✅
• •Reduces skill file size (progressive disclosure) ✅
• •Improves discoverability (explicit skill reference) ✅
• •User can quickly reference essentials ✅

Don't:

• •Duplicate all skill content in global config
• •Put project-specific patterns in global config
• •Rely solely on skill discoverability for critical workflows

Do:

• •Keep global config entries brief (1-3 bullets per topic)
• •Point to the skill name explicitly for details
• •Ensure the skill is globally installed if critical

Tips for Success

1. •Start with global: Most personal preferences belong in ~/.claude/CLAUDE.md
2. •Plugin skills for patterns: Use when you'd answer "others could benefit from this"
3. •Project-local is rare: Only truly project-specific architecture belongs here
4. •Review periodically: Check if project-local settings should be elevated to global
5. •Keep it simple: Don't over-engineer the tier structure
6. •Use worktrees for context-switching: Better than stashing or multiple clones
7. •Symlink .claude in OSS projects: Share configuration across worktrees when you can't commit
8. •Hybrid for critical skills: Brief in global, detailed in skill, both globally available