feat(skill-writer): Add scope-aware encapsulation depth gate

A skill's body should not exceed its registration scope. Global skills that hard-code project-specific identifiers ship them to every consumer, where the references resolve to nothing.

- design-principles.md: new Scope-Aware Encapsulation section pairs registration locations with what the body may reference, and sets the rule for resolving scope before authoring.
- mode-selection.md: scope mismatch on global registration is now a hard failure in the authoring path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: the-simian

skills/skill-writer/references/design-principles.md

@@ -67,6 +67,22 @@ Use this guide to keep skill instructions dense, scannable, and worth their toke
 - Reuse established repo-specific path variables only when the repo already standardizes on them.
 - Label provider-specific mechanics explicitly and add portability notes when they matter.
 
+## Scope-Aware Encapsulation
+
+A skill must speak to the level of its authorship. Registration scope determines what content is in-scope.
+
+| Registration | Scope | Body may reference |
+|--------------|-------|---------------------|
+| Global (`~/.claude/skills/`, `~/.claude/agents/`) | cross-project | generic patterns, public APIs, neutral placeholder names |
+| Project (`<project>/.claude/skills/`, `<project>/.claude/agents/`) | one codebase | project files, hooks, domain terms, internal helpers |
+
+A global skill that bakes in identifiers from one project ships them to every consumer of the skill, where the references resolve to nothing.
+
+- Resolve registration scope before authoring; ask the user once if ambiguous.
+- For global skills, abstract project-grounded patterns to placeholder names (`FollowToggle`, `useResourceActions`) before writing them into the body.
+- Source synthesis may consult a project's files for the canonical pattern; the resulting body must not.
+- Project skills may anchor freely on real codebase symbols; that's the value.
+
 ## Long Files
 
 - Keep `SKILL.md` short enough to scan as a router.

skills/skill-writer/references/mode-selection.md

@@ -65,3 +65,4 @@ Missing selected-profile requirements is also a hard failure.
 Missing required class dimensions is a hard failure.
 Missing an explicit execution-shape choice for a material skill change is a hard failure.
 Using advanced mechanics without justification or portability notes is a hard failure.
+Scope mismatch is a hard failure: a global-registered skill that hard-codes project-specific identifiers, file paths, hook names, or domain nouns must be fixed before completion. Project-registered skills are not constrained. See `references/design-principles.md` "Scope-Aware Encapsulation."