feat(skill-writer): Add scope-aware encapsulation depth gate#139
Open
the-simian wants to merge 1 commit into
Open
feat(skill-writer): Add scope-aware encapsulation depth gate#139the-simian wants to merge 1 commit into
the-simian wants to merge 1 commit into
Conversation
5cbe1fc to
7c58ddb
Compare
7c58ddb to
d0f61dc
Compare
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) <noreply@anthropic.com>
d0f61dc to
74b1a91
Compare
Author
|
Force-pushed a few times to fold self-review fixes into the original commit (current HEAD |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add a Scope-Aware Encapsulation principle to
skill-writer/references/design-principles.md, a matching hard-stop rule inmode-selection.md, and a sister-update toskill-writer/SPEC.md, so authored skills stay matched to the level at which they are registered.Why.
skill-writer's synthesis path explicitly permits local project files as grounding evidence. For a project-scoped skill, surfacing those files' identifiers in the authored body is correct; for a globally registered skill, it is not. The rule is implicit in good practice but is not currently codified anywhereskill-writerconsults:Independence And Portabilitycovers provider portability (paths, runtime deps), andmode-selection.md's portability note in synthesis outputs covers provider-specific mechanics, not registration-scope encapsulation of body content. An authoring agent following the documented synthesis-then-author flow can therefore land a global skill whose worked examples reference symbols that exist in only one project, producing references that resolve to nothing for every other consumer of the skill. This PR adds the principle, the matching hard-stop, and the contract bullet.Scope of the principle. The rule targets body content vs. registration scope: a skill's worked examples and inline references must not exceed the scope at which it is registered. Source synthesis may consult a project's files to learn the canonical pattern; the resulting body must abstract that pattern with structural placeholder names. Project-scoped skills are explicitly carved out and may anchor freely on real codebase symbols.
What changed.
skills/skill-writer/references/design-principles.md: add aScope-Aware Encapsulationsection afterIndependence And Portabilitywith a registration/scope/body-may-reference table, an explicit one-sentence distinction from the prior section, and four bullets covering the resolution rule, the abstraction rule for globals, the consult-but-don't-bake rule for synthesis, and the carve-out for project skills.skills/skill-writer/references/mode-selection.md: add one line toHard stop rulesflagging hard-coded project-specific identifiers in a globally registered skill as a hard failure. Cross-references the new section.skills/skill-writer/SPEC.md: add one bullet toNon-negotiable constraintsmirroring the new principle, so the skill's maintenance contract reflects the new gate.