Skip to main content

Skills and roles

Skills and roles change different parts of an agent:

  • A skill is contextual knowledge that is inactive until a human enables it or one of the documented model/agent invocation opt-ins loads it.
  • A role defines a sub-agent persona, optional model override, and tool allow-list used by task.

Neither grants new host capabilities. Skill prose can guide a plan; role tools can only narrow the parent's available operation set.

Skills​

A skill may be a Markdown file or a directory containing SKILL.md. Flux-native and Agent Skills/Claude-compatible metadata is accepted:

---
name: rust-style
description: Project conventions for Rust changes and verification.
triggers: [rust, cargo, clippy]
---

Use `cargo fmt --all` and keep clippy clean with warnings denied.

Discovery reads and parses the whole skill file, but discovery alone does not put its body in the prompt. Skills are inactive by default: user-message keywords, names, descriptions, and triggers do not activate one. Enable one or more by name:

flux run --skill rust-style "fix the parser"
flux run --skill rust-style --skill release-checks "prepare the release"

An unknown name fails before a model call. Once enabled, the skill body is injected on every turn of that agent. triggers remain compatible metadata for tooling and a future evaluated router; they are not an automatic activation mechanism.

A skill's supporting files — references/*.md, scripts, templates next to SKILL.md — are never loaded into the prompt. Instead the injected <skill> tag discloses where the skill lives (its directory for a SKILL.md skill, the file itself for a flat one), so a body that says "see references/extra.md" gives the model an anchor to read it lazily, on demand, at ordinary read cost — never eagerly, and never with a widened grant (the read still goes through the normal authorization/approval flow). See Claude Code compatibility for the details.

A skill may also carry Claude's allowed-tools and model — both honored:

---
name: reviewer
description: Read-only review — no edits, no shell.
allowed-tools: Read, Grep, Glob
model: haiku
---

Review the diff for correctness and style. Do not modify files.
  • allowed-tools narrows the turn's surfaced ops to the listed set while the skill is active (translated from Claude tool names to flux ops — Bash→bash, Edit→edit, Read→read, Grep→grep, Glob→glob, Write→write, WebFetch→web.fetch, WebSearch→web.search, Task→task). This narrows only — it sits on top of whatever policy/group gating already produced and never grants an op that wasn't already available. An entry with no flux equivalent warns at load and is dropped.
  • model overrides the turn's model while the skill is active, but an explicit --model (or SDK model choice) always wins — the skill only fills in when nothing more specific set one, the same precedence a role's model resolves against its parent.
  • Any other Claude field flux recognizes but doesn't implement (context, agent, hooks, license, compatibility) warns once at load, naming the skill and the field, instead of vanishing silently.
  • agent-triggerable: true (flux extension, default false) lets the agent itself invoke this skill mid-turn via the guarded command.invoke op, on top of policy and session-discovery gates — a human-activated skill (--skill) stays the default; this flag is a separate, explicit opt-in for agent-side invocation. See Agent-side invocation.

Model-invoked skills (opt-in)​

By default, flux does not advertise the general discovered-skill catalog to the model; explicit --skill/AgentSpec.skills activation is the baseline. The narrower agent-triggerable: true path described above remains a separate per-skill opt-in. If you want Claude Code's progressive-disclosure ergonomics—surface every eligible skill's name and description, then let the model load a body on demand—and accept the extra tokens, opt in:

flux run --skills-model-invoked "find and use the right skill for this"

or in .flux/config.toml:

[skills]
model_invoked = true

or from the SDK:

// ClientBuilder
Client::builder().model_invoked_skills().build(provider, ".")?;

// AgentSpec (set `cwd` first — discovery is rooted there)
AgentSpec { cwd: root, ..AgentSpec::new("sonnet") }.try_with_model_invoked_skills()?;

With the opt-in on, every discovered skill except one marked disable-model-invocation: true gets its name+description appended to the system prompt as a compact listing; the model pulls a body into context by calling skill.load(name), which only appears in the op catalog when the opt-in is on and at least one loadable skill exists. A loaded skill then behaves exactly like an explicitly --skill one for the rest of the session — its full body is re-injected on every later turn too. This is additive to --skill/AgentSpec.skills, not a replacement: both can be active at once. See Model-invoked skills (opt-in) for the full semantics.

