docs(writing-skills): add allowed-tools sync invariant to frontmatter docs and checklist#1533
Open
daniel769 wants to merge 1 commit into
Open
docs(writing-skills): add allowed-tools sync invariant to frontmatter docs and checklist#1533daniel769 wants to merge 1 commit into
daniel769 wants to merge 1 commit into
Conversation
Referencing Skill(X) in a skill body without listing it in allowed-tools causes a silent runtime failure — the agent can't invoke the skill and no error is thrown. Add a frontmatter entry and a GREEN-phase checklist item so authors know to verify the match before committing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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.
What problem are you trying to solve?
When a skill references another skill via
Skill(X)in its body but that skill is absent from theallowed-tools:frontmatter field, the agent silently fails to invoke it — no error is thrown, no hook catches it, the call just doesn't happen. This was caught in production at Honeydew by a cursor bugbot on a PR review; nothing in local tooling surfaced it first. Thewriting-skillsskill has no mention of this invariant, so skill authors have no reason to know it exists.What does this PR change?
Adds two things to
writing-skills/SKILL.md:allowed-toolsbullet under the Frontmatter section (matching the style of the existingname/descriptionentries) explaining the invariant and providing a one-liner to verify it.Is this change appropriate for the core library?
Yes. Any skill that calls other skills is affected, regardless of domain or project. The failure mode is universal and invisible, which makes it a good fit for the shared checklist.
What alternatives did you consider?
Adding it only to the checklist (without the frontmatter prose) — but the checklist is scanned quickly and the prose section is where authors learn the semantics of each field, so both felt necessary.
Does this PR contain multiple unrelated changes?
No. Two lines in one file, both documenting the same invariant.
Existing PRs
PRs #1001, #927, and #196 all attempted to enumerate all supported frontmatter fields comprehensively. This PR does not enumerate fields — it documents a specific silent failure mode that those PRs did not address (body/frontmatter mismatch causing
Skill()calls to silently fail).Environment tested
Evaluation
Skill(X)reference in a skill body had been removed fromallowed-tools, breaking the call silently.Rigor
superpowers:writing-skillsand completed adversarial pressure testing (paste results below)This is a documentation addition (two new lines) that does not touch any behavior-shaping content.
Human review