Skills

A skill is a packaged bundle of instructions an agent can reach for when it’s relevant — a “how to do X” playbook that lives outside the agent’s own system prompt. It’s a Markdown file, SKILL.md, with a short YAML frontmatter (a name, a one-sentence description of when to use it) followed by the procedure in the body.

The split from the system prompt is the point:

• An agent’s system prompt is always on — the standing personality and rules carried into every message.
• A skill is pulled in on demand — its one-line description advertises when it applies; the full body loads only when the task calls for it. That keeps the agent’s context lean while still giving it deep, specific know-how the moment it’s needed.

Skill vs agent vs tool

Three neighbouring words; keeping them apart makes the rest easy.

The agent is the actor; a tool is something it does; a skill is knowledge it consults. Reading a skill is itself done through a tool (read_skill), which is why an agent’s tool policy governs whether it can use skills at all.

The anatomy of a skill

A skill is a folder named for the skill, containing a SKILL.md file:

skills/
  commit-helper/
    SKILL.md        ← the skill: frontmatter + body
    examples.md     ← optional partials the body can pull in

SKILL.md opens with a YAML frontmatter block fenced by ---, then the instructions:

---
name: commit-helper
description: Draft a Conventional Commit message from the staged diff. Use when the user asks for a commit message.
user-invocable: true
argument-hint: "[scope]"
---

# Commit helper

When asked for a commit message:

1. Inspect the staged diff.
2. Pick the Conventional Commit type (feat, fix, docs, …).
3. Write a concise summary line, then a short body explaining *why*.

Only description is required (name defaults to the folder); everything else is optional. The body below the frontmatter can also expand templating tokens when the skill runs — $ARGUMENTS and $N for invocation arguments, @@path to splice in a sibling file, !`cmd` to run a shell command inline — which is what makes a skill more than static text.

The complete field reference — every frontmatter key (including the reserved, not-yet-enforced ones) and every templating token — lives on its own page: Skill frontmatter & templating.

Authoring a skill in the app

Skills are files, but you don’t have to leave Brisal to write them. Each workspace has a Skills tab with its own authoring flow.

An empty workspace shows a prompt to create your first one:

New Skill opens a dialog that scaffolds the folder and SKILL.md for you:

That drops you into the editor, split into a Frontmatter (YAML) pane and a Body (Markdown) pane. The Insert key button adds recognized frontmatter keys, and the body legend documents the templating tokens. File / Folder let you add partials to the skill package; Rename, Delete skill, and Save do what they say.

Saving switches to a read-only view of the same panes, with an Edit button to go back:

The four tiers

Every skill belongs to one of four tiers, which decide how widely it applies and where it’s authored. In increasing precedence:

• Builtin — the tier for skills that ship inside Brisal itself. Always on; you can’t disable it. It’s the home for any skills Brisal bundles with the app (the documentation skill is planned to land here).
• External — skills from your personal ~/.agents/skills folder, shared across every workspace on your machine. Opt-in: off until you enable it in Settings › Skills.
• Workspace — skills owned by one workspace and shared by everything inside it. The everyday tier, authored from the Skills tab.
• Project — skills that ship inside a project’s own files, traveling with the codebase. Trust-gated: a project’s skills load only once you’ve trusted it.

Precedence: the more specific tier wins

When the same skill id exists in more than one tier, the higher-precedence one wins:

project  >  workspace  >  external  >  builtin

So a project can override a workspace skill, a workspace can override one of your external skills, and any of your own skills can override a same-named Brisal builtin. The overridden copy isn’t deleted — it’s hidden, and Brisal tells you so (see Hidden and invalid) rather than dropping it silently.

External skills in Settings {#external-skills-in-settings}

The External tier is the one tier with a global switch, because it reaches outside any single workspace. It lives in Settings › Skills:

Enabling it points Brisal at ~/.agents/skills; a confirmation follows:

The Builtin card on the same page is informational: the builtin tier is always on and can’t be switched off, but your own skills override same-named builtins once External is enabled.

How a skill gets used

There are two ways a skill comes into play:

1. The agent pulls it in. Every visible skill’s description is offered to the agent as a menu (<available_skills>). When a task matches, the agent reads the skill through its read_skill tool and follows the body. A skill with disable-model-invocation: true is kept off this menu.
2. You invoke it by hand. Type /skill:<name> in the chat composer to run a skill on demand, passing arguments that fill $ARGUMENTS / $N / $name in the body. Only skills with user-invocable: true (the default) appear in the / picker; the argument-hint shows there to remind you what to type.

Reading a skill is a tool call, so the agent’s tool policy governs the automatic path — an agent restricted away from tools can’t consult skills on its own.

Hidden and invalid skills {#hidden-and-invalid}

Brisal never drops a skill without saying so. Alongside the active list it accounts for two other cases:

• Invalid — a file that looks like a skill but failed to parse (missing description, malformed YAML, an illegal name). It shows in the list with an INVALID badge and the exact reason, so you can fix it — it never crashes the list.
• Hidden — a skill discovered but not in the agent’s active list, because a higher-precedence tier shadows it (same id) or its name disagrees with its folder. Each entry says why.

Invalid skills stay visible with their parse error, rather than vanishing.

What to read next

A skill is a capability an agent draws on — so the neighbours are the agent that uses it and the project that can ship one:

• Agents — the assistant that consults skills, and the tool policy that decides whether it can.
• Projects — how a project ships its own skills, and the trust gate that guards them.
• Sessions — where all of this meets a real conversation, and where /skill invocation happens.