Skills

Purpose and Scope

Skills are Flue’s packaging mechanism for reusable agent guidance. A skill is not a tool, an action, or a sandbox capability; it is a named bundle of instructions and supporting resources that an agent can load when it needs specialized, repeatable guidance. The guide frames skills around work such as applying a review process, following an operational workflow, or using shared project guidance. That distinction matters when designing an agent harness: skills influence how the model reasons and what reference material it can consult, while tools and sandboxes provide the executable abilities needed to call APIs, modify files, or inspect a workspace.

Sources: apps/docs/src/content/docs/guide/skills.md

Use this page when you are deciding where reusable expertise belongs in a Flue application. If the agent needs an operation it can invoke, define a tool or action. If it needs filesystem or shell access, configure a sandbox. If it needs a checklist, policy, operating procedure, review rubric, or other prompt-adjacent resource, package that knowledge as an Agent Skill and register it with the agent that should be allowed to use it. This separation keeps the agent’s cognitive context reusable without accidentally granting new execution privileges.

Relevant Source Files

• apps/docs/src/content/docs/guide/skills.md — Defines the reader-facing Skills guide, including the distinction between skills and executable capabilities, application-owned skill layout, TypeScript import syntax, package-import rules, packaging behavior, security constraints, and workspace-discovered skills.

Core Primitives

A Flue skill starts with a SKILL.md file. The guide follows the Agent Skills specification and treats the surrounding directory as the skill bundle, so files next to SKILL.md can provide references, checklists, or other supporting content. The canonical application-owned layout places these bundles under src/skills/ next to authored agents and workflows, but location alone does not register the skill. Registration happens when application code imports the skill entry file and passes the resulting reference into an agent definition.

Sources: apps/docs/src/content/docs/guide/skills.md

The public agent configuration primitive is the skills array on the object returned by defineAgent. Importing SKILL.md with the JavaScript import attribute with { type: 'skill' } produces a skill reference. Passing that reference to skills makes the skill available to that agent by its declared name. This means skill exposure is explicit: a directory can exist in source control without becoming part of an agent, and an imported reference can be scoped to only the agents that should use it.

import { defineAgent } 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 defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  skills: [review, triage, investigate],
}));

Authoring and Import Flow

A typical application-owned skill flow begins by creating a directory for the skill under the project source tree, commonly src/skills/review/. Inside that directory, place SKILL.md and any ordinary supporting files the skill needs. The guide’s example uses a references/checklist.md file to show that skills can carry more than one document. This is useful for keeping a compact skill entry point while still giving the agent access to detailed procedures, reference material, or task-specific background.

Sources: apps/docs/src/content/docs/guide/skills.md

After authoring the directory, import only the SKILL.md entry point from the agent or shared module that registers the skill. Flue packages the skill instructions and supporting files with the application build, so an initialized harness can use the application-owned skill without relying on those source files being present in the runtime workspace. The import attribute is part of the contract: with { type: 'skill' } tells the build that this Markdown file is an Agent Skill asset rather than ordinary text.

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

Skills may also come from installed packages. In that case, the package must publish the target SKILL.md file and its supporting files. If the package uses package exports, it must export the imported SKILL.md subpath so the consuming application can resolve it. This makes shareable skill libraries possible while preserving the same explicit registration model used for local skills: importing from a package still produces a skill reference, and the agent still opts in through its skills configuration.

Packaging, Safety, and Runtime Discovery

Imported skill directories become deployed application content. The guide calls out an important security boundary: do not store credentials, private keys, or runtime secrets inside a skill directory that the application imports. Ordinary supporting files beside SKILL.md are included without additional imports, and Flue rejects common sensitive files and symbolic links inside imported skill directories during packaging. Treat a skill directory like content that may be bundled and shipped with the harness rather than like a private local working folder.

Sources: apps/docs/src/content/docs/guide/skills.md

Flue also supports workspace-provided skills. When a harness initializes context, it discovers Agent Skills-compatible directories under <cwd>/.agents/skills/. These skills do not require a TypeScript import and do not need to appear in the agent’s skills array. Their supporting files remain in the sandbox workspace, which lets a repository checkout, CI environment, or prepared runtime environment provide its own task guidance. This is especially useful when the skill belongs to the workspace being operated on rather than to the application bundle.

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

The practical distinction is ownership. Application-owned skills are bundled by importing SKILL.md and registering the reference in an agent definition. Workspace-provided skills are discovered from the sandbox working directory at runtime and are available by declared name without application source changes. Use application-owned skills for stable behavior your harness controls, such as a product review process. Use workspace skills for repository-local or environment-local practices that should travel with the workspace the agent is currently operating in.

System-to-Code Mapping

The Skills guide maps directly to Flue’s agent authoring model. defineAgent owns the agent’s behavior and receives skills alongside model configuration, instructions, tools, and sandbox settings. Skill imports are build-time content references, not runtime file reads from arbitrary project paths. That is why the guide emphasizes that placing a directory under src/skills/ does not make it available by itself. The application must import the entry point and attach the resulting reference to the agent configuration that should receive it.

Sources: apps/docs/src/content/docs/guide/skills.md

This mapping also explains why skills are safe to compose with tools and sandboxes without blurring responsibilities. A skill can tell a repository reviewer how to evaluate evidence, but a repository tool or sandbox gives the reviewer a way to inspect code. A skill can describe an operational workflow, but an action or workflow definition performs durable application work. Keeping these contracts separate makes agent behavior easier to audit: guidance is packaged as content, capabilities are exposed as code, and workspace access is controlled by sandbox configuration.

Next Steps

To add a skill, create a SKILL.md bundle, import it with with { type: 'skill' }, and register the imported reference in the target agent’s skills array. Then decide whether the content should be application-owned or workspace-provided. If it is application-owned, keep secrets out of the directory because the bundle is deployed content. If it is workspace-provided, place it under <cwd>/.agents/skills/ and ensure the harness sandbox points at the workspace that should supply it.

Sources: apps/docs/src/content/docs/guide/skills.md

Read Project Layout next to understand where Flue expects authored source such as agents, workflows, and skill directories to live. Read Building Agents to see how skills sits beside model, instructions, tools, and sandbox settings in a complete agent harness. Read Tools and Sandboxes when a skill’s guidance needs executable capabilities, API calls, filesystem access, or shell work.