fix(v4.0.3): hide nested sub-skills from / menu via user-invocable: false#1084
Open
keegoid wants to merge 1 commit intodanielmiessler:mainfrom
Open
fix(v4.0.3): hide nested sub-skills from / menu via user-invocable: false#1084keegoid wants to merge 1 commit intodanielmiessler:mainfrom
keegoid wants to merge 1 commit intodanielmiessler:mainfrom
Conversation
…alse Claude Code auto-indexes every SKILL.md in the skills/ tree and advertises each as an invokable slash-command tip. PAI organizes skills hierarchically: top-level SKILL.md files are user-invokable, but 36 nested sub-skills at depth >= 2 are routed to by the parent's Workflow Routing table and are NOT meant to be invoked by the user. Without any marker distinguishing them, Claude Code advertises broken slash commands like /annual-reports, /council, /osint — they appear in the tip system but do nothing meaningful when invoked. 78% false-positive rate on the primary affordance. Fix: set `user-invocable: false` on every nested sub-skill SKILL.md. This is the spec-blessed frontmatter field from the Claude Code Skills documentation (https://code.claude.com/docs/en/skills, "Frontmatter reference" table): user-invocable — Set to `false` to hide from the / menu. Use for background knowledge users shouldn't invoke directly. Default: true. The flag hides the skill from the / menu and tip system. Claude can still route to the sub-skill via the parent's file-path reference (parent's routing table uses Read, not the Skill tool). No structural reorganization or rename required. Changes: - Add `user-invocable: false` to 36 nested sub-skill SKILL.md files across ContentAnalysis, Investigation, Media, Scraping, Security, Thinking, and Utilities parents. - Add section "Sub-Skill Frontmatter (MANDATORY)" to PAI/SKILLSYSTEM.md documenting the rule, rationale, correct frontmatter shape, and validator check. - Update CreateSkill CanonicalizeSkill and ValidateSkill workflows to check for the flag on nested sub-skills as part of structural validation. Scope: all 36 nested sub-skills in Releases/v4.0.3. Older release snapshots (v4.0.0, v4.0.1, v4.0.2) are frozen artifacts and intentionally not touched. Relationship to PR danielmiessler#1082 (vaporware spinner tips): danielmiessler#1082 addresses a separate failure mode — hardcoded spinner tips that reference skill names which never existed as files. This PR addresses tips for sub-skills that DO exist as files but should not be user-invokable. `user-invocable: false` cannot apply to non-existent files, so danielmiessler#1082 remains independently valid. Verification: # Every nested SKILL.md has the flag (must return empty) find Releases/v4.0.3/.claude/skills -mindepth 3 -name SKILL.md \ -exec grep -L '^user-invocable: false$' {} + # No top-level SKILL.md was changed (must return empty) find Releases/v4.0.3/.claude/skills -mindepth 2 -maxdepth 2 \ -name SKILL.md -exec grep -l '^user-invocable' {} + Both return empty post-commit. No renames, no file moves, no routing changes. Parent skills' Workflow Routing tables still reference `<SubSkill>/SKILL.md` paths as before. The fix is purely additive — 36 single-line frontmatter additions plus documentation. Co-Authored-By: Claude Opus 4.7 (1M context) <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
1 participant
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.
Summary
Claude Code auto-indexes every
SKILL.mdin theskills/tree and advertises each as an invokable slash-command tip. PAI organizes skills hierarchically: top-levelSKILL.mdfiles are user-invokable, but 36 nested sub-skills at depth >= 2 are routed to by the parent's Workflow Routing table and are not meant to be invoked by the user directly. Without any marker distinguishing them, Claude Code advertises broken tips like/annual-reports,/council,/osint— they appear in the/menu and tip system, but nothing meaningful happens when a user tries them. ~78% false-positive rate on the primary tip affordance.Fix
Set
user-invocable: falseon every nested sub-skillSKILL.md. This is the spec-blessed frontmatter field from the Claude Code Skills documentation (Frontmatter reference):The flag hides the skill from the
/menu and tip system. Claude can still route to the sub-skill via the parent's file-path reference (parent's routing table usesRead, not the Skill tool invocation). No renames, no file moves, no routing changes.Changes
user-invocable: falseto 36 nested sub-skillSKILL.mdfiles acrossContentAnalysis,Investigation,Media,Scraping,Security,Thinking, andUtilitiesparents.PAI/SKILLSYSTEM.mddocumenting the rule, rationale, correct frontmatter shape, and validator check.CreateSkillCanonicalizeSkillandValidateSkillworkflows to enforce the flag on nested sub-skills as part of structural validation.Diff: 39 files changed, 144 insertions(+), 0 deletions(-). Purely additive — no deletions, no renames.
Scope
All 36 nested sub-skills in
Releases/v4.0.3/. Older release snapshots (v4.0.0,v4.0.1,v4.0.2) are frozen artifacts and intentionally not touched.Relationship to #1082
#1082 (open) removes 16 hardcoded spinner tips that reference skill names which never existed as files (e.g.,
/broadcast,/inbox). This PR addresses a different failure mode: tips for sub-skills that do exist as files but should not be user-invokable.user-invocable: falsecannot apply to non-existent files, so #1082 remains independently valid. The two PRs are complementary.Test plan
find Releases/v4.0.3/.claude/skills -mindepth 3 -name SKILL.md -exec grep -L '^user-invocable: false$' {} +returns empty (every nested SKILL.md has the flag).find Releases/v4.0.3/.claude/skills -mindepth 2 -maxdepth 2 -name SKILL.md -exec grep -l '^user-invocable' {} +returns empty (no top-level skills were changed).<SubSkill>/SKILL.mdpaths as before./annual-reports,/council, etc. for nested sub-skills (requires reviewer to test locally).Why this framing
This is submitted as both a convention fix (SKILLSYSTEM.md) and the full migration (all 36 files) in one PR because the per-file change is a single frontmatter line — splitting the convention and the application into separate PRs would add review overhead without meaningful isolation. If reviewer prefers the convention doc merged first, happy to split.
Generated with Claude Code