Skills

A skill is one of the simpler parts an app can ship: a small plain-language guide an agent loads when it needs it. Skills are listed in app.yaml and live in their own folders under src/.

This page covers writing SKILL.md files. For callbacks registered on the daemon's runtime, see Hooks.

Writing skills

A skill is a small plain-language guide written for agents. Its entry point is a SKILL.md file in its own folder, listed in app.yaml; the folder can also carry supporting files the body references, and they ship with the pack:

skills:
  - skills/app_creation

The layout is one folder per skill:

src/skills/<name>/SKILL.md

SKILL.md frontmatter

A SKILL.md is YAML frontmatter followed by a Markdown body:

---
name: app_creation
description: One sentence on when to use this skill
tools: [Read, Edit, Bash]
---

# Title
Body. The agent reads this and follows the workflow described inside.

A skill missing name or description — or with an invalid local name — is rejected at load. And note that tools is only read in the inline tools: [Read, Edit, Bash] form; a YAML block list (one - Read per line) silently parses as no tools.

The frontmatter keeps the local name, but every runtime reference uses the canonical <app-id>:<local-name> ID — including references made by the same app. For an app with id: coding, the skill above is coding:app_creation; the slash command is /coding:app_creation, and a startChat call passes skillName: "coding:app_creation". Store listing IDs and handles do not affect this namespace.

description is the trigger condition

The description is the only part of the skill the agent sees before it decides whether to load it. It must state when to use the skill — the agent reads the descriptions of the skills on hand and loads the one whose condition matches the task.

Write the description as a "use this when…" line, not a summary of the body. The app_creation skill that ships with Rome is a good model: its description spells out exactly what kind of request should trigger it (truly app-shaped software), what should not (pipelines/workflows), and when to skip it (editing an existing app, read-only checks):

description: >-
  Scaffold a brand-new Rome app into an independent, git-versioned source
  directory and install it from there. Use for genuinely app-shaped
  software ... FIRST apply the litmus ... Skip this skill for editing an
  existing installed app or read-only inspection.

A vague description ("helps with apps") gives the agent nothing to match on; a clear one that spells out when to use it and when not to is what makes the skill load at the right moment and stay out of the way the rest of the time.

The Markdown body

Everything below the frontmatter is the set of instructions the agent follows once the skill is loaded. It is prose — a workflow, a checklist, rules that must hold, tables of common failures — written for an agent to read and act on, not for a person to skim. Keep it practical: spell out the steps to take, the order to take them in, and the mistakes to avoid. The app_creation skill, for example, walks the agent through a numbered setup flow, lists the rules it enforces, and names concrete failures with their fixes.