Skip to main content
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”:
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/:
.agents
skills
deploy
SKILL.md
scripts
references
assets

​
Skill or AGENTS.md?

Both are repo-carried context; the difference is when they load. AGENTS.md 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.