Workflow 002: Monorepo Skills Setup

Fresh

Overview

Configure package-specific skills in monorepo setups with automatic discovery.

How Monorepo Discovery Works

When you work with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills/ directories.

Setup Procedure

Step 1: Root-Level Skills (Shared)

Create skills that apply to the entire monorepo:

mkdir -p .claude/skills/lint-all
mkdir -p .claude/skills/run-tests

Step 2: Package-Level Skills (Specific)

Create skills specific to each package:

# Frontend-specific skills
mkdir -p packages/frontend/.claude/skills/component-generator
mkdir -p packages/frontend/.claude/skills/storybook-setup

# Backend-specific skills
mkdir -p packages/backend/.claude/skills/api-endpoint
mkdir -p packages/backend/.claude/skills/migration-runner

Step 3: Additional Directories

Use --add-dir for shared skill libraries:

claude --add-dir /path/to/shared-skills

Skills from --add-dir directories:

• Load automatically
• Support live change detection (edit without restart)
• .claude/skills/ within those directories are discovered

CLAUDE.md Loading

CLAUDE.md files from --add-dir directories are NOT loaded by default. Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 to enable.

Step 4: Directory Structure

monorepo/
  .claude/
    skills/
      lint-all/SKILL.md          # Available everywhere
      run-tests/SKILL.md         # Available everywhere
  packages/
    frontend/
      .claude/
        skills/
          component-gen/SKILL.md # Only when editing frontend
          storybook/SKILL.md     # Only when editing frontend
    backend/
      .claude/
        skills/
          api-endpoint/SKILL.md  # Only when editing backend
          migration/SKILL.md     # Only when editing backend

Verification Checklist

• [ ] Root skills accessible from all packages
• [ ] Package skills only appear when editing files in that package
• [ ] No name conflicts between packages
• [ ] --add-dir skills load with live reload
• [ ] Committed to version control for team access