# Skills (/cli/resource/skill)



A **skill** is a `SKILL.md` instruction bundle in the standard [Agent Skills](https://agentskills.io) format. It is not executed: agents load it as context to learn how to do a kind of work — your email conventions, a report format, a triage procedure. The bundle is portable to any Agent Skills host, so a skill you author here also works elsewhere (and a skill folder from elsewhere publishes here unchanged).

Reach for a skill when you want to teach agents a repeatable method, not schedule work. For something that runs on a trigger, use a [code](/cli/resource/code) or [agent workflow](/cli/resource/agent).

## How it's used [#how-its-used]

Published skills are offered to the platform's agents (the home chat, the workflow and app authoring agents, and the CRM chat), which load one by name when its description matches the task. A skill is offered only while it is both **valid** (last publish passed the spec) and **enabled** (the toggle on its dashboard page). Users can also @-mention a skill in chat to inline its instructions directly.

<Callout type="info" title="Not `geni skills`">
  `geni skills` (plural) is unrelated: it installs the local instruction files
  that teach YOUR coding agent how to use this CLI. Cloud skill resources live
  under `geni resource`.
</Callout>

## Project layout [#project-layout]

```
SKILL.md        the manifest: YAML frontmatter + the instructions body
scripts/        optional runnable code the loading agent executes as-is
references/     optional long detail read only when the agent needs depth
assets/         optional templates and files used in the output
```

`SKILL.md` must sit at the bundle root, and the bundle must contain exactly one. Everything else is optional.

## SKILL.md format [#skillmd-format]

```markdown
---
name: gmail-inbox-triage
description: Triage a Gmail inbox: label, archive, and draft replies following the user's conventions. Use when the user asks to process, clean up, or respond to email.
---

# Gmail Inbox Triage

Step-by-step instructions, examples, and edge cases the loading agent follows.
```

Frontmatter contract (validated on publish):

| Field         | Rules                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | Required. Lowercase letters, numbers, and single hyphens; 64 chars max. The load key — it syncs to the skill's name on publish. |
| `description` | Required, 1024 chars max. The ONLY thing agents see before deciding to load, so say what the skill does AND when to use it.     |

The body below the frontmatter must be non-empty.

Rules:

* **Link supporting files with standard Markdown links** (`[the export script](scripts/export.py)`). Every linked path under `scripts/`, `references/`, or `assets/` must exist in the bundle — a dangling link fails validation.
* **Progressive disclosure.** Keep the body to a few hundred lines of "what to do and when". A long program belongs in `scripts/` with a one-line instruction to run it; a big reference table belongs in `references/` with a link.

## The build loop [#the-build-loop]

```sh
geni resource create --type skill --name "Gmail Inbox Triage"
# edit SKILL.md (and scripts/, references/, assets/)
geni resource validate
geni resource publish
```

Skills skip the config step — no credentials, consts, or schedules to wire — and [`publish`](/cli/resource/publish) needs no `--summary`. Each successful publish syncs the name and description from the frontmatter and snapshots a version you can revert to from the dashboard. [`pull`](/cli/resource/pull) brings a skill's live bundle to disk by its `skl_` id, including any binary assets (bundle bytes ride the same tar transport as workflows and apps).

Read the machine contract with [`geni skills load skill-authoring`](/cli/skills/load) — for this type the short contract is inline in the loaded `SKILL.md`.