Nested skills support

[tunnckoCore]

RFC

Summary

While reviewing the AbortController commit dec82b4 i just realized Flue doesn't support nested skills.

The Agent Skill spec doesn't necessarily force a flat directory of skills, and that's useful for grouping. I researched that a month or so ago, and added it in one of the Claude Code leaked source big forks - OpenClaude.

Pi itself also supports nested skills loading.

I've seen Discussion #83 but it's not related, and i'm in support of it too.

Background & Motivation

The idea is that there is a need for certain groups. And they should be recursively resolved. There are repos like jwynia/agent-skills which has great amount of awesome writer skills I use extensively. I regularly review and look around skills repos and there are a lot of other examples for that too, most recent was mattpocock/skills.

The spec doesn't force flat structure probably for these reasons.

Goals

A concise, bulleted-list outlining the intended goals of this RFC.

• nested skills support for easier grouping of skills
• namespaced and prefixed names in views for easier UX
• ignoring dir names like references, scripts, skills
• ignoring nested _-prefixed dir names.

Example

In my OpenClaude implementation specifically, i just globbed with **/SKILL.md, but in reality we should ignore specifically **/references/**, **/scripts/** and such names. The rule of that the name inside the SKILL.md frontmatter must match the parent dir name remains, but listing of skills (in UIs or APIs) should be namespaced and separated with _ for easier UX, like creative_fiction_application_shared-world is effectively skills/creative/fiction/application/shared-world/SKILL.md with name: shared-world.

[FredKSchott]

This makes sense! if the spec allows it, and there's precedent in another major coding harness, then I agree we should too. I'd just want us to match whatever behavior that other coding harness(es) used for detection. **/SKILL.md makes sense would just want to confirm before accepting a PR.

Would love a PR for this!

[stainlu]

opened #109 for this.

kept the behavior conservative:

• discover recursive SKILL.md files under .agents/skills/
• carry the exact discovered path into the skill registry + prompts, so nested skills do not depend on the old .agents/skills/<name>/SKILL.md convention
• stop descending once a directory is a skill root, so references/, scripts/, etc. inside a skill package do not get accidentally registered
• fail loudly on duplicate frontmatter name: values instead of inventing a second namespacing scheme in this PR

that felt closest to the existing Flue model: frontmatter name is still the public skill name, path is the disambiguation / escape hatch.

[tunnckoCore]

that felt closest to the existing Flue model: frontmatter name is still the public skill name, path is the disambiguation / escape hatch.

yeah, exactly. that was my idea maybe not worded well. The skill name remains the thing, the underscoring is only for "UI" like listing them. Chose _ because pi lists them when /skil:skill-name and it was going to be weird if it's /skill:creative:fiction:application:shared-world

Thanks for the PR.

[astrobot-houston]

Possibly related contribution from @stainlu — opened #109 which appears to be addressing this.

Their summary: Adds recursive traversal of .agents/skills/ to discover nested SKILL.md files, tracks each skill's file path in the registry for use in prompts, and fails fast on duplicate skill names. Also updates documentation to describe grouped/nested skill packs.

Implementation: stainlu/flue@stainlu/nested-skills (diff)

This comment was posted automatically when #109 was redirected. The implementation is preserved on the branch above so it can inform the work here.