feat(skills): support nested directories and lightweight injection

[Weaxs]

Closes #183
Closes #262

Why

Two gaps surface when subagents and the host pi-coding-agent share the same skill directory.

1. Nested skill discovery mismatch

pi-coding-agent's loadSkillsFromDirInternal recursively walks subdirectories looking for SKILL.md, treating any directory that contains one as a skill root. This lets users group skills hierarchically:

skills/
  shell/
    safe-bash/SKILL.md
    tmux/SKILL.md
  web/
    chrome-devtools/SKILL.md

pi-subagents's collectFilesystemSkills only descends one level — it finds <root>/<name>/SKILL.md but not <root>/<group>/<name>/SKILL.md. The result is that a subagent's frontmatter skills: safe-bash resolves in the host but fails in the subagent runtime, even when both agents are pointed at the same skills tree.

2. Heavyweight injection is the only option

When an agent declares skills: a, b, c in frontmatter, buildSkillInjection always wraps each skill's full SKILL.md body into the system prompt. For agents that bundle many skills, this can add 100KB+ to every cold start, even though most invocations only touch one or two skills.

pi-coding-agent's formatSkillsForPrompt solves the same problem on the host side by emitting a compact <available_skills> listing of name + description + path, and pointing the model at the read tool. Subagents have no equivalent escape hatch — they either inject everything or know nothing about declared skills.

What changes

1. Recursive skill discovery (matches pi-coding-agent)

collectFilesystemSkills now recurses into subdirectories of each registered skill root, stopping at any directory that contains a SKILL.md (treating it as the skill anchor for that subtree). Hidden directories and node_modules are skipped to mirror the host scanner.

Layouts that previously resolved are unchanged:

• <root>/SKILL.md (single skill at the root)
• <root>/<name>.md and <root>/<name>/SKILL.md

New layouts now resolved:

• <root>/<group>/<name>/SKILL.md
• arbitrary depth as long as no ancestor has its own SKILL.md

2. Optional lightweight skill injection

A new agent frontmatter field skillInjection: full | light (default full, fully backwards-compatible) controls how buildSkillInjection shapes the system prompt.

Given an agent with skills: safe-bash, tmux, here is the actual text appended to the subagent's system prompt in each mode.

full (default, current behavior) — the entire SKILL.md body is inlined per skill:

<skill name="safe-bash">
# safe-bash

Use this skill when the task requires running shell commands.

## Guidelines
- ...
- ...
</skill>

<skill name="tmux">
# tmux

When the task involves long-running processes, use tmux sessions.

## Commands
- `tmux new-session -d -s <name>`
- ...
</skill>

light — only name, description, and absolute path are emitted, plus instructions to load each file on demand via the read tool:

The following skills are available for this agent. Use the read tool to load a skill's file when the task matches its description.

<available_skills>
  <skill>
    <name>safe-bash</name>
    <description>Run shell commands safely with audit trail.</description>
    <location>/abs/path/to/skills/safe-bash/SKILL.md</location>
  </skill>
  <skill>
    <name>tmux</name>
    <description>Manage tmux sessions for long-running tasks.</description>
    <location>/abs/path/to/skills/tmux/SKILL.md</location>
  </skill>
</available_skills>

The light shape mirrors pi-coding-agent's formatSkillsForPrompt output, so a model that knows how to use the host's <available_skills> listing already knows how to use this one.

Note on naming: #183 sketches the same direction with skillInjection: lazy | inline. This PR uses full | light to make the contrast read more naturally as a heaviness scale (full SKILL.md vs light listing) and to keep the default explicitly the existing behavior. Happy to rename to match the issue if maintainers prefer.

The new buildLightSkillInjection helper is exported alongside the existing buildSkillInjection. The field is plumbed through BuiltinAgentOverrideBase, BuiltinAgentOverrideConfig, AgentConfig, KNOWN_FIELDS, the agent serializer, agent management input parsing, and the subagent extension tool description.

Example agent file

A user/project agent declaring many skills but opting into the lightweight listing — only the four "core" skills are injected in full; the rest stay as references the agent loads on demand:

---
name: shell-ops
description: Long-running shell and tmux operations specialist
tools: read, grep, find, ls, bash
systemPromptMode: replace
inheritProjectContext: true
inheritSkills: false
skillInjection: light
skills: safe-bash, tmux, chrome-devtools
---

You are a shell operations specialist.

Use the read tool to load any skill listed in your `<available_skills>` block when the task matches its description. Pull only what you need.

Without skillInjection: light, the same skills: declaration would inline three full SKILL.md bodies into the system prompt at every cold start. With light, only the listing block (name + description + location) is appended, and the agent loads each SKILL.md via the read tool when actually needed.

Tests

test/unit/skills-extensions.test.ts adds 9 cases covering:

• Two-level nested discovery (<root>/<group>/<name>/SKILL.md)
• Recursion stops at the first SKILL.md (no nested SKILL.md leakage)
• node_modules and dotfile directories are excluded
• Deeply-nested skills resolve via resolveSkills
• buildLightSkillInjection emits name/description/location, never the full body
• Missing description gracefully omitted in light mode
• Empty skill list returns empty string
• XML-special characters escaped in name/description/location
• buildSkillInjection (default) still emits full body — regression guard

Full test suite: 512 / 512 pass (npm run test:unit).

Backwards compatibility

• Existing layouts (<root>/<name>/SKILL.md etc.) keep working unchanged.
• skillInjection defaults to full, so agents without the field behave exactly as before.
• Serializer only writes skillInjection when value is non-default (light), keeping existing agent files byte-identical on round-trip.

[nicobailon]

Thanks for the PR. I would not merge this as-is, but I think it can get there with a smaller revision.

The scanner still walks inside a configured skill path after adding that directory's own SKILL.md. That means a settings or package skill path that points directly at a skill root can leak nested helper skills, which conflicts with the “stop at the first SKILL.md” rule this is trying to match.

For skillInjection: light, please also handle agents with an explicit tool allowlist that omits read. Right now the prompt tells the child to load the skill file, but a tools: bash style agent would not have the tool needed to do that. A validation error, warning, or automatic read inclusion would make that behavior clear.

Please add focused coverage for those cases, and update the user docs for the new frontmatter/override field.

[nicobailon]

One more small thing for when you revise this: please add an Unreleased changelog entry for the user-visible skill discovery/light injection change, with credit to Weaxs (@Weaxs).

[nicobailon]

I'm closing this for now while we clean up the PR queue. The nested-skill work still looks worth revisiting, but this branch needs a current-main revision before it can merge. Please feel free to open a fresh revised PR later if you want to pick it back up.