Skills

Flue supports Agent Skills: reusable instructions and supporting resources that agents can load for specialized, repeatable work, such as applying a review process, following an operational workflow, or using shared project guidance. Skills can be bundled with your application or supplied by the runtime workspace where an agent operates.

Skills guide agent work; they do not add executable capabilities. Use tools or sandboxes when an agent needs actions or workspace access.

Add a skill

Flue lets you keep an Agent Skill alongside the agents and workflows that use it. When you import that skill, Flue packages its instructions and supporting files with your application so an initialized harness can use it without depending on files in its runtime workspace.

Add an existing Agent Skill directory anywhere within your project root. This guide uses src/skills/ to keep application-owned skills next to authored source:

src/
├─ agents/
│  └─ assistant.ts
├─ skills/
│  └─ review/
│     ├─ SKILL.md
│     └─ references/
│        └─ checklist.md
└─ workflows/
   └─ review-change.ts

The example stores the skill in src/skills/ alongside other authored source, but its location does not make it available on its own. Import its SKILL.md to include it in the application and make it available to an agent. See Project Layout for how Flue organizes authored source.

Import a skill

Import your skills with the skill import attribute (a new feature in modern JavaScript). Once imported, pass the imported reference to the agent’s skills configuration:

import { createAgent } from '@flue/runtime';
import review from '../skills/review/SKILL.md' with { type: 'skill' };
import triage from '../skills/triage/SKILL.md' with { type: 'skill' };
import investigate from '../skills/investigate/SKILL.md' with { type: 'skill' };

export default createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  skills: [review, triage, investigate],
}));

Each import produces a skill reference and includes that skill directory in the application build. Passing those references in skills makes the skills available to this agent by their declared names.

Imported skill directories are deployed application content: ordinary supporting files beside SKILL.md are included without additional imports. Do not store credentials, private keys, or runtime secrets in a skill directory that your application imports. Flue rejects common sensitive files and unsafe symbolic-link boundaries when packaging imported skills.

Flue also loads skills from the sandbox where a harness runs, with no import required. At context initialization, it discovers Agent Skills-compatible directories under <cwd>/.agents/skills/:

<cwd>/
└─ .agents/
   └─ skills/
      └─ review/
         ├─ SKILL.md
         └─ references/
            └─ checklist.md

Each discovered skill is available by its declared name without a TypeScript import or an entry in skills, and its supporting files remain in that sandbox workspace. This lets a repository checkout, CI environment, or prepared runtime workspace provide its own skills to a harness. See Sandboxes for controlling the filesystem and working directory visible at runtime.

If an imported skill registered on an agent and a discovered workspace skill declare the same name, initialization fails rather than choosing one implicitly.

Invoke a skill

Normally you can trust the agent to use the skills you provide it, as needed, to complete its work.

In workflows, you can manually trigger a skill through the session.skill(name: string) API method. This works with both registered imported skills and workspace-discovered skills.

import { createAgent, type FlueContext } from '@flue/runtime';
import * as v from 'valibot';
import review from '../skills/review/SKILL.md' with { type: 'skill' };

const agent = createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  skills: [review],
}));

export async function run({ init, payload }: FlueContext<{ change: string }>) {
  const harness = await init(agent);
  const session = await harness.session();

  const response = await session.skill('review', {
    args: { change: payload.change },
    result: v.object({
      approved: v.boolean(),
      summary: v.string(),
    }),
  });

  return response.data;
}

args provides input for this invocation of the skill. The result schema makes response.data a validated structured result; omit it when you want text output from response.text. The string passed to session.skill(...) is the declared skill name, not a path to SKILL.md.

See the Agent API for operation options and response types.

Next steps

• Agent Skills specification — create and structure compatible skills.
• Agents — configure an agent’s model and capabilities.
• Tools — add executable capabilities that a skill may direct an agent to use.
• Sandboxes — control the runtime workspace where discovered skills and their files are available.
• Agent API — look up session operation options and result types.