Skills

A skill teaches an employee how to do one kind of work well. You write it as a folder with a SKILL.md file: a short description the employee uses to choose the skill, and instructions it follows once the skill is loaded. Skills need no code, and every employee on a bot can use them.

What a skill is

A skill is a folder whose name matches the skill's name. The folder holds a SKILL.md file and, optionally, any other files the instructions refer to: reference documents, templates, or scripts.

SKILL.md has two parts. YAML frontmatter between --- lines carries the name and a description. The Markdown body after it carries the instructions.

How employees use skills

An employee works with a skill in three steps.

Choose. Each turn, the employee sees a list of the skills available to it: each skill's name, its description, and up to three of its triggers. The description is what the employee reads to decide, so write it to say what the skill does and when to use it.
Load. The employee calls the use_skill tool with the skill's name. The tool returns the instructions, the path of the skill's folder, and the names of its files. This is the one way an employee reads a skill.
Work. The employee follows the instructions. It reads supporting files with read_skill_file and runs bundled scripts with execute.

Triggers never load a skill on their own. The employee always makes the choice. When the list grows long, the employee can search it with find_skills.

Write your first skill

Create a folder named after the skill, with one file in it.

meeting-notes/
└── SKILL.md

---
name: meeting-notes
description: Turn a meeting transcript into decisions, action items with owners, and open questions. Use when someone shares meeting notes or a transcript.
---

# Meeting notes

1. List the decisions that were made.
2. List action items as "owner — task — due date".
3. List open questions that need a follow-up.

Keep each list short. If the transcript names no owner for an item, write "unassigned".

Put the folder in the user skills directory of a bot (see Where skills live). Nebo notices the new folder within about a second, and every employee on that bot can use the skill.

An employee can also write a skill for you. Ask it to save one, and it calls save_skill, which writes the folder into the same user skills directory.

Rules the loader enforces

A skill that breaks one of these rules does not load. Nebo logs a warning and skips it.

Rule	Detail
File starts with `---`	The frontmatter must be the first thing in the file. The file must be UTF-8.
`name` is required	Lowercase letters, digits and hyphens only; no leading or trailing hyphen; no double hyphen; at most 64 bytes.
`description` is required	At most 1,024 bytes.
Fields have the right type	A field with the wrong YAML type fails the whole file. Quote versions, such as `"1.0.0"`.
`platform` matches	If present, the skill loads only on the listed operating systems.

Frontmatter keys Nebo does not recognize are ignored. The body has no size limit, but shorter instructions leave more room for the work. Move long material into files the employee reads when it needs them.

Add files

Any file in the folder other than SKILL.md and dotfiles is available to the employee. Folder names are yours to choose; Nebo gives no special meaning to references/ or assets/. Files under scripts/ or bin/ can be run.

invoice-check/
├── SKILL.md              # required
├── references/
│   └── policy.md         # read with read_skill_file
└── scripts/
    └── totals.py         # run with execute

Refer to files by their path inside the folder, such as references/policy.md. The employee reads them with read_skill_file, which rejects any path that leaves the folder. Scripts run with the execute tool in a sandbox. The SKILL.md reference covers runtimes, environment variables, secrets and network access.

Where skills live

A bot collects skills from several places. When two sources provide a skill with the same name, the later source in this list wins.

Source	Location	Who can use it
Built in	Compiled into Nebo	Every employee
Marketplace	`<data>/nebo/skills/<slug>/<version>/`	Every employee
Plugin	The `skills/` folder of an installed plugin	Every employee
User	`<data>/user/skills/<name>/`	Every employee
Employee package	`skills/` inside an installed employee package	That employee only
Learned	`<data>/learned/skills/<employee>/<name>/`	That employee only

<data> is ~/Library/Application Support/Nebo on macOS, %APPDATA%\Nebo on Windows, and ~/.local/share/nebo on Linux. The NEBO_HOME environment variable overrides it. When an employee has its own skill and a shared skill with the same name, its own skill wins.

Nebo watches these folders and reloads a changed skill after one second. To switch a skill off without deleting it, rename its file to SKILL.md.disabled.

Skills describe work, not tools. Write a skill around a responsibility, such as reconciling receipts, and let the employee use whatever connection the owner provided. When a skill truly needs a plugin, declare it with the plugins field.

SKILL.md reference: every field, tool and variable.
Examples: complete skills to copy.
Publishing: put a skill on the marketplace.