# Skills

A skill is how to do a kind of work, written once and read only when it applies. It
is a folder in the open [Agent Skills](https://agentskills.io/specification) format:

```
skills/
└─ refunds/
   ├─ SKILL.md
   └─ references/policy.md
```

```md
---
name: refunds
description: How to decide and issue a refund. Use when a customer asks for money back.
---

1. Look the order up before anything else.
2. …
```

Each agent's instructions list every skill's name and description. The body is read
through a `read_skill` tool when the agent decides the skill applies, and the other
files in the folder the same way, by path. `skills: ["refunds"]` on an agent narrows
what it sees; `skills: false` gives it none. `allowed-tools` is read and not
enforced.

These are different from the [skills an agent works out for itself](#what-an-agent-remembers):
those are proposed from its traces and wait for a person to accept them.

## Skills and plugins from a registry

A registry is an index anyone can host, in the Agent Skills discovery format
(`/.well-known/agent-skills/index.json`). An app lists the ones it reads:

```ts
export default defineConfig({ registries: ["https://skills.example"] });
```

```sh
praecise search refunds      # look through the registries for skills and plugins
praecise add refunds --show  # fetch and print a skill without installing it
praecise add refunds         # install it
```

A skill is fetched over `https`, checked against the digest the index gives, and
written to `skills/<name>/` with nothing marked executable. A plugin is not
fetched: it is recorded in `praecise.plugins.json` and the command to install it
is printed. `--kind skill` or `--kind plugin` says which, where a registry lists
both under one name. Nothing is read from a registry unless one of the two
commands is run, and there is no default registry.

An app serves its own skills to MCP clients as well: `skills/list`, `skills/get`
and `skill://<name>/<path>` resources. A skill whose front matter says
`metadata: { access: internal }` is not served.
