← Docs

External skills

External skills are the skills Brisal loads from your personal ~/.agents/skills folder — one of the four tiers, and the only tier that reaches outside any single workspace. Once enabled, every workspace on your machine sees these skills.

The folder convention enables cross-tool sharing: ~/.agents/skills is a personal, tool-agnostic location for your skills, making them available to Brisal and any other tool reading that path — write once, use everywhere.

External skills are opt-in and global. Disabled by default, Brisal ignores the folder entirely. Enable it once via the first-launch prompt or Settings › Skills, and it applies across all workspaces.

The first-launch prompt

On first launch, Brisal asks whether to enable external skills:

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 activates the tier and loads skills from the displayed path
  • Disable keeps it off (the default)

Either choice can be changed later in Settings.

Enabling and disabling in Settings

The global switch is in Settings › Skills. Off by default, the External skills card displays the ~/.agents/skills path with 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 it directs Brisal to ~/.agents/skills. A confirmation toast appears, and the button switches to Disable for toggling:

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 is informational: the Builtin tier is always active. Enabling External allows override.

Precedence: your skills override builtins

External sits above Builtin in the skill precedence order:

project  >  workspace  >  external  >  builtin

When External is enabled, your ~/.agents/skills skill overrides a same-named builtin — your version is used, the builtin is hidden (not deleted), and Brisal notifies you. Workspace or project skills of the same id still take precedence. Full precedence rules are 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.