Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Skills, agent files and output styles

Three kinds of file extend what Fontaine tells the model, and each has Claude Code’s frontmatter, so files from a .claude/ directory work by copying. Skills, agent files and output styles are not read from .claude/; instruction files are (see Instruction files).

KindFileWhat it is
Skillskills/<name>/SKILL.mdInstructions for a kind of task, loaded when asked for. Also a /name command.
Agent fileagents/<name>.mdA subagent type.
Output styleoutput-styles/<name>.mdA change to how the agent writes, chosen with /output-style.

They live under two roots: <config dir>/ (yours, loaded in every session) and <root>/.fontaine/ (the repository’s, from the primary workspace root only). Extra roots added with --add-dir contribute nothing. Installed plugins load between the two, under namespaced plugin:name names. These files are prompt content, so they load whether or not you trust the workspace; what they may do is limited as described below.

Frontmatter

A file starts with a --- block of key: value lines, then the body. Values can be plain or quoted text, a list written [a, b] or one item per - line, or a | / > text block. A key Fontaine does not know is ignored, so files written for Claude Code load.

Skills

KeyMeaning
nameThe skill’s name; the directory name when absent. Letters, digits, - and _.
descriptionOne line listed in the system prompt, so the model knows when to load the skill. The first line of the body when absent.
allowed-toolsRules lent to the agent while the skill is active; see below. A plugin skill’s count only after you trust it.
disable-model-invocationtrue keeps the skill out of the model’s skill list and refuses the skill tool; only you run it, as /name.
user-invocablefalse hides the skill from the / menu and from /name; only the model loads it. Default true.
argument-hintShown after the name in the / menu, such as [issue-number].
modelChecked and otherwise unused.

Agent files

KeyMeaning
name, descriptionAs above; the file name when name is absent.
toolsThe tools of the type: a list or a comma-separated string. Absent means every tool the parent has.
disallowedToolsTools taken away from that set.
modelinherit (no model: the session’s), a role name (sonnet, coding), $main, $guardian_default or <account>/<model>. A role you have not defined is an error in your own file and a startup warning in a repository’s or a plugin’s, whose agent then runs on the session model. A skill’s model is checked and not used.
effortinherit (the session’s level), off, low, medium, high or max.
permissionModeinherit, default (that is, manual) or dontAsk.

The body is the subagent’s instructions.

Output styles

name (the file name when absent) and description. The body is added to the system prompt.

Tool names

The same names, with a Claude Code name first, are what Agent SDK mode shows on its wire and accepts in --allowedTools, --disallowedTools and --tools. Programmatic agent types from an SDK host are a session-only origin: they are not files, and a plugin reload keeps them.

tools, disallowedTools and allowed-tools take Claude Code’s tool names, renamed on load:

Claude CodeFontaine
Readread
Edit, MultiEditedit
Writewrite
NotebookEditnotebook_edit
Glob, Grep, LSglob, grep, ls
Bashshell
BashOutput, BashOutputTool, TaskOutput, AgentOutput, AgentOutputTooljob_output
KillShell, KillBash, TaskStopjob_cancel
Monitormonitor
LSPlsp
PowerShellpowershell
WebFetchwebfetch
WebSearchwebsearch
Task, Agentagent
Skillskill
SendMessagesend_message
AskUserQuestionask_user_question
TodoWritetodo_write
CronCreatecron_create
CronListcron_jobs
CronDeletecron_delete
ScheduleWakeupschedule_wakeup

A (specifier) is kept as written, so Bash(git *) becomes shell(git *), and the result must be a valid permission rule. Fontaine’s own names (shell, mcp__github__create_issue) are accepted as they are. In an agent file, an entry with a specifier limits that tool: the subagent may use shell only as git status, and a disallowedTools entry with a specifier forbids just the calls it matches.

