From 969f78918ee0fab35c35bdfd1934afb4399144dc Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Sat, 28 Feb 2026 23:48:08 -0600 Subject: [PATCH] store: Skill organization: scoped user skills over symlinks --- ...scoped-user-skills-over-symlinks-6cc417.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 graph/decisions/skill-organization-scoped-user-skills-over-symlinks-6cc417.md diff --git a/graph/decisions/skill-organization-scoped-user-skills-over-symlinks-6cc417.md b/graph/decisions/skill-organization-scoped-user-skills-over-symlinks-6cc417.md new file mode 100644 index 00000000000..c13a6d7c38c --- /dev/null +++ b/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