52 lines
1.9 KiB
Markdown
52 lines
1.9 KiB
Markdown
---
|
|
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-01T22:02:48.108618+00:00"
|
|
relations:
|
|
- target: e0a851a7-1dc5-4191-b220-aa90112a1171
|
|
type: CAUSES
|
|
direction: outgoing
|
|
strength: 0.9
|
|
edge_id: 08489f38-78fc-4153-bad9-5d41e8c3164c
|
|
- target: 9e502d2b-bf95-4161-8190-ba153b9961d0
|
|
type: BUILDS_ON
|
|
direction: outgoing
|
|
strength: 0.8
|
|
edge_id: 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
|
|
|