---
title: Skills
description: Author load-on-demand procedures the model pulls into context with eve__skill.
url: "https://eve.dev/docs/skills"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

A skill is a procedure the model reads only when a task needs it, instead of carrying it on every turn. Each skill lives under `agent/skills/` as a markdown file, or as a directory with a `SKILL.md` and supporting files. Skills follow the Agent Skills standard, so a skill written for another Agent Skills client works as-is.

## Markdown vs `defineSkill`

The smallest skill is a flat markdown file whose content is the procedure:

```text
agent/skills/
├── forecast.md               # flat skill: description is optional
└── research/
    ├── SKILL.md              # packaged skill: description is required
    └── references/
        └── checklist.md      # supporting file
```

```md title="agent/skills/forecast.md"
Use the weather tool before answering forecast or temperature questions.
```

A skill's name comes from its path: `agent/skills/forecast.md` is `forecast`, and `agent/skills/research/SKILL.md` is `research`. A name uses only ASCII letters, digits, underscores, and dashes. It starts with a letter or digit and has at most 64 characters. The build fails on any other name.

A packaged skill is a directory with a `SKILL.md` and sibling files such as `references/`, `assets/`, and `scripts/`:

```md title="agent/skills/research/SKILL.md"
---
description: Research unfamiliar topics before answering with confidence.
---

When the task is novel or ambiguous, gather evidence first, then answer with the
key facts and the remaining uncertainty.
```

Use `defineSkill` from `eve/skills` when markdown can't express what you need, such as typed values, generated content, or inline sibling files:

```ts title="agent/skills/research.ts"
import { defineSkill } from "eve/skills";

export default defineSkill({
  description: "Research unfamiliar topics before answering with confidence.", // required
  content:
    "When the task is novel or ambiguous, gather evidence first, then answer with the key facts and the remaining uncertainty.",
  // optional: each key becomes a file next to the generated SKILL.md
  files: {
    "references/checklist.md": "# Checklist\n\n- Find primary sources.\n",
  },
});
```

eve generates `SKILL.md` from `content`. A static `defineSkill` module runs once at build time, and a dynamic skill module also runs at runtime. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).

| Field         | Where                        | Default                                          |
| ------------- | ---------------------------- | ------------------------------------------------ |
| `description` | Frontmatter or `defineSkill` | Required, except in a flat markdown skill        |
| `deferred`    | Frontmatter or `defineSkill` | `false`; see [Deferred skills](#deferred-skills) |
| `license`     | Frontmatter or `defineSkill` | Unset                                            |
| `metadata`    | Frontmatter or `defineSkill` | Unset; values must be strings                    |
| `content`     | `defineSkill`                | Required; the markdown body in a file            |
| `files`       | `defineSkill`                | None                                             |

eve ignores other frontmatter, so skills written for other Agent Skills clients import unchanged.

A flat markdown skill without `description` uses the body's first non-empty line that isn't a code fence marker. eve strips any leading `#`, `>`, `*`, or `-` marker from that line. A body with no such line gives `Instructions for the <name> skill.`, which is a weak hint. Add a `description` when the model must choose the skill by intent.

## How loading works

eve lists each skill's name and description in the system prompt. When a request matches a description, or names the skill, the model loads it with `eve__skill({ name })`. The skill's markdown becomes that call's result in the current turn.

An agent with skills always has the [`eve__skill` tool](./concepts/built-in-tools#eve__search-eve__tool-and-eve__skill). Each load reports a `load-skill` action named for the skill, and `t.calledSkill` asserts it in [evals](./evals/assertions).

The description tells the model when to load the skill. Write it as the task that should trigger it:

```md
Use when the user needs a release checklist or changelog workflow.
```

Loading a skill adds instructions, never tools. Tools stay visible whether or not a skill is loaded.

## Supporting files

Supporting files are for the model. It reads a loaded skill's references, assets, and scripts with sandbox tools such as `read_file` and `bash`.

The files are under `$HOME/.agents/skills/<skill>/` in the sandbox. When `$HOME` is unavailable, they are under `skills/<skill>/` in the workspace root. A relative path inside `SKILL.md`, such as `references/checklist.md`, starts from the directory that holds that `SKILL.md`.

Listing and loading skills don't need a sandbox. Only reading supporting files does.

Tools and hooks have no API to read skill files. When your code needs the same data, import it from a module in `lib/`.

## Skills are scoped per agent

A skill belongs to the agent that declares it. A [subagent](./subagents) and the root agent can't see each other's `skills/`. To share one skill across agents, package it in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount that extension in each agent. Put shared executable helpers in `lib/`.

## Deferred skills

A deferred skill stays out of the system prompt, which helps an agent with many skills. Set `deferred: true` in the frontmatter or on `defineSkill`:

```md title="agent/skills/pdf-forms/SKILL.md"
---
description: Fill and validate PDF forms.
deferred: true
---
```

The system prompt says only that deferred skills exist, and lists their namespaces. The model finds a deferred skill with `eve__search`, which searches skills and tools together, and loads it with `eve__skill({ name })`. After that, the skill works like any other skill.

## Dynamic skills

To serve a different skill per user, tenant, or channel, wrap `defineSkill` in `defineDynamic`. Read the value it depends on, such as the caller's team, from `ctx.session.auth`. Dynamic skills accept `deferred` too. See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-skills).

A parent agent keeps its dynamic skills when it resumes after delegating to a subagent.

## Find and install community skills

`eve registry search` includes [skills.sh](https://skills.sh) as the built-in `@skills` source. Search by task, review the source, then install the skill into your project:

```bash
eve registry search react --registry @skills
eve add @skills/vercel-labs/agent-skills/vercel-react-best-practices
```

skills.sh skills are written by the community and become files in your project. Review their source and the resulting diff before you run the agent. See [Install integrations](./install-integrations#add-a-skill) for registry configuration and install behavior.

## What to read next

Use [instructions](./instructions) for rules the model needs on every turn, and a [tool](./tools) when the model needs typed code that runs.

- [Connections](./connections): add tools from external MCP and OpenAPI servers
- [Dynamic capabilities](./guides/dynamic-capabilities): choose skills per caller with `defineDynamic`
- [Context control](./concepts/context-control): how skills fit the full context model

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)