# Skill Block Format

Agents emit a fenced `skill` block when they discover a durable, reusable workflow that future agents are likely to need. See [`playbooks/shared-rules.md`](../playbooks/shared-rules.md) for the eligibility threshold and the "zero skills is the default" rule.

The engine extracts valid blocks from agent stdout and from inbox findings (`notes/inbox/*.md`) and writes them into the selected runtime's native personal skills directory (e.g. `~/.claude/skills/<name>/SKILL.md` for Claude, the equivalent personal skills directory for Copilot). Project-scoped skills are landed via PR into the matching project's playbook tree.

## Block format

````
```skill
---
name: short-descriptive-name
description: One-line description of when to trigger this skill
scope: minions
---

# Skill Title

## Steps
1. ...
2. ...

## Notes
...
```
````

### Frontmatter fields

- `name` (**required**) — kebab-case identifier; becomes the on-disk directory name.
- `description` (**required**) — one-line "when to use this" hint shown in skill listings.
- `scope` — `minions` (default; user-level skill, available in any runtime window) or `project` (repo-local skill, landed via PR into that project).
- `project` — required when `scope: project`; the project name the skill belongs to.
- `allowed-tools` (optional) — comma-separated tools the skill is permitted to call (e.g. `Bash, Read, Edit`).
- `trigger` (optional) — natural-language phrase describing when an agent should invoke the skill.

### Body

Plain Markdown. Include the steps, commands, file paths, and notes another agent needs to follow the workflow without reading the original task context. Cite source files and PR numbers where useful — the body is what future agents actually read.

## When not to emit a skill

See [`playbooks/shared-rules.md`](../playbooks/shared-rules.md) for the full threshold. In short: do not emit a skill for one-off bug fixes, isolated command output, obvious repo facts, or anything already covered by existing docs, playbooks, or skills.
