> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

A skill is a folder in your repository that teaches Capy a repeatable workflow: deploy steps, a release checklist, how to run your visual regression suite. Capy sees every skill's name and description in every thread, and reads the full instructions only when the task calls for it, so skills carry detail that would be wasteful to load all the time.

## Where skills live and how they load

Skills live under `.agents/skills/` (preferred) or `.claude/skills/` (supported for compatibility), one folder per skill, each with a `SKILL.md` at its root. When both roots define the same skill name, `.agents/skills/` wins; across a multi-repo project, the first repo in the project's repo order owns a contested name.

Loading is read-based: the agent's context always carries the list of available skills (each skill's name, description, and the on-machine path of its `SKILL.md`), and the agent opens the file with its ordinary read tools when the description matches the task. There is no activation step and no permission gate; a skill is exactly as discoverable as its description makes it.

Skill lists share one context budget with your `AGENTS.md` instructions. When the budget overflows, skills degrade without disappearing: descriptions shorten, then empty out, each state with a visible marker, but every skill's name and location always renders, so the agent can still find and read it.

## The SKILL.md contract

The frontmatter is required, and a `SKILL.md` without `name` and `description` is skipped silently, which is the most common reason a skill "doesn't work":

```markdown theme={null}
---
name: deploy
description: Deploy the application to staging or production. Use when asked to deploy, release, or push to an environment.
---

# Deploy skill

## Steps

1. Run `scripts/deploy.sh <environment>`
2. Verify the deployment at the environment URL
3. Report success or failure

## When not to use

- Local development or testing; run the dev server instead.
```

Write the description as the trigger: it's the only part the agent sees before deciding to read the file, so "Use when asked to deploy, release, or push to an environment" beats "Deployment documentation."

Beside `SKILL.md`, a skill folder can carry whatever the workflow needs, conventionally `scripts/` (executables the instructions invoke), `references/` (longer material the instructions point into), and `assets/`:

<Tree>
  <Tree.Folder name=".agents" defaultOpen>
    <Tree.Folder name="skills" defaultOpen>
      <Tree.Folder name="deploy" defaultOpen>
        <Tree.File name="SKILL.md" />

        <Tree.Folder name="scripts" />

        <Tree.Folder name="references" />

        <Tree.Folder name="assets" />
      </Tree.Folder>
    </Tree.Folder>
  </Tree.Folder>
</Tree>

## Skill or AGENTS.md?

Both are repo-carried context; the difference is when they load. [`AGENTS.md`](/instructions) is always in context, so put rules there that apply to most work in the repo: style, verification commands, conventions. A skill loads on demand, so put workflows there that are long, specific, and occasional. A 40-line deploy procedure in `AGENTS.md` taxes every thread; as a skill it costs one list entry until someone actually deploys.

Skills are discovered from the repository like any other file, so they version with your code: a branch can change a skill, and the agent working that branch sees the branch's version. You can write skills by hand or ask Capy to scaffold one: describe the workflow and where it should live.