Add namespaced skill discovery - #67
Conversation
Allow `skills/` to organize skills beneath validated namespace directories while treating the first `SKILL.md` on each branch as a terminal discovery boundary. Distinguish skills by relative path, isolate client-specific mapping collisions, and exclude directory links so recursive discovery remains deterministic without a depth limit. Keep `1.0.0` discovery selected by its manifest schema.
|
This all makes sense 👍 Some notes from my agent on how this will affect OpenClaw/ClawHub:
The first two I'm sharing just for context on our current implementation and the changes we'll need to make to adhere. The third one I think could be an improvement to the spec, maybe a max depth of 4? |
Permit clients to stop namespaced skill discovery when an implementation-appropriate resource limit is exceeded and recommend reporting incomplete discovery. Record why the specification avoids fixed depth and breadth limits that constrain one tree shape without bounding traversal work.
|
@Patrick-Erichsen Thank you for taking a look! ❤️
Would a naming scheme like
I've added a commit saying "Clients MAY stop skill discovery when a client-defined resource limit is exceeded, such as a limit on directory entries inspected." That covers both depth and breadth of potentially-malicious directory trees. I would prefer to avoid explicitly specified limits because limits might be client specific, and can easily become outdated as technology progresses or as new threats emerge. Please let me know what you think! |
I think we could still run into a scenario where multiple plugins both contain a
Makes sense to me! Agreed that better to preserve flexibility rather than preempt security concerns here. |
|
For user-invocable skills, I'd prefer a format that puts the outcome (deploy) first and the qualifier (aws) second, For naming conflicts, I'm not sure how relevant Claude Code is to this discussion but I noticed they fully qualify skills like this: e.g.: |
Motivation
Agent Plugins 1.0 discovers skills only as immediate children of
skills/. This forces every plugin into a flat skill layout, even when skills come from different sources or belong to distinct namespaces.Proposal
This PR allows skills beneath namespace directories in plugins that target Agent Plugins 1.1.0.
Here,
aws/deployandgcp/deployare distinct skills even though both declarename: deploy. Discovery stops atskill-creator/SKILL.md, so the example beneathtemplates/is not discovered as another skill.Clients are free to choose how skill paths map to client-facing identifiers or invocation syntax. Because namespace directories follow the Agent Skills naming grammar, clients with flat identifier schemes can join the path segments. However, joining path segments can produce collisions, so clients must not silently merge distinct skills.
Plugins targeting Agent Plugins 1.0.0 retain the existing immediate-child discovery behavior.
Rationale
Treating the first
SKILL.mdon each branch as a terminal boundary prevents files bundled within an existing skill from being reinterpreted as nested skills.Discovery does not follow directory links, keeping traversal finite and avoiding cycles or multiple namespace paths to the same directory.