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).
| Kind | File | What it is |
|---|---|---|
| Skill | skills/<name>/SKILL.md | Instructions for a kind of task, loaded when asked for. Also a /name command. |
| Agent file | agents/<name>.md | A subagent type. |
| Output style | output-styles/<name>.md | A 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
| Key | Meaning |
|---|---|
name | The skill’s name; the directory name when absent. Letters, digits, - and _. |
description | One line listed in the system prompt, so the model knows when to load the skill. The first line of the body when absent. |
allowed-tools | Rules lent to the agent while the skill is active; see below. A plugin skill’s count only after you trust it. |
disable-model-invocation | true keeps the skill out of the model’s skill list and refuses the skill tool; only you run it, as /name. |
user-invocable | false hides the skill from the / menu and from /name; only the model loads it. Default true. |
argument-hint | Shown after the name in the / menu, such as [issue-number]. |
model | Checked and otherwise unused. |
Agent files
| Key | Meaning |
|---|---|
name, description | As above; the file name when name is absent. |
tools | The tools of the type: a list or a comma-separated string. Absent means every tool the parent has. |
disallowedTools | Tools taken away from that set. |
model | inherit (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. |
effort | inherit (the session’s level), off, low, medium, high or max. |
permissionMode | inherit, 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 Code | Fontaine |
|---|---|
Read | read |
Edit, MultiEdit | edit |
Write | write |
NotebookEdit | notebook_edit |
Glob, Grep, LS | glob, grep, ls |
Bash | shell |
BashOutput, BashOutputTool, TaskOutput, AgentOutput, AgentOutputTool | job_output |
KillShell, KillBash, TaskStop | job_cancel |
Monitor | monitor |
LSP | lsp |
PowerShell | powershell |
WebFetch | webfetch |
WebSearch | websearch |
Task, Agent | agent |
Skill | skill |
SendMessage | send_message |
AskUserQuestion | ask_user_question |
TodoWrite | todo_write |
CronCreate | cron_create |
CronList | cron_jobs |
CronDelete | cron_delete |
ScheduleWakeup | schedule_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:
$ARGUMENTSis replaced by the whole argument string,$ARGUMENTS[N]and$Nby 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 asRead) 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 bareBash) 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:
modelisinherit, 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. Theagenttool’s per-callmodelis refused for it;- no
effort, other thaninherit: it runs at the session’s level; permissionModeisdefault(the default) ordontAsk, neverinherit;- every tool in
toolsis 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,disallowedToolsandallowed-toolslines against the table above, and drop the colon form (Bash(git add:*)becomesBash(git add *)); - define the Claude Code model aliases your files use (
sonnet,opus) as roles, for examplesonnet = ["work/claude-sonnet-5"], or replace them inmodelwithinheritor a<account>/<model>. A skill withmodel: sonnetloads either way; Claude Code’s per-skill model override is not applied; - remove
hooksandmcpServersfrom the file and declare them in settings ([[hooks.*]],[mcp.servers.*]), where they are subject to workspace trust; - in a skill, remove
permissionMode.