Detecting and Consolidating Duplicate AI Agent Skills Across Repositories

To detect and consolidate duplicate AI agent skills across repositories, engineering teams audit scattered .cursor/rules, .claude/skills, and AGENTS.md files using content-hashing scripts, identify semantic divergence between diverged instructions, and migrate repo-local copies into a centralized, version-controlled skill library that synchronizes across all developer environments and agent CLIs.

Why Do AI Agent Skills Duplicate Across Multiple Repositories?

AI agent skills duplicate across repositories because developers create custom instructions to solve immediate coding challenges within a single project checkout, and then copy those working configuration files into subsequent projects without a shared distribution mechanism. When an engineer discovers an effective prompt for API validation or unit test generation, copying the file feels like the fastest path forward.

As documented in the Anthropic Claude Code documentation, “Claude Code searches for skills in both personal (~/.claude/skills/) and project (.claude/skills/) directories.” Similarly, the Cursor Documentation on Project and Global Rules clarifies that “Project rules apply only to the repository where they are defined, while user rules apply globally across all your projects.” Because developers frequently overlook global scopes, they re-author or copy-paste identical rules into every microservice root.

Duplicate AI agent skills across microservice repositories cause instruction drift, where two agents working on identical frameworks apply contradictory linting and testing constraints. Within a 90-day development window, teams typically experience a 15-30% instruction drift between unlinked copies of the same skill, leading to flaky CI runs and mismatched code conventions across services.

How Does Multi-Repo Skill Duplication Degrade Agent Performance?

Multi-repo skill duplication degrades agent performance by inflating token consumption, triggering contradictory rule evaluations, and obscuring canonical engineering standards. When multiple configuration files with overlapping scopes exist within an environment, the AI model must allocate substantial context budget simply to ingest and reconcile redundant guidelines.

Cursor executes .cursor/rules/*.mdc rules sequentially based on file glob matches, meaning duplicate rules with identical globs force the model to parse redundant tokens on every file edit. An engineering workstation with duplicated 2,000-token rules across multiple active IDE tabs or worktrees wastes between 2,000 and 8,000 tokens on every single prompt execution. Over hundreds of daily interactions, this token inflation increases latency, accelerates model context window exhaustion, and causes hallucinated regressions.

Consolidating duplicate skills into a centralized skill manager eliminates repo-level drift while reducing prompt token consumption by up to 6,000 tokens per agent interaction. For detailed context optimization tactics, see our architectural analysis on auditing and pruning AI agent skills and our guide to fixing broken agent instructions across repositories.

How Can You Detect Duplicate Agent Skills Across Local Repositories?

You can detect duplicate agent skills across local repositories by running an automated discovery script that walks your workspace root, calculates 64-character hexadecimal SHA-256 hashes of all instruction files, and groups files by their declared YAML frontmatter names. This audit uncovers both exact duplicate files and drifted variants that share the same conceptual identity.

The following portable Python audit script scans all Git repositories in your projects directory, identifies SKILL.md, .mdc, and AGENTS.md files, and produces an actionable deduplication report:

#!/usr/bin/env python3
"""
audit_duplicate_skills.py: Audit and detect duplicate AI agent skills across repositories.
Identifies exact bitwise clones (SHA-256 matches) and drifted variants (name collisions).
"""
import os
import hashlib
import re
from pathlib import Path
from collections import defaultdict

WORKSPACE_DIR = os.path.expanduser("~/Projects")

# Target file patterns across Claude Code, Cursor, Codex, and Antigravity
TARGET_PATTERNS = ["**/SKILL.md", "**/.cursor/rules/*.mdc", "**/AGENTS.md", "**/CLAUDE.md"]

hash_registry = defaultdict(list)
name_registry = defaultdict(list)

def extract_skill_name(file_path):
    """Extract frontmatter name or fallback to parent directory name."""
    try:
        with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
            content = f.read(1024)
            match = re.search(r"^name:\s*["']?([^"'\n]+)["']?", content, re.MULTILINE)
            if match:
                return match.group(1).strip()
    except Exception:
        pass
    return Path(file_path).parent.name

print(f"Scanning {WORKSPACE_DIR} for AI agent skills and rules...")

for pattern in TARGET_PATTERNS:
    for path in Path(WORKSPACE_DIR).glob(pattern):
        # Ignore dependency and build directories
        if any(ignored in path.parts for ignored in ["node_modules", ".git", "target", "dist"]):
            continue
        try:
            content = path.read_bytes()
            file_hash = hashlib.sha256(content).hexdigest()
            skill_name = extract_skill_name(path)
            
            hash_registry[file_hash].append(str(path))
            name_registry[skill_name].append((str(path), file_hash))
        except Exception as e:
            print(f"Error reading {path}: {e}")

print("\n=== EXACT BITWISE DUPLICATES (Identical SHA-256 Hashes) ===")
for file_hash, paths in hash_registry.items():
    if len(paths) > 1:
        print(f"\nHash: {file_hash[:12]}... (found in {len(paths)} locations):")
        for p in paths:
            print(f"  - {p}")

print("\n=== INSTRUCTION DRIFT CANDIDATES (Same Skill Name, Divergent Hashes) ===")
for skill_name, entries in name_registry.items():
    unique_hashes = {h for _, h in entries}
    if len(unique_hashes) > 1:
        print(f"\nSkill Name: '{skill_name}' has drifted across {len(entries)} repositories:")
        for p, h in entries:
            print(f"  - [{h[:8]}] {p}")

