Skills

A skill is a package of instructions an agent can load when it needs it: a house style, a review checklist, the steps for a deploy, the shape of your API. Instead of stuffing all of that into a system prompt that is paid for on every turn, an agent carries only the names of its skills and pulls a body in when the work calls for it.

Skills live under Build → Skills, and you assign them per agent in the agent editor.

The format

SynapseOrch uses Claude Code's skill format, deliberately — YAML frontmatter carrying name and description, then a markdown body:

---
name: api-review
description: How we review a pull request that changes a public API.
---

Check, in order:

1. Is the change additive? A removed field is a breaking change...
2. ...

That shape is already on disk in thousands of repositories, so a skill written for one product works in the other and nobody has to maintain a converter. Unknown frontmatter keys are kept but ignored, for the same reason.

A skill is instructions, not a dataset. Anything bigger belongs in the vault.

Why it stays cheap

Progressive disclosure is the whole design:

• Every turn an agent pays only for its skills' names and one-line descriptions — the roster.
• The body enters the context once, through the native load_skill tool, and only when the agent decides it needs it.

So giving an agent twenty skills costs twenty lines of prompt, not twenty documents. Write descriptions that make the choice obvious — the description is the only thing the agent sees when deciding whether to load one.

Two sources, one list

The library is a tenant-scoped collection you create and edit in the UI. It is the one place to add a skill that behaves identically in every deployment of the engine.

The disk is .agents/skills/ scanned at the install root, plus whatever SYNAPSE_SKILLS_DIR points at. It is read-only, so skills already sitting on the machine are offered without an import step. Deployments whose images do not carry the directory simply find nothing.

On a name collision the library wins — you made that one deliberately — and the disk copy is shown as shadowed rather than silently dropped.

Installing from the Skills CLI

Where Node is available, Install from skills.sh runs npx skills add <package> -g -y — a package such as anthropics/skills or vercel-labs/agent-skills@vercel-react-best-practices — into your user skills folder, ~/.agents/skills, and reports what appeared. The screen checks first, so a machine without Node says so up front instead of failing at the end of a form. When the install fails, the screen shows the CLI's own output.

Assigning skills to an agent

In the agent editor, tick the skills this agent may load. The agent gets the roster in its prompt and the load_skill tool alongside its other tools.

A step that passes an explicit tool list runs without load_skill, the same way it runs without the memory tools — the step's tool list is the whole tool list.

Skills, memory and the vault

Reach for a skill when you are telling an agent how to do something. Reach for the vault when you are giving it material to work from.