Anything else is an error that stops startup with exit code 2 and names the file: a Claude Code tool Fontaine does not have (REPL, say), the colon form Bash(git add:*), which is not Fontaine’s rule syntax, and a model that is neither a role name nor a model reference (two words). So are keys that would run something or change permissions from inside a file: hooks and mcpServers in an agent or skill file, and permissionMode in a skill. Files load without workspace trust, so they carry no executables of their own.

Skills

The names and descriptions of the skills go into the system prompt, between the instructions files and the output style. The body loads through the skill tool, which takes the skill’s name and optional args, substituted as for /name args. Because it can load nothing but skill text, skill is a read-only tool and needs no approval; what the skill then asks the model to do goes through the permission pipeline like anything else. Arguments the model supplies can form ! commands just as typed ones do; those are still gated as shell (see Commands in a skill), and allowed-tools rules lent by a user-scope skill can apply to them. A personal skill outranks a repository skill of the same name. In the terminal UI, /skills lists every loaded skill with its scope.

Reloading

Skills, agent files and output styles load when a session starts. To pick up added, edited and removed ones in your user and project directories and in installed plugins without restarting, run /reload-plugins between turns: the skill index in the system prompt, the / menu, the skill tool and the agent types follow, the conversation stays, and a trust you recorded with /skills trust takes effect. At each turn boundary Fontaine also checks the modification times of these files (and of plugin manifests, plugins.toml and skill-trust.toml) and, when something changed since the last load, says once: “skills/plugins changed on disk — run /reload-plugins”. It never applies a change by itself, so a stray edit cannot alter the toolset or cost a prompt-cache miss unexpectedly. The system prompt is rebuilt only when what the model sees changed; skill text it read earlier in the conversation is not rewritten, and the next turn says which skills changed or went away so the model treats that text as possibly stale. See Plugins for the plugin side.

Slash commands and arguments

A skill with user-invocable not false is the command /name. Typing / lists the commands and skills with their argument-hint. /name some arguments runs the skill with the rest of the line as its arguments:

  • $ARGUMENTS is replaced by the whole argument string, $ARGUMENTS[N] and $N by the N-th argument counting from 0 (words, with single or double quotes keeping one together); one past the end is empty.
  • A body with no such placeholder gets ARGUMENTS: <arguments> appended when there are arguments.

A built-in command wins over a skill of the same name or alias. The skill gets no / menu entry, startup names it, and the model can still load it with the skill tool.

What you typed (/name some arguments) is recorded as your message; the skill’s text is the agent’s prompt for that turn, not your words.

Commands in a skill