Running this script across 10 to 20 microservices typically reveals that 40% of custom skills are redundant duplicates. Once identified, these files should be consolidated to restore architectural consistency.

The Sprawl Moment: The Outdated Migration Skill That Broke CI

A backend engineer maintains fifteen microservices across a distributed financial platform. When building a new order-processing service, they copy-paste a database migration skill from an older billing repository into .claude/skills/db-migrate/SKILL.md. Over the following six months, the core database infrastructure team updates the billing repository's skill with critical zero-downtime table locking assertions and rollback verifications. When a junior engineer runs a schema migration on the order-processing service using Claude Code, the agent executes the stale, unpatched local copy of the skill, triggering an exclusive table lock that halts checkout transactions in production—because the engineering team had fifteen diverging copies of the same skill scattered across fifteen repositories with no central synchronization.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

How Do You Consolidate Duplicated Rules into a Single Source of Truth?

You consolidate duplicated rules into a single source of truth by extracting universal guidelines from individual Git repositories, diffing diverged variants to merge improvements into a canonical package, and deploying that consolidated skill to a global, synchronized directory. This 4-step migration protocol eliminates repository clutter while ensuring every coding assistant accesses the latest instructions.

Step 1: Diff Diverged Variants to Preserve Critical Edge Cases

Before deleting repository-local copies, run a unified diff between the diverged files identified by your audit script:

# Compare two drifted variants of the same skill across repositories
git diff --no-index ~/Projects/billing-service/.claude/skills/db-migrate/SKILL.md \
                    ~/Projects/orders-service/.claude/skills/db-migrate/SKILL.md

Merge any repository-specific bug fixes or schema checks into a comprehensive, parameterized master skill. If one version contains edge-case handling for PostgreSQL enum types and the other handles foreign key indexes, combine both improvements into the canonical version.

Step 2: Promote the Master Skill to Global User Scope

Move the consolidated master skill into your user-level agent skills directory rather than checking it into individual Git repositories. For Claude Code, place the skill inside ~/.claude/skills/[skill-name]/SKILL.md:

# Create the canonical global skill directory
mkdir -p ~/.claude/skills/db-migrate

# Copy the merged master skill into personal global scope
cp master-db-migrate.md ~/.claude/skills/db-migrate/SKILL.md

Because Claude Code evaluates ~/.claude/skills/ across all terminal sessions, the consolidated workflow immediately becomes accessible across all repositories without requiring in-repo file copies. For more details on scoping, consult our guide on Claude skills across projects and folders.

Step 3: Purge Redundant In-Repo Copies

Delete the redundant local skill folders from your microservice repositories:

# Remove redundant repo-local skill copies to prevent precedence overrides
git -C ~/Projects/orders-service rm -r .claude/skills/db-migrate
git -C ~/Projects/billing-service rm -r .claude/skills/db-migrate
git commit -m "chore(ai): consolidate db-migrate skill into global skill library"

Removing local copies ensures that Claude Code falls back to your updated global skill rather than executing outdated local instructions.

Step 4: Automate Cross-Machine Synchronization with Prompttly

Maintaining global skills across multiple developer machines (such as a primary MacBook Pro and an office workstation) manually introduces the same drift problem across computers. Prompttly's two-way sync on macOS mirrors changes made in ~/.claude/skills/ back to the central library without manual git pushes or export scripts.

Whenever an engineer edits a skill in Prompttly's web app or updates a markdown file in their terminal, Prompttly synchronizes the change across Claude Code, Codex, and Cursor across all connected devices in under 200ms.

Resolving Precedence Conflicts Between Global and Local Rules

Resolving precedence conflicts requires understanding how each AI agent resolves namespace collisions when both a global instruction and a repository-local instruction exist. If an engineer forgets to remove a local copy, the agent's resolution hierarchy determines which instruction governs code generation.

In Cursor, because local and global rules concatenate additively, maintaining duplicate rules in both scopes forces the model to read conflicting instructions simultaneously. In Claude Code, an outdated local skill completely masks improvements made to your global skill. Consolidating into a clean single source of truth prevents both failure modes. For Git worktree setups, review our guide on syncing AGENTS.md across git worktrees, or read our comparative evaluation of open-source AI skill managers on GitHub.

When Should an Instruction Remain Strictly Repository-Local?

An instruction should remain strictly repository-local when it enforces constraints unique to a single codebase, such as service-specific port bindings, bespoke architectural patterns, or specialized build pipelines. Promoting repository-specific constraints to a global skill library pollutes the agent's context across unrelated projects.

Keep instructions strictly inside .cursor/rules/ or .claude/skills/ within the repository if they meet any of the following criteria:

• Proprietary Microservice Architectures: Rules dictating the exact GraphQL schema or message bus topics used exclusively by that individual service.
• Local Test Harness Configurations: Commands that invoke repository-specific Docker test containers, local mock endpoints, or internal seeding scripts.
• Non-Standard Build Flags: Specific compiler directives, linters, or legacy language version constraints required only for that legacy codebase.
• Team-Shared Repo Conventions: Architectural guidelines agreed upon by an entire engineering squad that must be versioned directly in Git alongside application source code.

Conversely, any instruction defining how to write clean TypeScript, format Git commits, generate unit test assertions, or author pull request summaries should be consolidated into your global Prompttly library. To turn your best workflows into reusable packages, try our free Claude Skill Creator.

Frequently Asked Questions About Duplicate AI Agent Skills