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.

# 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

1. A global instruction file

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

2. One project instruction file

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

3. 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:

{
  "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.

---
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

{
  "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 covers the instructions and skills blocks, Agents & subagents covers per-agent prompts, and Skills and Project instructions cover the editor’s equivalents.