Skip to content

docs(writing-skills): add allowed-tools sync invariant to frontmatter docs and checklist#1533

Open
daniel769 wants to merge 1 commit into
obra:mainfrom
daniel769:fix/allowed-tools-sync-checklist
Open

docs(writing-skills): add allowed-tools sync invariant to frontmatter docs and checklist#1533
daniel769 wants to merge 1 commit into
obra:mainfrom
daniel769:fix/allowed-tools-sync-checklist

Conversation

@daniel769
Copy link
Copy Markdown

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 the allowed-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. The writing-skills skill 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:

  1. A allowed-tools bullet under the Frontmatter section (matching the style of the existing name/description entries) explaining the invariant and providing a one-liner to verify it.
  2. A corresponding GREEN-phase checklist item so authors are prompted to check it during skill creation.

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

Harness Harness version Model Model version/ID
Claude Code latest Claude Sonnet claude-sonnet-4-6

Evaluation

  • Session that led to this: a Honeydew PR where cursor bugbot flagged that a Skill(X) reference in a skill body had been removed from allowed-tools, breaking the call silently.
  • After the change: the checklist item surfaces during normal skill authoring; the prose entry is visible when reading the frontmatter section.
  • No behavioral change to any agent workflow — this is additive documentation only.

Rigor

  • If this is a skills change: I used superpowers:writing-skills and completed adversarial pressure testing (paste results below)
  • This change was tested adversarially, not just on the happy path
  • I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language) without extensive evals showing the change is an improvement

This is a documentation addition (two new lines) that does not touch any behavior-shaping content.

Human review

  • A human has reviewed the COMPLETE proposed diff before submission

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant