Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
the-simian wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions skills/skill-writer/SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
16 changes: 16 additions & 0 deletions skills/skill-writer/references/design-principles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 (`<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 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.
Expand Down
1 change: 1 addition & 0 deletions skills/skill-writer/references/mode-selection.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.