Skills

Skills give agents specialized knowledge and step-by-step procedures for specific types of tasks, following the Agent Skills specification. At session start fuseraft scans your skill directories, injects a catalog of available skills into the system prompt, and exposes tools the model can call to use them. Discovery, frontmatter parsing/validation, and the skill tools themselves all come from the Microsoft Agent Framework’s AgentFileSkillsSource/AgentSkillsProvider — the REPL and fuseraft run orchestration sessions share the exact same implementation, so a skill is treated identically in both.

---

Where skills come from

fuseraft loads skills from five locations, in precedence order (earlier entries win when two skills share the same name):

Scope	Path
Project (fuseraft)	<project>/.fuseraft/skills/
Project (shared)	<project>/.agents/skills/
User (fuseraft)	~/.fuseraft/skills/
User (shared)	~/.agents/skills/
Built-in	shipped with fuseraft

---

How skills work in the REPL

fuseraft uses a progressive-disclosure pattern to keep context lean:

1. Catalog injection — At session start, the names and descriptions of all discovered skills are appended to the system prompt so the model knows what is available without loading every full body.
2. On-demand load — When the model decides a skill is relevant, it calls load_skill("<slug>") to retrieve the full SKILL.md content, then follows those step-by-step instructions using its other tools.
3. Resource reading — If a skill ships supplementary reference material (e.g. under references/), the model reads it with read_skill_resource("<slug>", "<path>"), e.g. read_skill_resource("craft-orchestration", "references/schema-cheatsheet.md").
4. Script execution — If a skill bundles executable scripts alongside its SKILL.md, the model can run them with run_skill_script("<slug>", "scripts/<file>") — the script is named by its path relative to the skill directory. See Bundled scripts.
5. Direct invocation — Type $<slug> at the REPL prompt to invoke a skill immediately without describing what you want. The SKILL.md content is loaded directly into the turn so the model applies the skill right away. Append arguments after the slug to pass context: $commit fix typo in readme. Tab completion cycles through matching skill slugs.

At startup, the skill count appears in the compact info line alongside the active tool categories (e.g. … · 3 skills · …). Run /tools at any time to list all active tools by category, including the Skills category.

Tool	Description
load_skill	Load the full SKILL.md for a skill by slug.
read_skill_resource	Read a supplementary file bundled with a skill (e.g. a file under references/), by path relative to the skill directory.
run_skill_script	Run a script bundled with a skill (.py, .js, .sh, .ps1, .cs) — see Bundled scripts.

read_skill_resource and run_skill_script reject a path that resolves outside the skill directory, including via a symlinked file or subdirectory planted inside it.

If --no-tools is passed, skills are disabled for that session.

fuseraft run orchestration sessions use the same five discovery locations and the same three tools (load_skill, read_skill_resource, run_skill_script), wired onto every agent automatically whenever at least one skill directory exists — there is no need to add Skills to an agent’s Plugins: list, though doing so as a declaration of intent is harmless. This is the same discovery pipeline the REPL uses, not a separate implementation — a skill either works identically in both, or (if its frontmatter is invalid) in neither.

Bundled scripts

run_skill_script takes a skill slug, a script name, and an optional list of arguments:

• Script name — the script’s path relative to the skill directory: scripts/md2docx.cs, not md2docx.cs. A bare filename for a script that lives in a subdirectory is reported as not found.
• Arguments — a JSON array of strings, each passed as one command-line argument (there is no shell parsing, so no quoting is needed). The script runs with its own directory as the working directory, so pass absolute paths for any file it should read or write. If a model sends a flag/value object such as {"--type": "Bug", "--verbose": true} instead, it is flattened into --type Bug --verbose (false is dropped; nested values are rejected).
• Interpreter — chosen by file extension:

Extension	Run as
.py	python3 (python on Windows)
.js	node
.sh	bash
.ps1	pwsh
.cs	dotnet run <file> -- — a single-file C# app; needs the .NET 10 SDK, and the first run restores its NuGet packages
anything else that is discovered (for example .csx)	executed directly, so it needs a shebang and the executable bit

• Result — the script’s standard output, followed by a Stderr: block if it wrote to standard error and a Script exited with code N line if the exit code was non-zero. A script that prints nothing returns (no output).

Scripts run as your OS user with the session’s environment and there is no approval step, so read Security — Skills execution trust model before installing skills you did not write.

---

Shipped skills

fuseraft ships with the following built-in skills, all specific to building and operating fuseraft itself. Install any of them globally with fuseraft skills add:

fuseraft skills add path/to/fuseraft/skills/craft-orchestration

