How to Organize Claude Code Skills So They Don't Conflict at Scale

Summary:

1. The numbering system: 01-11 folders that prevent naming collisions.
2. Real migration: 15 skills with conflicts, fixed in 25 minutes.
3. The 40-line rule: any skill over 40 lines has scope creep.
4. Team patterns: repo commits, submodules, and template repos.
5. Second migration walkthrough with exact rename mappings.

A Reddit post on r/ClaudeCode with 100 upvotes said it clearly: “You don’t have a Claude Code problem, you have an architecture problem.”

The post was about a developer with 15 skills that kept conflicting. Claude would follow one rule and break another. The issue was not Claude’s understanding. The issue was style.md competing with style-v2.md, outdated files nobody deleted, and scope creep turning focused skills into unfocused monsters.

I fixed that exact situation for a client in 25 minutes.

What does a clean skills architecture look like?

Numbered folders. Each folder scopes a category. The numbers create implicit priority.

.claude/skills/
├── 01-style/
│   └── code-conventions.md       # Naming, imports, exports
├── 02-testing/
│   └── test-standards.md         # Framework, assertions, patterns
├── 03-docs/
│   └── documentation.md          # JSDoc, README, comments
├── 04-architecture/
│   └── project-structure.md      # File layout, module boundaries
├── 05-errors/
│   └── error-handling.md         # Error types, logging, recovery
├── 06-performance/
│   └── performance-rules.md      # Query optimization, caching
├── 07-security/
│   └── security-checks.md        # Input validation, auth patterns
├── 08-devops/
│   └── deployment.md             # CI/CD, environment config
├── 09-communication/
│   └── code-review.md            # Review format, PR descriptions
├── 10-project/
│   └── project-specific.md       # This project's unique rules
└── 11-global/
    └── stop-slop.md              # Universal quality rules

01-03 are defaults that every project needs. 04-06 cover engineering concerns. 07-08 handle compliance. 09 governs communication style. 10-11 hold project-specific and global rules.

When Claude encounters a conflict between two skills, the numbered order resolves it. A rule in 02-testing/ takes priority over a generic mention in 09-communication/. This is how you prevent the Jest-vs-Vitest collision that shows up in almost every skills audit.

What did the real migration look like?

The client had 15 skills in a flat directory:

# Before: the mess
.claude/skills/
├── style.md           # Original code style
├── style-v2.md        # "Updated" but still loaded alongside v1
├── code-review.md     # Mentioned Jest (conflicted with testing.md)
├── testing.md         # Specified Vitest
├── stop-slop.md       # 60 lines, mixed coding + writing rules
├── docs.md            # Only 4 lines, barely did anything
├── security.md        # Solid, no issues
├── react-stuff.md     # Vague name, scope unclear
├── api-rules.md       # Half architecture, half error handling
└── ... 6 more files with unclear scope

Problems: naming collisions (style.md vs style-v2.md), conflicting rules (Jest in one file, Vitest in another), scope creep (stop-slop.md at 60 lines covering two domains), and dead files (docs.md too vague to do anything).

The 25-minute fix:

# Step 1: Audit current state (3 minutes)
wc -l .claude/skills/*.md | sort -n
# Identify files over 40 lines (scope creep signal)
grep -r "jest\|Jest" .claude/skills/   # Find conflicts
grep -r "semicolons" .claude/skills/   # Find conflicts

# Step 2: Create numbered structure (2 minutes)
mkdir -p .claude/skills/{01-style,02-testing,03-docs,04-architecture,05-errors,07-security,09-communication,11-global}

# Step 3: Migrate and rename (15 minutes)
mv style.md      01-style/code-conventions.md
rm style-v2.md   # Delete: conflicts resolved in code-conventions.md
mv testing.md    02-testing/test-standards.md
mv docs.md       03-docs/documentation.md   # Also expanded to 15 lines
mv api-rules.md  04-architecture/api-structure.md   # Split error parts out
mv security.md   07-security/security-checks.md
mv code-review.md 09-communication/code-review.md   # Removed Jest mention
mv stop-slop.md  11-global/stop-slop.md   # Trimmed to 30 lines

# Step 4: Verify no conflicts remain (5 minutes)
grep -r "jest\|Jest" .claude/skills/
# Should return zero hits (unless you actually use Jest)

The second migration I did was even more targeted. Six renames:

Old name                  → New location
──────────────────────────────────────────────────────────────
code-style.md             → 01-style/code-conventions.md
stop-slop.md              → 11-global/stop-slop.md
react-stuff.md            → 04-architecture/react-patterns.md
my-testing.md             → 02-testing/test-standards.md
review.md                 → 09-communication/code-review.md
misc-rules.md             → DELETED (rules merged into relevant files)

How do you know when a skill has scope creep?

Any skill over 40 lines is a signal. Not a hard failure, but a signal worth investigating.

# Scope creep check — run weekly
echo "=== Skills over 40 lines ==="
for f in .claude/skills/**/*.md; do
  lines=$(wc -l < "$f")
  if [ "$lines" -gt 40 ]; then
    echo "  WARNING: $f ($lines lines)"
  fi
done

echo ""
echo "=== Total skills word count ==="
wc -w .claude/skills/**/*.md | tail -1
# If total exceeds 5,000 words, Claude's context gets crowded

A 60-line skill is doing two jobs. Split it. A 15-line style skill and a 15-line naming skill will both fire more reliably than one 30-line file trying to handle both.

How do teams share skills?

Three patterns, each for a different team size:

Small team (2-5 people): Commit skills to the repo. Everyone pulls the same files. One person owns updates.

# Skills committed alongside code
git add .claude/skills/
git commit -m "feat(skills): add code style and testing standards"
# Every team member gets skills on git pull

Medium team (5-20 people): Git submodule for shared standards. Project-specific skills stay local.

# Shared standards as submodule
git submodule add git@github.com:company/claude-skills-shared.git .claude/skills-shared
# Symlink shared skills into the skills directory
ln -s .claude/skills-shared/01-style/ .claude/skills/01-style
# Project-specific skills go directly in .claude/skills/10-project/

New projects: Template repo with starter skills. Clone it, customize the project-specific folder, start working.

What broke

During the first migration, I moved all 15 files at once without testing. Three of the renamed files had internal cross-references. The code review skill referenced “see style.md for naming rules.” After renaming, that reference pointed nowhere.

Fix: after moving files, grep for internal references.

# Find cross-references that broke during migration
grep -r "\.md" .claude/skills/ | grep -v "^Binary"
# Any reference to a filename that no longer exists = broken link

What should you actually do?

• If you have fewer than 5 skills —> you don’t need folders yet. Keep flat files with clear names. Add the numbered structure when you hit 8-10 skills.
• If you have 10+ skills with conflicts —> run the 25-minute migration from this article. Create numbered folders, move files, delete duplicates, grep for conflicts. You will fix 90% of your “Claude ignores my rules” problems.
• If you work on a team —> commit skills to the repo immediately. Shared skills in a submodule if you have company-wide standards. The cost of skills drift across team members is hours of inconsistent output per week.

bottom_line

• Numbered folders (01-11) prevent naming collisions and establish implicit priority. This is the fix for “my skills conflict with each other.”
• Any skill over 40 lines has scope creep. Split it. Two 15-line focused skills outperform one 40-line unfocused skill every time.
• Teams must centralize skills in version control. Individual copies drift within weeks, and the inconsistency costs more than the setup. Git submodules are the cleanest pattern for cross-repo sharing.