# Skills & instructions

There are two ways to give the agent knowledge it wouldn't otherwise have. **Instructions** are always loaded and describe your project. **Skills** sit on the shelf until a task needs them.

## Instructions — always on

Put an `AGENTS.md` at the root of your repository. It's read at the start of every session, so it's the right home for conventions that always apply: how to run the tests, which patterns to follow, what never to touch.

```markdown
# Project notes

- Run tests with `npm test -w @app/api`. Never use `--force`.
- Database migrations are generated, not hand-edited.
- All API responses go through `packages/http/envelope.ts`.
```

### What gets loaded, in order

### A global instruction file

An `AGENTS.md` in your config directory, or `~/.claude/CLAUDE.md`. The first one found is used.

### One project instruction file

`AGENTS.md`, then `CLAUDE.md`, then the deprecated `CONTEXT.md` — searched from your current directory up to the worktree root.

### Anything you listed in config

Every entry under `instructions`.

> Note:
>
> **Only the first project-level match is used.** V3Code doesn't stack an `AGENTS.md` from every folder up the tree, so instructions can't quietly accumulate as you move around a monorepo.

The `instructions` array accepts relative paths, absolute paths, globs, `~/` paths, and `https://` URLs:

```jsonc
{
  "instructions": [
    "./docs/conventions.md",
    "./packages/*/AGENTS.md",
    "~/notes/my-style.md",
  ],
}
```

> Tip:
>
> Keep instructions short and specific. A long document competes for the same context as your actual code — a page of real constraints beats ten pages of general advice.

## Skills — loaded when relevant

A skill is a folder with a `SKILL.md` inside it. The agent sees every skill's *name and description* all the time, but only pulls the full contents in when a task actually matches — so you can keep a deep library without flooding the context.

```markdown
---
name: release-checklist
description: >
  Use when cutting a release: version bumps, changelog entries,
  tagging, and the publish order across packages.
---

## Steps

1. Confirm `main` is green.
2. Bump versions with `npm run version`.
...
```

The folder can hold more than the one file — scripts, templates, reference documents. The instructions can point at them by relative path, and the agent can open them.

### Where skills come from

| Location                                    | Scope                                           |
| ------------------------------------------- | ----------------------------------------------- |
| `skill/` or `skills/` in a config directory | Global or project, depending on which directory |
| `~/.claude/skills/**/SKILL.md`              | Skills you already wrote for Claude Code        |
| `.agents/skills/**/SKILL.md`                | A shared convention, global or per project      |
| `skills.paths` in config                    | Any extra folders you name                      |
| `skills.urls` in config                     | Downloaded from a URL and cached                |

```jsonc
{
  "skills": {
    "paths": ["./tooling/skills", "~/skills"],
    "urls": ["https://example.com/.well-known/skills/"],
  },
}
```

A skill URL must serve an `index.json` listing each skill and its files. Entries without a `SKILL.md` are skipped with a warning, and a `version` field lets V3Code re-download only what changed. Downloads are cached under `~/.cache/v3code/skills/`.

> Note:
>
> Skills you wrote for Claude Code load as they are — there's nothing to convert. Set `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1` if you'd rather V3Code ignored them, or `OPENCODE_DISABLE_EXTERNAL_SKILLS=1` to skip both external folders. These two runtime flags read the `OPENCODE_` name specifically — the `V3CODE_` alias doesn't apply to them.

### Using them

Mostly you don't have to do anything: the agent picks a skill when the task matches its description, which is why the description matters more than the title. You can also just ask — "use the release-checklist skill."

That makes description-writing the real craft here. Write it as *when to use this*, not *what this is*: "Use when cutting a release" gets matched; "Release documentation" doesn't.

## Which one should you use?

### Use instructions

Facts that are true for every task in this repository — commands, conventions, hard rules.

### Use a skill

A procedure for a specific kind of job that only comes up sometimes — releases, migrations, incident response.

If it would be noise on an unrelated task, it belongs in a skill.

## Related

[Configuration](/terminal/configuration) covers the `instructions` and `skills` blocks, [Agents & subagents](/terminal/agents) covers per-agent prompts, and [Skills](/editor/skills) and [Project instructions](/editor/project-instructions) cover the editor's equivalents.