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. Skills live in Fontana Files namespaces, beside the agents and documents a namespace holds. You upload and edit packages in AI → Skills (/ai/skills), the Fontana Files explorer filtered to namespaces that hold skills; you grant namespaces to agents in AI → Agents. An agent discovers the skills it may open with the skills catalog tool and loads the full procedure only when it activates 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 in Fontana Files, namespace grants, nested skills, and temporary allowed-tools expansion while a skill session is open.

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-namespace grants so only the agents you choose may activate the skills in a namespace
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 one seeded namespace, system, shown as Fontana in the agent’s Skills tree: the abilities (Email, Messaging, Knowledge Graph, Data, Files, Workspaces, Agents and the rest), the Fontana page skills, and the canvas, email-extraction and exception skills, all under skills/ in the system namespace. The finance operations library ships under skills/ in the finance namespace. You can author more packages in Skills or upload folder trees from your repository. A package’s namespace is part of how an agent names it, so the sets stay distinct. Abilities are switched on in the agent’s Abilities section rather than granted as a namespace; see Agents.

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 (matched in any letter case) is a skill, at any depth in a namespace that holds skills. A skill folder can contain further skills; see Nested skills.

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 skill the agent may open	Result of the skills catalog tool (`skills_listSkillsCatalog`), run automatically on the first turn when discovery is on
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

A namespace is one Fontana Files namespace, named exactly as you name it (system, finance, Client Golden Source). The same namespace can hold skills, agents and Knowledge Graph documents; its tags say which: skills, agents, kg. Skills are discovered only in a namespace tagged skills.

A skill root is a folder that holds a SKILL.md. New skills go under the namespace’s skills/ folder, for example skills/canvas-creator/SKILL.md.
stableId is that folder path inside the namespace (for example skills/canvas-creator).
Catalog / tool id (what agents activate) is `${namespace}/${stableId}` (for example system/skills/email, or system/skills/canvas/canvas-steward for a skill nested in the canvas skill).

Namespaces group packages for your teams (for example system for the seeded Fontana skills, team-finance for a team’s playbooks). An agent is granted a namespace; every skill in that namespace is then available to it. There is no per-skill assignment. An agent whose skills is ["*"] (the All namespaces switch in the agent’s Skills section) may open every namespace, including ones created later.

Manage skills in Flow

Open AI → Skills. The page embeds the same explorer as File System (/files), filtered to namespaces tagged skills. Editing a SKILL.md here, in File System, or through Fontana Files is the only way to change a skill.

Action	How
Create a namespace	Add namespace; Fontana creates a namespace with the name you type, tagged `skills`, and selects it in the tree
Upload packages	Upload folder or Upload file on a namespace or folder; the tree is preserved, and every `SKILL.md` in it becomes a skill
Download	Download a file or folder from the tree when you need an offline copy or to move packages between workspaces
Create a skill	Create skill on a namespace or folder; Fontana writes a starter `SKILL.md` at `skills/<name>/SKILL.md`, or inside the folder you chose
Edit a skill	Select `SKILL.md`. Editor shows the rendered instructions (click to edit them in place) beside the icon, name, description and settings; Raw is the whole file; Details is the package’s activity log: every save (with the fields and lines that changed), every delete, and every agent that opened it
Edit other files	Any other text file in the package opens in Raw
Permissions	The namespace’s grants apply. Everyone can read `system`; your team edits the namespaces it holds an editor grant on; a namespace admin narrows grants in its Permissions dialog
Grant to agents	AI → Agents → select an agent → Skills → tick a namespace, or switch on All namespaces. Nested skills sit under the skill that contains them. Set each skill to On-demand or Preloaded.
Delete	Delete files or folders from the tree. Deleting a package removes it from every agent’s auto-load list; the namespace grant itself is unchanged

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

Reading and writing packages follows the namespace’s grants. Granting namespaces to agents 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)
icon	No	Icon key for the agent panel tile and the Skills tree (see below)

Fontana reads the keys in the table when you save or upload SKILL.md, and checks tool ids (or trailing-star patterns) against the catalog. Other frontmatter from a pasted package, such as license, compatibility, metadata, or any extra key, stays in the file. A later edit in the skill panel writes those keys back with Fontana’s own fields. Keep procedure-critical guidance in the Markdown body or bundled files.

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 **data_queryWorkflow** with a narrow JSONPath or JSONata (for example node ids), not a full config fetch.
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.

`icon`

icon names the glyph shown on the skill’s tile in the agent panel and beside it in the Skills tree. It takes one of two forms:

A built-in key such as email, knowledge, workflow, or fontana (the Fontana mark). Seeded Fontana skills without a glyph of their own use fontana.
A Heroicons reference heroicons:<outline|solid>/<name>, where <name> is the icon’s name on heroicons.com (for example heroicons:outline/building-library, which the finance library uses). Both the outline and the solid set are available, drawn in the tile’s current colour.

icon: heroicons:outline/building-library

A heroicons: key that does not follow that form is rejected on save. In the skill editor, the icon selector’s Built-in tab lists the built-in keys and every Heroicon behind a search box, so you can pick a glyph by name instead of typing the key.

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:

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

Runtime lifecycle

Grant - in AI → Agents, you tick the namespaces an agent may use in its Skills section. Every skill in a granted namespace can be opened. Abilities you enable in the Abilities section load through the same mechanism.
Discover - the agent calls skills_listSkillsCatalog for one namespace, or for everything it may open (*). Each row carries the catalog id, name, the first sentence of description, whether it auto-loads, and whether it is already open on this thread (open rows also list the tools the session holds). With Discover skills on first turn on (the default), that call runs automatically before the first reply, after auto-loaded skills have opened. The result is an ordinary tool result in the transcript, so it ages out like other tool output instead of riding in every prompt.
Activate - the agent calls activate_skill with the catalog id (namespace/stableId, for example system/skills/email), 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).
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).
Close - the agent calls close_skill with reason and result. Later turns drop that skill’s extra tools. The transcript keeps the close, and chat shows a failed tool call if the agent uses one of those tools again, asking to reopen the skill.

Nested skills

A skill can hold further skills in its folder tree, and Fontana reveals them progressively:

The catalog and the chat composer list only outermost skills.
Opening a skill makes the skills nested directly inside it listable and openable on that thread. This repeats at every level.
Opening a nested skill by / or auto-load opens its parent skills first.
Closing a skill also closes the skills opened inside it.
A skill’s file list and read_skill_file cover its own files, not the folders of the skills nested inside it.
A namespace grant covers the whole tree.

For example, the seeded system/skills/canvas skill holds the canvas skills (system/skills/canvas/canvas-workflow-creator, system/skills/canvas/canvas-operation-editor, and the rest); an agent sees them once it opens canvas.

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 tool 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.

Agents - grant skill namespaces, switch abilities on, and configure baseline tools
Author agents - upload an agent folder, or hand an external AI the agent authoring skill
Tools and MCP - audited tool catalog and MCP connections
Knowledge Graph - document namespaces and search
agentskills.io specification - open package format Fontana implements