Skills

A skill is a file inside an agent: skills/<name>.md. When an agent loads the agent it receives every skill in full, in the same payload as the instructions, and follows them for everything it produces for that concern. Skills are how a team gets consistent output from agents without repeating the same rules in every prompt: how to format a chart, how to build a customer-facing HTML page, which colours and names the brand uses, how a runbook is structured.

A skill applies to everything an agent makes for the agent's concern. For one recurring job with its own steps and inputs, such as the monthly all-hands deck or the release notes, write a workflow instead: workflows/<name>.md in the same agent.

Where skills live

skills/ sits next to BRAIN.md, INDEX.md, workflows/ and memory/ in the agent. It holds files directly, with no subfolders. File names use letters, digits, ., _ and - and end in .md, for example skills/chart-formatting.md.

The file is markdown. Its title is the first heading, or the name: line when the file starts with header lines:

---
name: Chart formatting
description: How every chart we publish should look.
---

Header lines are optional.

Each skill has versions, a diff between any two and restore, under History.

Skills are protected

Skills set rules, so they change under review, like BRAIN.md and workflows:

• In the app, open the agent, pick the skill under Knowledge and choose Edit. With write access you choose between Save directly and Propose change; with read access your edit goes to Review. New file with type Skill creates one from a short starter.
• From an agent, brain_write or propose_change on skills/<name>.md never edits the file. It files a proposal that a person with write access approves in the Review tab, in whole or hunk by hunk. A new skill is proposed the same way. See Proposals and review.
• Removing a skill is done by a person in the app.

Prompts that work: "Propose a skill for the design-system agent from these chart conventions." "The brand skill still says the old product name, propose a fix." The agent tells you the change is waiting for review.

Sharing skills between agents

Keep a skill in one agent and include that agent where it should apply: a brand agent included by support and by sales. Agents that load support get the brand skills after support's own, marked from_brain: "brand". See Includes.

Ordering

Agents are told that when two skills conflict, the earlier one wins. The agent's own skills come first, sorted by file path, then each included agent's skills in the order of the includes. To put a general rule ahead of a specific one, name the files so they sort that way, for example skills/01-brand.md and skills/02-charts.md.

What agents receive

load_brain returns skills as a list of {path, title, markdown, from_brain}. The agent's instructions say skills apply to everything produced for this concern. When the payload exceeds its character budget, the source index is trimmed first, then memory excerpts, then skill bodies from the end of the list: a trimmed skill keeps its path and title with truncated: true, and the agent reads the body with brain_read. So keep skills short and put the most important ones first. brain_search covers skills, including those of included agents, so an agent can find the rule it needs without reloading the agent. The Agent view tab of the agent shows the payload.

Everyone who can read the agent receives its skills. Skills from an included agent arrive only for callers who can read that agent too.

Good practice

• Keep each skill to one job: one for charts, one for page layout, one for tone. Short skills survive the payload budget and are easier to keep right.
• Write in the imperative: "Use the 12-column grid", "Put the summary first", "Never ship a chart without axis labels".
• Give one example of the output you want, and one of what to avoid, rather than a long explanation.
• Say when the skill applies, so the agent can tell whether it is relevant to the task in front of it.
• Update the file when the rule changes; every agent gets the new version on its next load_brain. History shows who changed what.
• Keep the instructions (BRAIN.md) for purpose, reading order and rules of engagement; keep skills for how to produce things.
• List each skill in INDEX.md with one line on when to read it.

A starter skill

# Chart formatting

## When to use

Any chart, sparkline or KPI tile in a page published for this brain.

## Steps

1. Pick the form from the data: bars for comparisons, lines for change over
   time, a table when there are fewer than four values.
2. Use the workspace palette: primary #2563eb, secondary #64748b, alert
   #dc2626. Never more than four series on one chart.
3. Label both axes with units. Start bar axes at zero.
4. Put the takeaway in one sentence above the chart.

## Output

A self-contained HTML page with the chart inline (no external assets), the
data table under it, and the source named in a footer line.