[FEATURE] Explicitly hierarchical skills/skill tree loading #13032
Description
Preflight Checklist
- I have searched existing requests and this feature hasn't been requested yet
- This is a single feature request (not multiple features)
Problem Statement
I am one of many experimenting with turning large datasets into Skills for claude code. As an example, converting the apple docs MCP into skills with skill seeker produces a massive dump of 15 skills:
WWDC (15)
| Skill | Sessions | Path |
|-------------------------|----------|-----------------------------------------|
| wwdc-swiftui | 120 | output/wwdc-swiftui/SKILL.md |
| wwdc-developer-tools | 199 | output/wwdc-developer-tools/SKILL.md |
| wwdc-app-services | 172 | output/wwdc-app-services/SKILL.md |
| wwdc-essentials | 161 | output/wwdc-essentials/SKILL.md |
| wwdc-design | 142 | output/wwdc-design/SKILL.md |
| wwdc-audio-video | 124 | output/wwdc-audio-video/SKILL.md |
| wwdc-system-services | 79 | output/wwdc-system-services/SKILL.md |
| wwdc-app-store | 75 | output/wwdc-app-store/SKILL.md |
| wwdc-machine-learning | 60 | output/wwdc-machine-learning/SKILL.md |
| wwdc-accessibility | 56 | output/wwdc-accessibility/SKILL.md |
| wwdc-swift | 53 | output/wwdc-swift/SKILL.md |
| wwdc-business-education | 51 | output/wwdc-business-education/SKILL.md |
| wwdc-privacy-security | 45 | output/wwdc-privacy-security/SKILL.md |
| wwdc-photos-camera | 30 | output/wwdc-photos-camera/SKILL.md |
| wwdc-maps-location | 11 | output/wwdc-maps-location/SKILL.md |
This results in comically generic skills, e.g.: "WWDC SwiftUI - Declarative UI framework covering views, data flow, navigation, animations, and state management. Based on 120 WWDC sessions covering SwiftUI fundamentals, view composition, property wrappers, navigation patterns, and modern UI development."
(Yes, I know that description is terrible, I haven't optimized it because I realized I wasn't going to be able to use these skills for the same reason I'm creating this issue)
It's not for SwiftUI views or animations, just a uselessly broad mishmash of it all.
It's not going to be reasonable either to break it up into more skills, because those will just clutter the context window.
Proposed Solution
It seems to me like the most straightforward option would be to allow hierarchical loading of skills as a tree. We'd define a top-level SKILL.md exactly as before, but it would just be a shim to a bunch of subskills, expanding their YAML frontmatter progressively.
The initial state might look like:
<skill>
<name>wwdc-swiftui</name>
<description>
Declarative UI framework covering views, data flow, navigation, animations, and state management. Based on 120 WWDC sessions covering SwiftUI fundamentals, view composition, property wrappers, navigation patterns, and modern UI development
</description>
<location>project</location>
</skill>
But after using Skill(wwdc-swiftui), it would then replace itself with something like:
<skill>
<name>swiftui-views</name>
<description>
MANDATORY for creating or updating SwiftUI views, NOT for use with: UIKit
</description>
<location>project</location>
</skill>
<skill>
<name>swiftui-dataflow</name>
<description>
MANDATORY for creating or updating or working with SwiftUI dataflows
</description>
<location>project</location>
</skill>
<skill>
<name>swiftui-navigation</name>
<description>
MANDATORY for creating or updating or working with SwiftUI navigation, navigation components, or navigation paradigms; NOT for use with simple buttons, or single components
</description>
<location>project</location>
</skill>
<skill>
<name>swiftui-animations</name>
<description>
MANDATORY for creating or updating or working with SwiftUI animations or animation paradigms; NOT for use with static components or static UIs
</description>
<location>project</location>
</skill>
<skill>
<name>swiftui-state-management</name>
<description>
MANDATORY for creating or updating or working with SwiftUI state management or state management paradigms; NOT for use with static components, static UIs, or UIKit
</description>
<location>project</location>
</skill>
etc...
Then, only when running the Skill tool a SECOND time, e.g. with Skill(swiftui-state-management)/tool_use, would the actual contents expand into the system prompt.
This seems to me like the perfect metaprogression of progressive disclosure.
I'm not in a position to implement it myself unless Anthropic hires me, not that I think I could pass the interview! I'm just using Skills intensively in development and have already bumped up against their limits!
Alternative Solutions
- Obvious, terrible, option: Just try to include a few dozen skills, watch them not even show up in the context window because their YAML frontmatter eats the entire budget that claude code gives them in the system prompt.
- Less obvious, but still pretty obvious, and also fragile option: leverage the normal recommended pattern of hierarchical references in a Skill folder. Problem: It still gets very difficult to cram the right information into the recommended skill file size without it taking too much context, or on the other hand not including enough.
- Agentic search: I've been trying to make purely agentic search with a DIY knowledgebase work for like 6 months now. It definitely works a bit, but not remotely reliable. Not as good as skills already are.
Priority
High - Significant impact on productivity
Feature Category
Developer tools/SDK
Use Case Example
Really, any large documentation that is part of a massive and broad dataset.
Honestly, It just seems to me like this would be the obvious next step now that skills exist!
Additional Context
No response