A line !`git status` in a skill body, or a fenced block that starts with ```!, is a command run when the skill loads, with its output put in its place. Arguments are substituted first. Each command goes through the permission pipeline as a shell call by the agent that loaded the skill: it asks, is judged by the guardian or is denied exactly as if the model had called shell. A denied command’s place shows [command failed: ...] and the skill still loads. On Windows without Git Bash there is no shell, so each command is reported as not run ([command not run: the shell tool is not available]) and the skill still loads. A repository’s skill commands run only when the workspace is trusted; a headless run (fontaine -p) runs them without asking, as it does for hooks and MCP servers, unless [headless] require_trust = true and the workspace is not trusted.

allowed-tools

A skill from your own config directory can lend rules, in the Tool(specifier) grammar, to the agent that runs it:

---
description: Run the test suite
allowed-tools: Bash(cargo test), Read
---

They act like allow rules (after the floor and the mode, suspended in auto if broad) from the moment the skill is loaded until the end of that user turn, whether it was loaded by /name or by the skill tool. They belong to the invoking agent only: a subagent it starts does not get them. A repository’s skill cannot approve calls, so its allowed-tools is checked and then ignored, and it can never be trusted. A plugin skill’s allowed-tools is checked and ignored until you trust it.

Trusted skills

Trusting a skill says that you have read its allowed-tools and want them honoured. It is for your own skills and for plugin skills, whose allowed-tools would otherwise be ignored, so a step the skill documents does not stall an unattended run.

fontaine plugin trust dev-skills:pr       # one skill, named as /skills shows it
fontaine plugin trust dev-skills          # every skill the installed plugin has now
fontaine plugin untrust dev-skills:pr

trust prints each skill’s digest, its allowed-tools split as below, and the ! commands it runs, then asks for confirmation. Without a terminal it refuses unless you pass --yes, which skips only the question. In the terminal UI, /skills trust <name> shows the same and asks, and /plugin install asks it for each of the plugin’s skills that declares allowed-tools, while fontaine plugin install on a terminal asks once for all of them. A trust or untrust applies from /reload-plugins in a running session, or from the next session start. The record is <config dir>/skill-trust.toml, described here.

While the record matches the skill file, for the agent that runs the skill and until the end of that user turn:

  • a specific rule (a shell command with no wildcard such as Bash(git status), and every non-shell tool such as Read) acts as an allow, after the floor, your deny and ask rules and hooks, like any other allow rule;
  • a wildcard shell rule (Bash(git *), Bash(npm run *), a bare Bash) is never an allow, in any mode. The guardian is told that the skill is running and which classes of command it declares, so a routine step of that class is easier to allow, while a force-push or a delete is still judged on its own.

A skill in your own skills directory keeps lending all of its rules as before, trusted or not; trusting it adds the note for the guardian.

The record pins the skill file by digest. When the file changes (an edit, or a plugin update), the trust is suspended: a plugin skill’s allowed-tools are off, a skill of yours falls back to the behaviour above without the guardian note, and a notice at the next start or reload says so. Run /skills trust <name> to see what changed and trust the new version. /skills marks each skill (trusted) or (changed (re-trust)). A headless run never asks: a changed or untrusted plugin skill that declares allowed-tools lends nothing and warns once.

Agent files

An agent file adds a type to the registry that agent offers; see Subagents for how types combine. A file in your config directory follows the rules of [agents.types]: permissionMode is inherit, default or dontAsk, and acceptEdits, auto and bypassPermissions are errors.

A file in a repository can only narrow what its parent can do:

  • model is inherit, a role name or $main, never an <account>/<model>, a list or $guardian_default: a role names no endpoint, because you define every role. A role you have not defined runs the agent on the session model, with a warning at startup that names the file and the role. The agent tool’s per-call model is refused for it;
  • no effort, other than inherit: it runs at the session’s level;
  • permissionMode is default (the default) or dontAsk, never inherit;
  • every tool in tools is a tool the parent has: a built-in tool, or a tool of an MCP server that is configured for the session.

A plugin’s agent files follow the same project rules. One relaxation: a plugin agent file that names an MCP server neither the plugin ships nor the session has is skipped with a warning, not an exit-2 startup error — whether that server exists is your configuration, not a defect in the file.

A file that breaks these is an error that stops startup with exit code 2.

Output styles

/output-style lists the styles, /output-style <name> switches to one for the next turn and /output-style none removes it. The style’s text is added to the agent’s system prompt after the skill list. It changes nothing the guardian sees: the guardian’s request and prompt are the same with and without a style.

Porting from .claude/

Copy skills/, agents/ and output-styles/ into <config dir>/ or <root>/.fontaine/, then:

  • check the tools, disallowedTools and allowed-tools lines against the table above, and drop the colon form (Bash(git add:*) becomes Bash(git add *));
  • define the Claude Code model aliases your files use (sonnet, opus) as roles, for example sonnet = ["work/claude-sonnet-5"], or replace them in model with inherit or a <account>/<model>. A skill with model: sonnet loads either way; Claude Code’s per-skill model override is not applied;
  • remove hooks and mcpServers from the file and declare them in settings ([[hooks.*]], [mcp.servers.*]), where they are subject to workspace trust;
  • in a skill, remove permissionMode.