# Skills URL: /docs/building-apps/capabilities/skills Markdown: /docs/building-apps/capabilities/skills.md Description: Ship plain-language skills an agent loads when it needs them. 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](/docs/building-apps/capabilities/hooks). ## Writing skills [#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: ```yaml skills: - skills/app_creation ``` The layout is one folder per skill: ``` src/skills//SKILL.md ``` ### SKILL.md frontmatter [#skillmd-frontmatter] A `SKILL.md` is YAML frontmatter followed by a Markdown body: ```markdown --- 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. ``` | Field | Purpose | | ------------- | --------------------------------------------------------------------------------------------------------------------- | | `name` | Required local name. It must match `/^[a-z][a-z0-9_-]{0,63}$/`, contain no `:`, and can look like `story_authoring`. | | `description` | Required. One sentence stating **when** the agent should load the skill — see below. | | `tools` | The built-in tools the skill expects to use (e.g. `Read`, `Edit`, `Bash`). Must be the inline array form shown above. | 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 `:` 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 [#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): ```yaml 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 [#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.