Global vs Project Skills
Claude Code skills can be scoped to a single project (live in .claude/skills/) or installed globally (live in ~/.claude/skills/) and available from any project. Choosing the right scope is a key part of skill architecture.
Key points
- Project-scoped skills live in
.claude/skills/within a project directory — visible only from that project [src-013]/SKILL.md - Globally-scoped skills live in
~/.claude/skills/in the home directory — available from any Claude Code session on the machine [src-013]/SKILL.md - Example: a
frontend-designskill useful across multiple projects belongs globally; apublish-to-wordpressskill tied to one blog project belongs locally [src-013] - Both levels follow the same Progressive Context Loading (Skills) pattern — frontmatter is loaded at session start, full skill.md only when triggered [src-013]
- Cloud routines clone only the linked GitHub repo, so they access only project-scoped skills; global skills must be added to the repo if needed in routines [src-013]
- Jack Roberts adds the cross-harness angle: Claude skills can be exported with implementation notes and recreated as Codex skills, turning skill scope into a portability concern rather than only a Claude Code concern [src-058].
Related entities
- Claude Code Skills — the entity being scoped
- Claude Code — the runtime
- Codex (OpenAI) — another runtime that can recreate or consume similar skill instructions
Related concepts
- Progressive Context Loading (Skills) — both scope levels use the same three-level loading pattern
- Four C’s of an AI Operating System — global skills belong to the Capabilities layer (C3) of the AIOS
- Claude Code Cloud Routines — routines access only project-scoped skills
- Agent Harness Portability — skill instructions can move between agent harnesses when documented explicitly
Source references
- [src-013] Nate Herk — “Build & Sell Claude Code Operating Systems (2+ Hour Course)” (2026-05-01)
- [src-058] Jack Roberts — “How to use Codex Better than 99% of People” (2026-05-06)
Recommended next
Keep reading from this thread
From 491 indexed pages and articles.
- Wiki concept Agent Harness Portability The practice of organizing project files, instructions, skills, tools, and operating context so multiple coding-agent runtimes can work in Related by skills
- Wiki concept Progressive Context Loading (Skills) The three-level loading pattern Claude Code uses to keep skills lightweight. Level 1: initial search only reads the YAML frontmatter (name + Related by skills
- Insight AI Beyond POCs How enterprise AI moves beyond proofs of concept through ownership, governance, measurement, adoption, and production operating models Readers have engaged with this next