From 74b1a9108946260b27b1995e248d4c23c22c42d2 Mon Sep 17 00:00:00 2001 From: the-simian Date: Fri, 1 May 2026 20:03:27 -0500 Subject: [PATCH] feat(skill-writer): Add scope-aware encapsulation depth gate A skill's body should not exceed its registration scope. Globally registered 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: hard-coded project-specific identifiers in a globally registered skill are now a hard failure in the authoring path. - SPEC.md: matching bullet in Non-negotiable constraints reflects the new gate in the skill's maintenance contract. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/skill-writer/SPEC.md | 1 + .../skill-writer/references/design-principles.md | 16 ++++++++++++++++ skills/skill-writer/references/mode-selection.md | 1 + 3 files changed, 18 insertions(+) diff --git a/skills/skill-writer/SPEC.md b/skills/skill-writer/SPEC.md index 62ceaca..7935016 100644 --- a/skills/skill-writer/SPEC.md +++ b/skills/skill-writer/SPEC.md @@ -57,6 +57,7 @@ Out of scope: - Source provenance and decisions live in `SOURCES.md`. - Durable positive/negative examples live in `references/evidence/`. - `SPEC.md` records the maintenance contract for new or materially changed skills. + - Globally registered skills do not bake in project-specific identifiers (file paths, hook names, domain nouns). - Validation runs before completion. - Expected bundled files loaded at runtime: - `references/mode-selection.md` diff --git a/skills/skill-writer/references/design-principles.md b/skills/skill-writer/references/design-principles.md index 709b4dd..2ba0b7c 100644 --- a/skills/skill-writer/references/design-principles.md +++ b/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's body must not exceed its registration scope. Where the skill is registered determines what its content may reference. Distinct from `Independence And Portability`: that section governs provider portability (paths, runtime deps); this one governs body content matching registration scope. + +| Registration | Scope | Body may reference | +|--------------|-------|---------------------| +| Global (`~/.claude/skills/`, `~/.claude/agents/`) | cross-project | generic patterns, public APIs, structural placeholder names | +| Project (`/.claude/skills/`, `/.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 structural placeholder names (`ExampleComponent`, `useDataHook`) before writing them into the body. Do not substitute one domain for another. +- 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. diff --git a/skills/skill-writer/references/mode-selection.md b/skills/skill-writer/references/mode-selection.md index c2eaa8e..17142d9 100644 --- a/skills/skill-writer/references/mode-selection.md +++ b/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. +Hard-coding project-specific identifiers in a globally registered skill is a hard failure; see `references/design-principles.md` Scope-Aware Encapsulation.