store: Skill organization: scoped user skills over symlinks

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

@@ -0,0 +1,39 @@
+---
+id: 6cc417e2-8b8a-4629-a611-b2b379ad39b4
+type: decision
+title: "Skill organization: scoped user skills over symlinks"
+tags: [claude-code, skills, organization, best-practices, scope-guards, claude-code-config]
+importance: 0.8
+confidence: 0.8
+created: "2026-03-01T05:48:08.265336+00:00"
+updated: "2026-03-01T05:48:08.265336+00:00"
+---
+
+# 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