Skills

Skills are modular instruction packages your agents can load on demand. Each skill is a folder with a required SKILL.md file (YAML frontmatter plus a Markdown procedure) and optional supporting files. You upload and edit packages in the Skills page; you assign them to agents in Admin → Agents. Agents see a short catalog on every turn and load the full procedure only when they activate the skill for the current task.

Fontana follows the open Agent Skills (agentskills.io) format so packages stay portable and auditable. Fontana adds workspace namespaces, Convex blob storage, RBAC, Active/Inactive catalog control, and temporary allowed-tools expansion while a skill session is open.

What is a skill?

A skill is a directory whose root contains SKILL.md. Optional conventional folders include references/, scripts/, and assets/; any additional package-relative paths are allowed. Skills teach how to perform a task. The Knowledge Graph holds what your organisation knows.

Why use skills

Long procedures either bloat every system prompt or stay trapped in one agent’s instructions. Skills give you:

• One authored package for a playbook (canvas edits, reconciliations, domain checklists)
• Per-agent assignment so only the personas you choose may activate a skill
• Progressive disclosure so catalog metadata stays cheap until the agent commits to a playbook
• Governed tool expansion while a session is active, without permanently widening the agent’s baseline allowlist
• Audit-friendly sessions with activation, file reads, and close events on the chat transcript

Fontana ships default canvas and workflow skills under the default namespace. You can author more packages in Skills or upload folder trees from your repository.

Package layout (agentskills.io)

A skill directory looks like this:

canvas-creator/
├── SKILL.md          # Required: frontmatter + instructions
├── references/       # Optional: supplemental docs the agent reads on demand
├── scripts/          # Optional: code samples or helpers (not executed by Fontana in V1)
├── assets/           # Optional: templates, static files, lookup data
└── ...               # Any additional files or folders under the skill root

Fontana discovery rule: any directory that contains a SKILL.md becomes a discovered skill, including nested packages under the same namespace.

Optional directories

Folder	Role
references/	Supplemental docs the agent reads on demand (API notes, domain checklists, long tables). Keep each file focused; smaller files use less context per read_skill_file call.
scripts/	Code samples or helpers. On agentskills.io platforms these may be executable; in Fontana V1 they are package files only (not run on the server). Prefer clear dependencies and error handling if you document how operators run them outside Fontana.
assets/	Templates, diagrams, lookup tables, static config. Text files return path, mime type, and size (no multimodal image parts into the model in V1).

These names are conventional, not exclusive. Any additional files or folders under the skill root are valid package paths.

Progressive disclosure

Agent Skills load detail only as the task requires it. Fontana maps that model to three stages (aligned with the agentskills.io specification):

