# Skills

## What a skill contains

A skill is a named set of instructions for a repeatable task. V3Code reads a Markdown
body and a small frontmatter block. A skill guides the agent; it does not install new
tools, grant permissions, or guarantee that its instructions will be followed.

## Add a project skill

Create `.v3code/skills/review-change/SKILL.md` in your workspace:

```markdown
---
name: review-change
description: Review a proposed change for correctness and missing tests.
keywords:
  - review
globs:
  - "**/*.ts"
---
Read the relevant source and diff before making claims.
Identify behavior changes and edge cases.
Report findings with file references and a suggested verification step.
Do not change files unless asked.
```

Keep the body concrete. Explain inputs, expected outputs, checks, and stopping conditions.
Do not include secrets.

## Where skills come from

Skills load from bundled product skills, then `~/.v3code/skills`, then workspace
`.v3code/skills`. A later skill with the same name overrides an earlier one.
The loader also checks immediate child folders for workspace skill directories.
It accepts skill folders containing `SKILL.md` and individual `.md` or `.mdc` files.

## Supported metadata

| Field             | Purpose                                                   |
| ----------------- | --------------------------------------------------------- |
| `name`            | Skill name; filename or folder name is the fallback       |
| `description`     | Short task description for the catalog                    |
| `globs` or `glob` | File-pattern triggers                                     |
| `keywords`        | Keyword triggers                                          |
| `alwaysApply`     | Request always-active instructions                        |
| `loadOnDemand`    | Use a pointer so the full skill can be loaded when needed |
| `catalog: false`  | Omit from the visible skill catalog                       |

Ask the agent to use the skill by name and verify that it loaded the expected
instructions. The native agent has a `read_skill` tool for retrieving a skill by name;
bundled skills are not necessarily accessible as workspace files.

## Troubleshooting

Check the folder location, frontmatter, non-empty body, and duplicate names. The loader
caches skills, so newly created files may not appear immediately. Reopen the editor if
necessary. An ACP agent may use its own skill discovery instead of V3Code's native catalog.

See [Project instructions](/editor/project-instructions) for rules that apply across tasks.