Claude Skills Across Projects: Folders, Scopes, and Cross-Repo Sync

To use Claude skills across projects without duplicating files, store global habits in your personal folder at ~/.claude/skills/ and repo-specific rules in .claude/skills/. When skill names collide, project-scoped skills strictly override personal skills. Managing a single versioned library prevents configuration drift across repositories, machines, and tools.

Where Are Claude Code Skills Stored on Your Computer?

Claude Code stores skills in two distinct filesystem locations: personal skills live in ~/.claude/skills/[skill-name]/ in your home directory, while project skills live in .claude/skills/[skill-name]/ at the root of a git repository. Personal skills follow your terminal user across every project and directory, whereas project skills activate only when Claude Code runs inside that specific repository.

According to the official Anthropic Claude Code Documentation, Claude Code scans both directories upon initialization. When a skill exists in both scopes with identical directory names, project-scoped skills strictly override personal skills, ensuring local repository constraints supersede global developer habits.

You can initialize both scopes directly from your terminal using standard shell commands:

# Create a personal global skill (available in all terminal sessions)
mkdir -p ~/.claude/skills/code-review-rubric
touch ~/.claude/skills/code-review-rubric/SKILL.md

# Create a project-scoped repository skill (shared via git)
mkdir -p .claude/skills/repo-release-check
touch .claude/skills/repo-release-check/SKILL.md

A Claude Code skill remains portable only when its directory structure, frontmatter triggers, and relative references travel together. If Claude fails to detect a skill after moving directories, review our troubleshooting guide on fixing Claude skills that are not working and verify that frontmatter syntax conforms to the agent skills and SKILL.md specification.

How Do Skill Folders Map Across Claude Code, Cursor, Codex, and Antigravity?

Skill folders map across developer tools through distinct filesystem conventions, ranging from on-demand modular directories to persistent system prompt preambles. While Anthropic Claude Code and OpenAI Codex evaluate isolated skill folders on demand, Cursor and Windsurf inject rules directly into conversation prompt headers.

