← Docs

External skills

External skills are the skills Brisal loads from your personal ~/.agents/skills folder — one of the four tiers a skill can come from, and the only one that reaches outside any single workspace. Enable it once and every workspace on your machine sees those skills.

The point of the folder convention is sharing across tools: ~/.agents/skills is a personal, tool-agnostic home for your own skills, so the same SKILL.md you keep there is available to Brisal and to any other agent tool that reads the same location — author a skill once, use it everywhere.

External skills are opt-in. Until you turn the tier on, Brisal ignores the folder entirely — nothing in ~/.agents/skills reaches the agent. There are two places to flip that switch: the first-launch prompt and Settings › Skills. Both point at the same setting, which is global — it applies across every workspace, not per-workspace.

The first-launch prompt

The first time you launch Brisal, it asks whether to load your external skills before you’ve been anywhere near Settings:

The "Enable your external skills?" dialog over a fresh Brisal window. Body text: "Brisal can load skills from your personal ~/.agents/skills folder so you can use the same skills across tools. You can change this later in Settings." Below it an "External skills path" field showing a path ending in /.agents/skills, then two buttons: "Disable" (outlined) and "Enable" (filled).

  • Enable turns the tier on and starts loading skills from the shown ~/.agents/skills path.
  • Disable leaves the tier off — the default state.

Whichever you pick, it’s not final: the dialog itself says “You can change this later in Settings,” and the switch below is the same one.

Enabling and disabling in Settings

The External tier’s global switch lives in Settings › Skills. Off by default, the External skills card shows the ~/.agents/skills path and an Enable button:

The Settings › Skills page. Intro: "System-wide skills settings. The External tier links Brisal to your personal ~/.agents/skills folder." An "External skills" card: "Opt in to load skills from ~/.agents/skills. Your own skills override same-named Brisal builtins. This setting is global — applies across every workspace." with "Enable external skills — Disabled", the path /Users/anynines/.agents/skills, and an Enable button. A "Brisal builtins" card: "The Builtin tier ships with Brisal itself and is always on — you can't disable it. Same-named user skills can override it when External is enabled."

Enabling points Brisal at ~/.agents/skills; a confirmation toast follows, and the button flips to Disable so you can turn the tier back off at any time:

The Settings › Skills page after enabling. The External skills row now reads "Enabled" with a Disable button, and a green toast says "External skills enabled — Brisal will load skills from your ~/.agents/skills folder."

The Brisal builtins card on the same page is informational: the Builtin tier is always on and can’t be switched off. What enabling External unlocks is override — see below.

Precedence: your skills override builtins

External sits above Builtin in the skill precedence order:

project  >  workspace  >  external  >  builtin

So once External is on, a skill of yours in ~/.agents/skills overrides a same-named Brisal builtin — your version wins, the builtin is hidden (not deleted), and Brisal tells you so. A workspace or project skill of the same id still outranks your external one. The full precedence rules, and how hidden skills are surfaced, live on the Skills page.

  • Skills — the parent concept: what a skill is, all four tiers, precedence, and authoring.
  • Settings — the machine-wide vs. per-workspace model, and where this global switch fits.
  • In-app help — the brisal-docs Builtin skill your external skills can override.