Configurable skills directory (skillsPath)

[FredKSchott]

Originally proposed in #73 by @jimdrury — opening this discussion to gather use cases before reviewing a PR.

Summary

Make the skills discovery directory configurable, so the skills an agent uses while being authored can be separated from the skills an agent executes at runtime.

Background & Motivation

Today, skills are discovered from a hardcoded .agents/skills/ directory. This means there's no way to distinguish skills the author/dev loop uses from skills the deployed agent itself loads at runtime — they all live in the same place.

The original PR description gestures at this with: "If you're building an agent that runs skills, those skills currently have to live alongside the skills you use to build it."

What we'd really like to understand before moving forward is the concrete user story behind this:

• What are you actually building? Walk us through the agent — what does it do, and which skills are author-time vs runtime?
• What goes wrong today? Naming collisions? Wrong skills surfacing in the authoring loop? Deployment/packaging concerns? Something else?
• Why is "configurable directory" the right shape vs. naming conventions, subdirectories, a manifest, or modeling "runtime skills" as a first-class concept?

@jimdrury — would love your scenario in your own words. Anyone else who's hit this, please chime in too.

Goals

• Allow agents that themselves load skills at runtime to keep those skills isolated from the author/dev-time skill set.
• Avoid forcing a single shared skill namespace on workspaces that have meaningfully different author-time vs runtime skill needs.
• Do this without breaking existing workspaces (default behaviour should remain .agents/skills/).

Example

The proposed API in #73:

const agent = await ctx.init({
  model: 'anthropic/claude-sonnet-4-6',
  skillsPath: './runtime-skills',
});

• New skillsPath on AgentInit (and TaskOptions) that replaces the default .agents/skills/ lookup
• Type-safe paths (relative ./ or absolute /)
• Validated at init (throws if directory doesn't exist)
• Child tasks inherit the parent's skillsPath, with per-task override
• No breaking changes — defaults are unchanged

See #73 for the full diff. Open design questions if we move forward: workspace-level config vs per-init, and how this interacts with the build/deploy story where the workspace is compiled into a deployable artifact.

[ketankhairnar]

Two concrete scenarios where the current single-directory model bites:

1. Meta-agents (agent-runs-agents). An agent whose job is to author or operate other agents. Its author-time skills are things like "scaffold a new agent," "add a role," "run the dev loop." Its runtime skills, the ones the agents it spawns will load, are a totally different set, often domain-specific (e.g. "summarize a transcript," "extract entities"). Today both sets live in .agents/skills/, so the parent agent sees its children's skills as candidates in its own authoring loop. That's noise at best and wrong-skill-fires at worst.

2. Monorepo with shared author-time skills, divergent runtime skills. A workspace ships multiple deployable agents (one per target/binding). They share the same author-time skill set (lint, scaffold, test) but each has its own runtime skill set that should be packaged only with that target. A single .agents/skills/ forces either (a) packaging every agent's runtime skills into every artifact, or (b) hoisting per-agent skills out of the workspace-level directory and losing the dev loop's awareness of them.

What goes wrong today, concretely:

• Naming collisions. A summarize skill the parent uses for changelogs collides with a summarize skill a child agent ships.
• Packaging bloat. Every deployable artifact carries every workspace skill, even unused ones.
• Wrong-skill surfacing. Runtime-only skills show up as suggestions during the author/dev loop because the discovery path can't distinguish them.

On shape: I'd lean toward making this a workspace-level setting (a key in flue.config.ts from #52) rather than a per-init() option. The question "which directory does this workspace's skills live in" is a property of the workspace, not of any particular call site. Putting it in the config file avoids precedence ambiguity between CLI flags, parent tasks, and init() overrides. If a per-call override is ever needed, it can be added later as an escape hatch on top of the config-file default.

Worth asking whether skillsPath in the config should accept an array (for monorepos with shared author-time + per-target runtime directories), but that's a follow-up. The single-path version is a strict superset of today's behavior and unblocks both scenarios above.

[jimdrury]

As @ketankhairnar has noted, meta agents and mono-repos.

In general my thinking is that if we're giving the agents the ability to run skills, I probably want them to have access to a different set of skills to the ones I'm building the codebase using.

My use-case specifically is that I'm building a webhook based agent which will assess a specific jira ticket and it's associated attachments, validate them across a number of roles "What would a solution designer consider?", "What would an enterprise architect consider?" ... each of those roles has a selection of skills available - the agent (via role) should be selecting which skills to invoke as needed.

It could be that I'm overly anthropomorphising, and for the sake of token windows I'm executing them as their own tasks to avoid Agent A's output from influencing Agent B

High level flow

flowchart TD
    A(["Jira Workflow Triggers Webhook"])
    B["Documents extracted and converted to MD"]
    C["(prompt) Orchestrator identifies roles required for review"]
    D1["(task) Role A\nwith relevant skills"]
    D2["(task) Role B\nwith relevant skills"]
    D3["(task) Role C\nwith relevant skills"]
    E["Orchestrator captures output from all tasks"]
    F["(prompt) Review Document created"]
    G["Document converted to PDF"]
    H(["PDF attached to Jira — Workflow progressed"])

    A --> B
    B --> C
    C --> D1 & D2 & D3
    D1 & D2 & D3 --> E
    E --> F
    F --> G
    G --> H

    style A fill:#f97316,color:#fff,stroke:none
    style H fill:#f97316,color:#fff,stroke:none

    style B fill:#0ea5e9,color:#fff,stroke:none
    style G fill:#0ea5e9,color:#fff,stroke:none

    style C fill:#8b5cf6,color:#fff,stroke:none
    style E fill:#8b5cf6,color:#fff,stroke:none
    style F fill:#8b5cf6,color:#fff,stroke:none

    style D1 fill:#10b981,color:#fff,stroke:none
    style D2 fill:#10b981,color:#fff,stroke:none
    style D3 fill:#10b981,color:#fff,stroke:none

Loading