As highlighted in the Cursor Rules Documentation, “Rules allow you to provide custom instructions that are included in every request to the model” via .cursor/rules/*.mdc files. Unlike Claude Code's on-demand skill execution, unconstrained IDE rules consume context tokens on every single message turn.

For technical guidance on managing instruction files across different toolchains, consult the official OpenAI Prompt Engineering Documentation and our comparison of Claude Skills vs Cursor Rules, CLAUDE.md, and AGENTS.md.

Why Does Copying Skills Between Repositories Break Down?

Copying skill folders between repositories breaks down because git repositories isolate file histories, creating silent configuration drift across projects. When you refine a code review rubric or refactoring workflow in one repository, those improvements never propagate to your other projects.

The first copied skill usually feels harmless: you write an effective TypeScript review checklist in one repository, paste the folder into a second project, adjust two lines, and commit. Three months later, five different repositories hold five divergent variations of the same workflow. When a teammate asks which prompt contains the canonical standard, the answer depends on individual memory rather than a reliable system.

This manual duplication pattern introduces three distinct failure modes:

• Configuration Drift: Critical improvements, bug fixes, and security checks added in Repository A remain completely absent from Repositories B and C.
• Context Window Waste: Developers frequently copy repo-specific test scripts or API endpoints into global instructions, forcing the agent to process irrelevant facts in unrelated codebases.
• Onboarding Friction: New team members inherit fragmented, out-of-date instructions rather than a clean, documented standard.

To systematically discover and merge identical instruction folders across your local checkouts, follow our step-by-step framework on detecting and consolidating duplicate AI agent skills across repositories.

The Sprawl Moment: The Mystery of the Disappearing Local Skill

An engineer writes a high-precision TypeScript schema migration skill inside their personal dotfiles at ~/.claude/skills/migrate-schema. It performs flawlessly across three production microservices, catching unindexed foreign keys and enforcing zero-downtime column migrations. Later that week, they clone a legacy billing repository that happens to contain an abandoned, year-old experiment at .claude/skills/migrate-schema/SKILL.md. When they execute /migrate-schema in their terminal, Claude Code quietly resolves the local project folder instead of the user's updated global skill. The agent generates deprecated database syntax, fails type assertions, and leaves the engineer debugging prompt phrasing for two hours before discovering the hidden repo override.

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.

With Prompttly's native Mac hotkey palette, you can open your entire verified skill library from anywhere with a single keystroke and instantly insert or sync instructions across apps without hunting through dotfiles or terminal paths.

How Do You Separate Reusable Habits From Repo-Specific Rules?

You separate reusable habits from repo-specific rules by isolating durable developer methodology into global skills while keeping codebase-specific commands and architecture notes inside the repository. A code review rubric belongs in global scope because review principles apply across projects, whereas database seed commands belong strictly in project scope.

Consider the contrast between an overly coupled repo prompt and a clean, portable global skill:

# WEAK: Overly coupled to a single repository
Review this diff for the Billing Dashboard repo.
Run npm run test:billing and check the Stripe webhook rules in /docs/billing.md.
Ensure the invoice preview component still adheres to our enterprise account policy.

# STRONG: Reusable methodology that applies across all codebases
Review this diff for financial transaction risk, state transitions, or auth changes.
Check behavior alterations, missing boundary tests, rollback hazards, customer-facing copy,
data integrity, and retry edge cases around network failures and permission boundaries.

Weak global skills carry hidden repository assumptions. Strong global skills encode repeatable engineering judgment that enhances every codebase you touch.

What Files Belong Inside a Multi-File Claude Code Skill Folder?

A valid Claude Code skill directory requires one mandatory entrypoint file named SKILL.md, supplemented by optional subdirectories for templates, examples, and validation scripts. Structuring skills into modular multi-file directories keeps the primary instruction file concise while providing rich reference data on demand.

cross-repo-review/
├── SKILL.md
├── examples/
│   ├── risky-migration-diff.md
│   └── clean-refactor-diff.md
├── scripts/
│   └── run-typecheck.sh
└── templates/
    └── review-summary-template.md

The SKILL.md entrypoint defines the YAML 1.2 frontmatter metadata that Claude Code indexes during startup:

---
name: cross-repo-review
description: Review code changes for architectural risk, regression hazards, missing tests, and backward compatibility across repositories.
version: 1.2.0
author: Engineering Platform Team
---

When reviewing a code change, prioritize structural risk and correctness over cosmetic formatting:
1. Identify behavioral changes in core business logic or public API contracts.
2. Flag missing unit or integration tests for newly introduced logic branches.
3. Verify backward compatibility with existing database schemas and stored state.
4. Return findings ordered strictly by severity: Blocker, High, Medium, Low.

When authoring multi-file packages, follow our in-depth architectural guide on modular multi-file Claude skills to ensure relative file references resolve correctly across working directories. You can also generate clean starting templates with our free Claude Skill Creator.

How Do Personal and Project Skills Work Together in Practice?

Personal skills and project skills work together through layered composition, where a global personal skill defines the overarching methodology and a local project skill supplies repo-specific commands and constraints. By giving personal and project skills distinct names (such as /code-review globally and /repo-check locally), you prevent naming collisions while equipping the agent with both perspectives.

In this architecture, your personal skill provides the durable review standard:

~/.claude/skills/code-review/SKILL.md
# Global Code Review Rubric
- Evaluate logic correctness, regression risk, and security hygiene.
- Check edge cases for empty state, network timeouts, and concurrency.

Meanwhile, the repository maintains its own local skill with specific build targets and CI constraints:

.claude/skills/repo-check/SKILL.md
---
name: repo-check
description: Run repository verification checks for the authentication microservice.
---

Apply global code review principles, then execute these repo-specific validation gates:
- Execute 'cargo test --all-features' and ensure zero compiler warnings.
- Verify that SQL migration scripts include rollback transactions in /migrations.
- Confirm that OpenAPI schemas in /docs/swagger.json match route annotations.

This layered pattern gives you the best of both worlds: universal engineering standards that travel across every project, paired with strict repository gates checked directly into Git.

A 5-Step Checklist to Migrate Existing Repo Copies Safely

Migrating duplicated repository skills into a unified architecture requires inventorying existing copies, extracting reusable methodology, and preserving repository-specific nuances before deleting duplicate folders.

1. Inventory Active Copies: Search your project directories for .claude/skills/, .cursor/rules/, and AGENTS.md to catalog duplicate workflows.
2. Extract the Stable Methodology: Identify common review rubrics, formatting guidelines, or triage patterns across all copies and extract them into a single global skill.
3. Strip Codebase Assumptions: Remove hardcoded repository paths, private API endpoints, and toolchain commands from the global instruction file.
4. Re-delegate Local Constraints: Keep codebase-specific test commands and deployment steps inside the repository's .claude/skills/ folder.
5. Verify Cross-Repo Execution: Test the global skill inside at least two separate projects to confirm it executes reliably without missing context before deleting legacy copies.

If you struggle with broken symlinks or rule divergence across git worktrees, review our companion guide on fixing agent instructions across repos and worktrees.

When Should an AI Agent Skill NOT Be Stored Globally?

An AI agent skill should not be stored globally when it contains sensitive credentials, proprietary business logic, one-off debugging experiments, or build commands unique to a single repository. Storing repo-specific constraints in global scope risks polluting unrelated projects with incorrect assumptions and hallucinated commands.

• Private Infrastructure & Secrets: Database connection strings, internal API keys, and private URLs must never enter personal dotfiles or global skill directories.
• Ephemeral Debugging Prompts: One-off triage prompts or temporary test harnesses should stay in project notes or be discarded after resolution.
• Stack-Specific Commands: Commands like pytest -m integration or cargo clippy belong in repository skills unless all your projects share an identical build system.
• Unilateral Team Rules: Standardizing a workflow across a team requires consensus. Use our comprehensive guide on how to share Claude skills and team AI workflows to agree on shared skills before rollout.

The goal is a lean, dependable library of high-impact skills that elevate your productivity across every environment you use.

Frequently Asked Questions About Claude Skills Across Projects

Related Resources

Browse our complete library on the Prompttly resources hub. To explore the technical foundations of agent instructions, read our guide on agent skills and SKILL.md architecture. Learn how to install and use Claude skills, explore how to sync Claude skills across computers, and read our migration checklist for transferring Claude Code settings to a new computer. When coordinating across multiple coding assistants, consult our guide to managing prompt sprawl in AI agents.