claude-memory/graph/decisions/skill-organization-scoped-user-skills-over-symlinks-6cc417.md

id	type	title	tags	importance	confidence	created	updated	relations
6cc417e2-8b8a-4629-a611-b2b379ad39b4	decision	Skill organization: scoped user skills over symlinks	claude-code skills organization best-practices scope-guards claude-code-config	0.8	0.8	2026-03-01T05:48:08.265336+00:00	2026-03-01T22:02:48.108618+00:00	target type direction strength edge_id e0a851a7-1dc5-4191-b220-aa90112a1171 CAUSES outgoing 0.9 08489f38-78fc-4153-bad9-5d41e8c3164c target type direction strength edge_id 9e502d2b-bf95-4161-8190-ba153b9961d0 BUILDS_ON outgoing 0.8 30e44ec2-f9ea-49db-bf2e-6e9a98508c94

Skill Organization Strategy: Scoped User Skills Over Symlinks

Decision

When skills need to be shared across multiple projects but not all projects, prefer keeping them as user skills (~/.claude/skills/) with SCOPE guards in the description rather than symlinking into project directories.

Problem with Symlinks

• Maintenance burden: forgetting to link in new projects
• Broken paths if drive is unmounted (e.g., /mnt/NV2/ not available)
• Have to remember to update all symlink locations when skill changes

Solution: Scope Guards

Append to the description field in SKILL.md frontmatter:

SCOPE: Only use in repo-a, repo-b repos. Do not activate in unrelated projects.

Token overhead is minimal (~50-100 tokens per skill description).

Three-Tier Architecture

1. Universal user skills — no scope guard, active everywhere (e.g., commit, review-pr)
2. Scoped user skills — with SCOPE guard, active only in named repos
3. Project skills — live in .claude/skills/ inside a single repo, not shared

Rationale

• Single source of truth in ~/.claude/skills/
• No symlink management
• Claude respects scope guards in skill descriptions
• Easy to update scope by editing one file