General-purpose productivity skills (not specific to fuseraft) live in the separate fuseraft/skills repository — e.g. commit, sandbox-test, build-docx, datamap, dbconnect, terminal-screenshot, and azure-devops. Clone that repo and install from it the same way:

fuseraft skills add path/to/skills/commit

---

craft-orchestration

Guides the agent through building a valid, runnable orchestration.yaml from scratch. Triggers when the user asks to create or scaffold a fuseraft config, set up a multi-agent pipeline, or convert a described workflow into a runnable config.

The skill gathers requirements (agent roles, model, routing strategy, plugins, validators), picks the right skeleton, generates the YAML, validates it with fuseraft validate, and writes it to disk ready to run.

---

debug-session

Diagnoses a failing, stuck, or unexpectedly terminated fuseraft run session. Triggers when a session looped without progress, raised a ValidatorStuckException, hit the iteration cap, crashed, or stopped with a budget or circuit-breaker error.

The skill reads the session checkpoint, events log, and crash dumps, maps the symptoms to a root cause (stuck validator, missing keyword, context loss after compaction, API failures, sandbox denial), and recommends the exact config or instruction fix.

---

config-audit

Reviews an existing orchestration config for correctness before running it. Triggers when the user wants to validate a config, when fuseraft validate passes but the run still fails, or when a config was recently written or modified.

The skill runs fuseraft validate, then performs a deeper semantic audit: routing keyword alignment, plugin prerequisites, validator dependency chains, termination safety, failure handling, instruction quality, and model alias consistency. Findings are grouped by severity (error / warning / suggestion).

---

mcp-setup

Connects a fuseraft config to an MCP server and wires its tools to agents. Triggers when the user wants to add an MCP server (npm package, Python module, or HTTP endpoint), or when an existing McpServers block is failing at startup.

The skill verifies the server command or endpoint, adds the McpServers entry to the config, wires the plugin name to the right agents, validates the result, and runs a one-turn dry-run to confirm the connection and tool registration.

---

skill-author

Guides the agent through writing a new fuseraft skill from scratch. Triggers when the user wants to create a skill, capture a reusable procedure, or understand how to structure a SKILL.md file.

The skill gathers requirements (what it does, when it triggers, where it lives), writes the frontmatter and body, decides whether reference files or bundled scripts are needed, installs the skill at the chosen scope, and verifies it appears in the catalog.

---

knowledge-setup

Bootstraps the fuseraft knowledge layer in a new or existing project. Triggers when the user wants to set up ADR tracking, the repository semantic graph, architecture drift detection, or objective tracking — or when Decision, Graph, or Objective plugins are wired in a config but the backing stores have not been initialized.

The skill scaffolds .fuseraft/knowledge/ via fuseraft init, builds the repository semantic graph with fuseraft graph build, guides authoring of .fuseraft/architecture.yaml for fuseraft arch check, tunes the lifecycle policy for fuseraft knowledge gc, and wires the knowledge plugins (Decision, Graph, Objective) to the right agents in the orchestration config.

---

repl-tmux-driver

Drives an interactive fuseraft repl session from outside via tmux, for live-testing REPL changes against a real model instead of relying on unit tests alone. Triggers when the user wants to dogfood the REPL agent on a real task, reproduce a REPL bug interactively, or verify /safe-mode, /tools, /hitl, or similar mode toggles against real agent-visible behavior.

The skill covers launching the REPL in a detached tmux session, injecting single- or multi-line input (via /paste plus tmux load-buffer/paste-buffer for anything with embedded newlines), polling for the idle prompt with a wait loop instead of blind sleeps, capturing pane output to a file for review, and cleaning up with /exit so session-end bookkeeping runs.

---

Cross-session handoff: /compact

To pass context from the current REPL session to a new one, use the /compact command. /compact generates a concise summary of what was worked on, key decisions, current state, and what comes next; it then replaces the conversation history with that summary so the session can continue with a clean context window.

If you want to carry a summary to a different session or agent entirely, run /compact and copy the resulting summary into the new session as an opening message.

---

Installing skills

For a single project

Place a skill directory under .fuseraft/skills/ in your working directory:

my-project/
└── .fuseraft/
    └── skills/
        └── my-skill/
            └── SKILL.md

Use .agents/skills/ instead if you want the skill available to other Agent Skills–compatible tools (Claude Code, Cursor, Copilot) running in the same directory.

To share a skill with your team, commit the skill directory. .agents/skills/ is the recommended location for shared skills.