Stage	Budget (guidance)	What enters context	Fontana behaviour
1. Metadata	~100 tokens per skill	name + description for every assigned skill	Catalog block (## Available Skills) in provider instructions each turn
2. Instructions	Keep under ~5000 tokens / ~500 lines when practical	Full current SKILL.md body, plus the list of package-relative file paths	After successful activate_skill
3. Files	As needed	One path’s contents (or binary metadata) per call	read_skill_file while the session is active

Put long reference material in references/ and point to it from the procedure so the agent can pull files only when needed.

File references inside SKILL.md

Use package-relative paths from the skill root:

See [the wiring guide](references/wiring.md) for edge rules.

Example helper (documentation only in Fontana V1):
scripts/validate-ports.py

Keep references one level deep from SKILL.md. Avoid chains where one reference file only points to another nested file.

Namespaces and identity in Fontana

Skills live in the shared workspace filesystem (same explorer as Knowledge Graph; Skills uses a sky accent):

• Files are stored as Convex blobs at (scope: skills, namespace, path) in filesystem_files.
• A skill root is the folder that owns a SKILL.md.
• stableId is that folder path under the namespace (for example team-a/canvas-creator). A SKILL.md at the namespace root uses stable id ..
• Catalog / tool id (what agents activate) is `${namespace}/${stableId}` (for example default/canvas-creator, or default/. for a root package).

Namespaces group packages for operators (for example default for seeded skills, team-finance for a team’s playbooks). Agent assignment always targets a discovered skill row, not a raw folder or namespace.

Manage skills in Flow

Open Skills in the Flow sidebar.

Action	How
Create a namespace	Add namespace, then select it in the tree
Upload packages	Upload folder on a namespace or folder; the tree is preserved, then Fontana reconciles every SKILL.md into the skill catalog
Download	Download a file or folder zip from the tree when you need an offline copy or to move packages between workspaces
Create a skill	Create skill on a namespace or non-skill folder; Fontana writes a starter SKILL.md at the path you choose
Edit files	Select any file (including SKILL.md) to open the editor; Markdown files also have a Preview tab (body only, frontmatter omitted)
Active / Inactive	On a discovered skill’s folder or SKILL.md header, toggle Active / Inactive (same pattern as agents). Inactive skills stay off the agent catalog
Assign to agents	Admin → Agents → select an agent → assign discovered skills
Delete	Delete files or folders from the tree. If agents still assign the skill, Fontana lists those agents and offers Unassign and delete

Operator migration from older versioned skill backups: pnpm skills:convert-backup writes agentskills.io folders you can upload under a namespace.

Skill package writes use the skills RBAC permission (read / write / delete). Assigning skills to agents also requires agent write access. See Roles and RBAC.

Author SKILL.md

SKILL.md must start with YAML frontmatter, then a Markdown body.

Frontmatter Fontana validates

Key	Required	Notes
name	Yes	Human-readable title shown in the catalog and Skills UI
description	Yes	What the skill does and when to use it; include concrete trigger phrases and keywords
allowed-tools	No	YAML list of tool ids from Fontana’s audited catalog (see below)

Fontana validates known frontmatter keys and known tool ids (or trailing-star patterns) when you save SKILL.md. Extra agentskills.io fields such as license, compatibility, or metadata are not part of Fontana’s validated key set today; keep procedure-critical guidance in the Markdown body or bundled files.

Open format vs Fontana name

On agentskills.io, name is a machine id: lowercase, hyphens, max 64 characters, and it must match the parent directory. In Fontana, the directory path (under the namespace) is the stable identity (stableId / catalog id). Frontmatter name is the display title agents and operators see. When you export packages for other Agent Skills clients, rename the folder and frontmatter name to match that client’s rules.

allowed-tools on agentskills.io is documented as an experimental space-separated string. Fontana uses a YAML list of audited catalog ids (and trailing-star prefixes).

Write descriptions that help the model choose the skill: state what the skill does, when to use it, and concrete keywords users or agents will say:

description: Edit Operation nodes on the Fontana canvas. Use when the task is about action params, operation wiring, or Operation node create/update.

Minimal example:

---
name: Canvas Operation Editor
description: Edit Operation nodes on the Fontana canvas. Use when the task is primarily about action params or operation wiring.
allowed-tools:
  - canvas_createOperationNode
  - canvas_updateOperationNode
---

Use this skill when the delegated task is primarily about Operation nodes.

## Before editing

1. Call **canvas_queryCanvas** to read the current graph.
2. Apply changes with the allowed create/update tools only.

allowed-tools

While a skill session is active, Fontana unions the agent’s manual tools with that skill’s allowed-tools list for the turn. When the session closes, those extra tools leave the next turn’s effective set.

You can list exact catalog ids, or use a trailing-star prefix to match many tools:

allowed-tools:
  - canvas_*

canvas_* expands against the live tool catalog (for example all canvas_… tools). Prefer exact ids or tighter prefixes when a playbook must stay narrow (for example operation-only skills should not unlock every canvas mutation).

MCP connection wildcards that already exist in the tool catalog (for example mcp_<slug>.*) stay as catalog entries and expand through the MCP path.

Body content

Write step-by-step instructions, examples, and edge cases in Markdown after the frontmatter. The agent receives this body only after activate_skill. Recommended structure:

1. When to use / when to hand off
2. Preconditions (which baseline tools to call first)
3. Procedure steps
4. Finish checklist (close_skill with reason and result)

Runtime lifecycle

1. Assignment - in Admin → Agents, you attach discovered skills to an agent. Only assigned, Active skills appear in that agent’s catalog.
2. Catalog - each turn, assigned skill name + description values are available so the model can decide whether to activate.
3. Activate - the agent calls activate_skill with the catalog id (namespace/stableId), or you type / in chat and pick an assigned skill (the composer shows an inline name chip; send auto-activates the same session path). Fontana injects the live SKILL.md body and the package-relative filePaths list (SKILL.md itself is omitted from that list).
4. Read files - with an open session, the agent calls read_skill_file for one path at a time (text contents, or path + mime + size for binary files).
5. Close - the agent calls close_skill with reason and result. Provider context redacts closed skill internals on later turns; the transcript keeps audit rows.

Multiple skill sessions can be active at once. Effective tools are the union of the agent baseline and every open session’s expanded allowed-tools. Activation is always explicit (activate_skill or chat /); vector search never auto-activates a skill.

See Tools and MCP for the full tool catalog, and Agents for baseline allowlists.

Authoring guidance (from Agent Skills practice)

• Put trigger language in description so the catalog entry matches real user phrasing.
• Keep SKILL.md as the short procedure; move long tables, schemas, and examples into references/.
• Prefer one skill per coherent job; split operation-heavy work from broad workflow construction when tool sets differ.
• Document finish behaviour: call close_skill with a durable result the parent agent or user can trust after redaction.
• Treat scripts/ as documentation or samples unless your operating model runs them outside Fontana; Fontana does not execute skill scripts on the server in V1.

Skills and the Knowledge Graph

	Skills	Knowledge Graph
Purpose	Repeatable procedures and playbooks	Governed operational knowledge and reference articles
Content	SKILL.md packages with activation lifecycle	Namespace-scoped documents with version history
Retrieval	Catalog plus explicit activation	Automatic pre-turn injection plus agentic search
Typical use	”How to build this canvas pattern"	"What our NAV approval rules say”

Assign both to the same agent when it needs firm knowledge and structured runbooks for complex tasks.

Related

• Agents - assign skills and configure baseline tools
• Tools and MCP - audited tool catalog and MCP connections
• Knowledge Graph - document namespaces and search
• agentskills.io specification - open package format Fontana implements