Default precedence, highest first:

  1. project .flux/skills;
  2. project .claude/skills;
  3. ~/.flux/skills;
  4. ~/.agents/skills;
  5. ~/.claude/skills.

Repeatable --skill-dir entries precede all defaults. [skills] dirs comes next, with project entries before user entries. Earlier directories win when two skills share a name. These options change discovery only; use --skill to activate a discovered name.

flux skill [cli|lang|plugin|ops] prints a generated skill; add --install for project .flux/skills, or --install --global for ~/.claude/skills. Installation does not activate it; pass --skill <name> when you want it. flux plugin skill generates the operation reference for installed plugins.

Sub-agent roles​

Put roles in .flux/agents/<name>.md in the project or ~/.flux/agents/<name>.md for user-wide reuse. The filename stem is the default role name:

---
description: Read-only repository reconnaissance
profile: general
model: haiku
thinking: true
effort: low
tools: [read, glob, grep, git_status, git_diff]
---

Inspect the requested area quickly. Do not modify files. Return evidence with paths.
  • Omit model to inherit the parent's model. A role's model resolves against the parent's provider aliases.
  • profile defaults to general, so the Markdown body is authored instructions after Flux's universal harness protocol. Set profile: coding only when the role should inherit the coding lifecycle as well.
  • Omit thinking and effort to inherit the parent's reasoning policy. Set them explicitly to override it for that role (effort: low, medium, high, xhigh, or max).
  • Omit tools to inherit the tools available to the parent.
  • Use tools: [] to grant no operations.
  • A listed tool is still subject to policy, approval, and the parent capability floor.

Role catalogue​

The catalogue separates Flux's embedded fallbacks from roles defined by this repository. A project or user role with the same name takes precedence over an embedded fallback. Delegate, for example, with task({role: "scout", task: "map the parser"}).

Embedded fallback roles​

These six role instructions ship as assets in Flux and are available when no project or user role defines the same name.

RolePurposeKindSource
scoutRead-only, compressed codebase reconnaissance.Embedded fallbacksource
plannerTurns a task into ordered subtasks and open questions without editing.Embedded fallbacksource
workerExecutes a delegated subtask with the operations available to it.Embedded fallbacksource
reviewerReviews described changes while remaining read-only.Embedded fallbacksource
evaluatorDecides whether a goal is satisfied or gives one next instruction.Embedded fallbacksource
summarizerCondenses conversation state into durable facts, decisions, and open threads.Embedded fallbacksource

Roles defined by this repository​

These tracked .flux/agents files are repository-defined overrides or examples. They describe how Flux's own project delegates work; they are not additional universal roles installed into every Flux project.

RolePurposeKindSource
flux-lang-writerAuthors and validates the smallest requested Flux-Lang change without using effectful execution as a syntax check.Repository-defined override/examplesource
product-scoutExamines user value, UX, and scope for the multi-perspective example.Repository-defined override/examplesource
release-scribeDrafts engineering and customer release notes from supplied commit evidence.Repository-defined override/examplesource
review-correctnessReviews a frozen context pack for correctness defects without tools.Repository-defined override/examplesource
review-maintainabilityReviews a frozen context pack for maintainability issues without tools.Repository-defined override/examplesource
review-projectReviews one dynamically selected project-specific dimension with read-only tools.Repository-defined override/examplesource
review-securityReviews a frozen context pack for security defects without tools.Repository-defined override/examplesource
review-synthesizerCombines project-adaptive reviewer reports without strengthening their evidence.Repository-defined override/examplesource
risk-scoutExamines failure modes, security, and operational risk for the multi-perspective example.Repository-defined override/examplesource
tech-scoutExamines architecture, implementation, and feasibility for the multi-perspective example.Repository-defined override/examplesource

This GitHub-backed inventory is derived only from tracked repository files. Any other ignored .flux/agents/*.md files in a checkout are local scaffolding: Flux may discover them in that local project, but they are not shipped by the repository and therefore do not appear in this catalogue.

.agents/skills and .claude/skills are compatibility discovery locations for reusable project skills. Their existence does not replace Flux's harness prompt and discovery does not activate a skill; only the activation paths described above inject its body.