Trust warning: Skills travel with the repository. Treat .fuseraft/skills/ and .agents/skills/ the same as a Makefile or postinstall script — only run fuseraft in directories you trust. See Security — Skills execution trust model.

For all your projects

Use fuseraft skills add to copy a skill into ~/.fuseraft/skills/ and register it in the global search index:

fuseraft skills add ../skills/productivity/handoff
fuseraft skills add ~/my-skills/triage

The command accepts a path to a skill directory (containing SKILL.md) or directly to a SKILL.md file. The slug is derived from the name: field in the frontmatter; if no name: field is present, the directory name is used. If a skill with the same slug already exists it is updated in place — the installed copy is made to mirror the source exactly, so files removed or renamed at the source are pruned from the installed copy too, and directories left empty by that pruning are removed. The whole skill directory is copied (references/, scripts/, and any other bundled files) except for a .git directory or .git file, which is never copied; pointing at a bare SKILL.md file copies only that file.

You can also install skills by placing them directly under ~/.fuseraft/skills/ without using the CLI — skills are loaded from that directory at session start regardless of how they got there.

fuseraft skills add canonicalizes the frontmatter as it installs: if the raw name: field doesn’t already equal the slug it’s being installed under (e.g. it had spaces or uppercase letters), the installed copy’s name: line is rewritten to match. This guarantees an installed skill’s name: and directory always agree, which orchestration requires (see below).

---

Writing a skill

Create a directory named after your skill and add a SKILL.md file:

mkdir -p .fuseraft/skills/my-skill

---
name: my-skill
description: What this skill does and when to use it.
---

# Instructions

Step-by-step guidance for the agent...

fuseraft follows the Agent Skills specification for SKILL.md frontmatter:

Field	Required	Notes
name	Yes	Lowercase letters, digits, and single hyphens only (no leading/trailing/double hyphens); max 64 characters; must match the parent directory name exactly.
description	Yes	1–1024 characters. What fuseraft uses to decide whether the skill is relevant to the current task — write it so it covers both what the skill does and the kinds of tasks that should trigger it.
license	No	License name, or a reference to a bundled license file.
compatibility	No	Max 500 characters. Environment requirements (e.g. Requires docker and jq) — shown in the REPL’s skill catalog as a [requires: ...] hint.
metadata	No	Arbitrary string-to-string map for your own bookkeeping (author, version, etc.). Not surfaced to the model.
allowed-tools	No	Space-separated list of pre-approved tools (experimental, per spec — fuseraft parses but does not currently act on this field).

If your instructions are long, move reference material into a references/ subdirectory inside the skill folder. The agent loads those files on demand — with read_skill_resource — rather than all at once. scripts/ and assets/ are supported the same way.

If two installed skills share the same name, the one in the higher-precedence location wins.

name: must match the directory name exactly. Both the REPL and fuseraft run require name: to match its parent directory name exactly (case-sensitive), to be valid lowercase kebab-case, and require a non-empty, correctly-sized description: — they use the identical discovery pipeline, so there is no REPL-specific leniency here. A skill that violates any of these is silently excluded from the catalog in both surfaces, with the reason logged as a warning or error (visible by default — no --verbose needed). Run fuseraft skills validate [path] to check a skill (or every installed skill) against the full specification before relying on it. The one exception is fuseraft skills add, which stays deliberately lenient — see Installing skills above.

---

Automatic skill generation

When skill curation is enabled, fuseraft automatically creates or updates a skill at the end of qualifying sessions. If the session produced a reusable procedure — a debugging workflow, a multi-step pattern, a problem-solving approach — fuseraft writes it to ~/.fuseraft/skills/ so future sessions can benefit from it.

Trivial or highly project-specific sessions typically produce no output. If a skill with the same slug already exists it is updated in place, so the procedure is refined over time rather than duplicated.

Enabling curation for REPL sessions

Quickest way: fuseraft settings set skillCuration.enabled true (see CLI Reference — fuseraft settings). Or add a skillCuration block to ~/.fuseraft/config directly:

{
  "provider": { "modelId": "claude-sonnet-4-6" },
  "skillCuration": {
    "enabled": true
  }
}

All the standard knobs are supported (minTurns, digestTurns, model, libraryPath, indexTopN, logPath) — fuseraft settings set only exposes the enabled toggle so far, so set these by editing the file directly. Note that skill injection at session start (surfacing relevant skills before the first turn) is only available in fuseraft run sessions — the REPL has no upfront task description to query against.

Enabling curation for fuseraft run sessions

Set SkillCuration.Enabled: true in your orchestration YAML. See Configuration → Skill curation for the full field reference, start-of-session skill injection, and the curation log format.