> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seriora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Named procedures that run in the session's own context, and the ones seri proposes.

A skill is a procedure rather than a role. It is a named set of instructions that runs in the
session's own context, on the session's model, with the session's tools. That is the difference
from a [subagent](/guides/subagents), which gets a context of its own.

## Writing one

Put it at `.seri/skills/<name>/SKILL.md` for this project, or under your profile root for every
project.

```markdown theme={null}
---
name: regression-sweep          # optional. The directory name is the default.
description: Reproduce a bug, write the failing test, then fix it.
argument-hint: "<bug description>"
disable-model-invocation: true  # optional. Only you can run it, never the model.
---

Fix this bug: $ARGUMENTS

1. Reproduce it and record the exact steps.
2. Write the failing test first.
3. Fix it, then run the suite.
```

The **directory** names the skill, not the filename. Every file in the tree is called `SKILL.md`,
so the filename could never have carried the name.

## Running one

**You run it.** Type `/` and the name. The completion list shows every command, agent and skill
with what each one does, so you do not have to remember exact names.

**The model runs it.** Your `description` is what it reads to decide when a task calls for this
procedure.

## Arguments

| Token        | Substitutes                               |
| ------------ | ----------------------------------------- |
| `$ARGUMENTS` | everything you typed after the name       |
| `$0` … `$9`  | the individual whitespace-separated words |

Substitution is a single pass, so a word that itself looks like `$1` is not re-scanned.

`argument-hint` is the usage line shown in the completion list. A YAML list under `arguments:`
does the same job, rendered as `<mode> <prompt>`, and `argument-hint` wins when a file sets both.
Neither one binds a name to a position. Substitution is positional either way, so the names buy
you a usage line and nothing more.

## What a skill costs

**A skill's instructions are never in the prompt.** Session start pays for the name, the
description and the argument hint. The body stays on disk until the skill actually fires, so a
directory of twenty skills costs twenty descriptions rather than twenty procedures.

`disable-model-invocation: true` keeps a skill out of the prompt and out of the model's reach
entirely, leaving `/name` as its only entry point.

## Keys that are accepted and ignored

`allowed-tools`, `model` and `context` are part of the Cursor format. seri accepts them and warns
at startup naming the file, rather than silently honouring them. A skill runs in the parent's
context, on the parent's model, with the parent's tools, so a file reading `allowed-tools: Read`
would otherwise leave you believing the skill is restricted when it is not.

The format is Cursor's, so existing `SKILL.md` files work when you copy them in. seri does not
read `.cursor/skills/` itself, for the same reason it does not read `.cursor/agents/`.

## The one artifact seri writes for you

After hard-won work, the archivist can propose a skill. It is staged, never applied.

| Command                | Does                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------ |
| `/skills`              | open the panel: every skill this session loaded, where each file lives, who wrote it |
| `/skills pending`      | list what is waiting for review                                                      |
| `/skills diff <id>`    | show the exact file that would be written                                            |
| `/skills approve <id>` | write it                                                                             |
| `/skills reject <id>`  | throw it away                                                                        |

`<id>` also accepts `all`. An approved file carries `author: archivist` and the reason it was
proposed, so you can always tell which of your skills you wrote and which one seri did.

## A name that is both

If a skill and an agent share a name, `/name` runs the agent and seri warns at startup. The skill
is still reachable through the skill tool. The collision is reported rather than refused, because
neither loader can see the other.