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/<name>/SKILL.md within a project directory — visible only from that project ^[src-013]
• Globally-scoped skills live in ~/.claude/skills/<name>/SKILL.md in the home directory — available from any Claude Code session on the machine ^[src-013]
• Example: a frontend-design skill useful across multiple projects belongs globally; a publish-to-wordpress skill tied to one blog project belongs locally ^[src-013]
• Both levels follow the same Progressive Context Loading 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 — another runtime that can recreate or consume similar skill instructions

Related concepts

• Progressive Context Loading — both scope levels use the same three-level loading pattern
• Four Cs Aios — 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)