Skip to main content

Skills

A skill is a folder of instructions, and optionally scripts, that an agent loads only when a request needs it. Use skills for playbooks, workflow rules, formatting standards or support procedures that would bloat every system prompt.

The agent sees a short list of its skills, with name and description. When one fits, it calls load_skill and gets the full SKILL.md.

Create a skill​

Skills follow the open Agent Skills format. Put the folder under broods/:

broods/
support-flow/
SKILL.md
examples/escalation-policy.md
scripts/triage.py
broods/support-flow/SKILL.md
---
name: support-flow
description: Handles support triage and escalation decisions.
---

# Support flow

Use this skill when a customer reports a product issue.

1. Classify urgency.
2. Identify the product area. See examples/escalation-policy.md.
3. Run scripts/triage.py with the ticket text to get a suggested queue.

Then declare it and allow it on the agent:

broods/index.ts
import { defineAgent, defineSkill } from "broods";

export const supportFlow = defineSkill({
name: "support-flow",
path: "support-flow",
});

export const support = defineAgent({
name: "support",
skills: { enabled: true, allowed: [supportFlow] },
});

broods dev checks that SKILL.md exists, bundles the folder and uploads it.

The description decides when the model loads the skill, so write it as a routing hint. Keep long examples and tables in separate files. The model asks for them by path only when SKILL.md points to them.

Rules and limits​

RuleValue
NameLowercase letters, digits and hyphens, up to 64 characters. Names containing anthropic, claude or XML tags are rejected.
File sizeThe server accepts 5 MiB per file and 30 MiB per skill, any number of files. broods dev and broods deploy upload a skill too large to send inline, unless the account already holds its exact files. Each upload counts toward the account's 20 uploads per hour, shared with MCP and workspace uploads, so a project that needs more than 20 uploads in one hour (20 changed large skills) cannot sync until the hour passes
FrontmatterMust end within the first 64 KB of SKILL.md. A skill whose frontmatter runs past it is left out of the skill list.
Per agentUp to 32 distinct skills in skills.allowed. Repeats are dropped. An agent saved before this limit runs with its first 32.
File typesText only, meaning .css .csv .html .js .json .md .mjs .py .sh .sql .svg .toml .ts .tsx .txt .xml .yaml .yml
PathsRelative to the skill root. Write SKILL.md, not support-flow/SKILL.md
ScopeSkills belong to the account. A skill's name comes from SKILL.md, not from the folder name.

Do not put credentials in a skill. Use environment variables.

Running scripts from a skill​

When the agent has a workspace, load_skill also copies the bundle into it at .claude/skills/<name>/, mirrored at .agents/skills/<name>/. Scripts ending in .sh, .bash, .zsh, .py, .js, .mjs or .ts are marked executable, so the agent can run them with bash. Every load copies a fresh version. The copy lands in the workspace's own storage, a bring-your-own bucket included; a disk workspace gets no copy, since its files live only on its sandbox.

Without a workspace, the instructions still load, but scripts cannot run in that turn.

Editing skills with an agent​

load_skill is read-only. To let an agent edit a skill, attach the skill's files as a workspace the agent can write to and let it use the normal file tools.

Other ways to upload​

The account API also takes skills from JSON, uploaded files, or a public GitHub tree URL of the form https://github.com/{owner}/{repo}/tree/{ref}/{path}. Only import from repositories you trust, and pin the ref. See POST /v1/skills in the API reference.

The skill demo is a runnable example.