Initial commit

2025-11-29 18:00:42 +08:00
commit cc49e355bc
37 changed files with 10917 additions and 0 deletions
--- a/skills/cross-repo-config/SKILL.md
+++ b/skills/cross-repo-config/SKILL.md
@@ -0,0 +1,358 @@
+---
+name: Managing Cross-Repository Configuration
+description: Use when user asks where to put configuration, skills, or learnings, or discusses sharing config across projects. Provides decision criteria for the three-tier architecture (global ~/.claude, plugin, project-local .claude) to prevent duplication and ensure reusability. Invoke before creating new skills or configuration to determine the correct tier and location.
+---
+
+# 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:**
+```markdown
+# 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:**
+```markdown
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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/`:
+
+```bash
+#!/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:
+```bash
+./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:**
+
+```markdown
+# 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