User skills auto-loading by agents (follow-up to #29)

[xzxzxc]

Context

Issue #29 was closed with v3.4.0 fixing the installer wipe problem — custom skills now survive reinstalls. However, the second part — agent auto-loading of user skills — was noted as "planned for a future release" and has no tracking issue.

This follow-up tracks that remaining piece.

Problem

Agents have hardcoded skills: lists in frontmatter. A custom skill file placed in ~/.claude/skills/ (e.g. org-bdd-patterns/SKILL.md) is never loaded by any agent unless the agent definition is manually patched.

This means users who need org-specific or project-specific test patterns, coding conventions, or domain knowledge still can't integrate them into the nWave workflow natively.

Current Workaround

I'm using a two-layer approach:

Layer 1: SubagentStart hook (conversation-level injection)

A Claude Code SubagentStart hook (~/.claude/hooks/inject-test-rules.sh) that:

• Fires when nw-acceptance-designer, nw-software-crafter, or nw-functional-software-crafter agents are spawned
• Reads a project-level .claude/test-rules.md file if present
• Injects its content as additionalContext into the sub-agent's conversation via the hook response:

{"hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":"<rules content>"}}

Pros: survives updates, per-project, no file patching.
Cons: injected into conversation context (lower priority than system prompt), may be overridden by agent's built-in instructions.

Layer 2: Restore script (system-prompt inline injection)

A shell script (~/.claude/scripts/nwave-restore-custom-skills.sh) that:

• Reads skill files from a durable directory (~/.claude/nWave/skills/{agent}/)
• Inlines the full skill content directly into agent .md definition files (appended as <!-- BEGIN INLINE: ... --> blocks)
• Must be re-run after every nwave-ai install

Pros: highest-priority injection (part of agent system prompt), guaranteed to be seen.
Cons: fragile, must re-run after updates, patches multiple file copies.

Expected Behavior

Agents should discover and load user-created skills from ~/.claude/skills/ automatically, alongside framework skills. Possible approaches mentioned in #29:

• Wildcard/glob loading (load all SKILL.md files in skills dirs, not just named ones)
• Agent-level extra_skills: config in .nwave/des-config.json or project CLAUDE.md
• A user-skills: frontmatter field or convention-based auto-discovery (e.g. skills matching {agent-name}-* pattern)

Environment

• nwave-ai v3.7.0 (CLI install)
• macOS, Claude Code

[11PJ11]

Apologies @xzxzxc — my previous reply on this thread didn't post fully. Picking it up properly now.

You've identified a real architectural question. Two limitations bite for any naive solution:

1. Prompt-level "go read this file" instructions are dynamic per-dispatch but the agent can ignore them.
2. Hook-based injection (your SubagentStart workaround) is hard-bound but coupled to Claude-Code lifecycle events — it doesn't survive a multi-runtime story (OpenCode, future agent surfaces).

The direction we're working toward is deterministic path-list resolution at dispatch time + evidence-based attestation at PREPARE-end, vendor-neutral and token-economic. Concretely:

• The orchestrator reads only the YAML frontmatter of skill files (~200 tokens for ~30 skills, with caching). Each agent declares categories: [...]; the orchestrator selects matching skills and lists them by path with provenance (framework / user / project).
• The agent reads the listed paths during PREPARE.
• The agent emits a SHA256 digest of all loaded MANDATORY skills via the DES CLI; the orchestrator validates the digest before allowing the dispatch to proceed past PREPARE. A canary skill with a unique marker provides a second-layer probe (agent must echo the marker; otherwise the session refuses to start with a clear error).

Status: in active design. No timeline commitment yet — we want to ship something we won't regret rather than something fast. Tracked in our backlog as "Skill Resolution v2" alongside #38 since they're the same architectural surface.

Until v2 lands, the SubagentStart hook is acceptable for Claude-Code-only setups — just be aware it's not the long-term contract we'll commit to.

If you'd like to help shape the design (especially the category taxonomy or the canary-probe contract), comments here or a draft RFC PR are very welcome.

---

🤖 AI-assisted draft, reviewed and posted by @11PJ11.