Skip to main content
A skill is a folder that defines a reusable workflow: a SKILL.md with instructions, plus any scripts or reference files the workflow needs. Capy sees every available skill’s name and description, then reads the full instructions when a request matches. Skills come from three places:

​
Built-in skills

Built-in skills are available in every thread with nothing to install, and Capy reads one when your request matches it. To use one on purpose, name it in your message: “use gh-stack to split this into stacked PRs”. Built-in skills update with Capy itself, so they stay current without any action from you.

​
Repository skills

Repository skills live under .agents/skills/ (preferred) or .claude/skills/ (supported for compatibility), one folder per skill, each with a SKILL.md at its root. They version with your code, go through review like any other change, and work in other agents that read the same folders.
Create a deploy skill in .agents/skills from the steps in our release runbook.

​
Drive skills

Drive skills live at skills/<name>/SKILL.md in a Drive scope. They skip git, so they suit workflows that span repositories or don’t belong in a codebase. The scope decides who gets the skill: Open More → Drive, pick a scope, and choose New skill, or ask Capy:
Create a release-checklist skill in our organization drive from the release procedure we agreed on.

​
Install a published skill

Skills published in the Agent Skills format install with the skills CLI. Run it in your repository and commit the result, and Capy picks the skill up from .agents/skills/:
To install into Drive instead, give Capy the repository and the scope:
Install the banger-video skill from scrapybara/agent-skills into our organization drive.

​
When two skills share a name

A name is used once. When the same name appears in more than one place, Capy loads the first match in this order:
  1. Repository: .agents/skills/ before .claude/skills/, and across a multi-repo project, the first repo in the project’s repo order.
  2. Drive, nearest scope first: Project + personal, Personal, Project, then Organization.
  3. Built in.
So a repository or Drive skill named like a built-in replaces it, and a Project + personal skill overrides a team-wide one while you try out a change. Skills with different names all appear, and Capy picks the one whose description best matches the task.

​
How skills load

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

Repository skills require name and description in frontmatter. Drive skills use the folder name and accept missing fields, but descriptions help Capy select the workflow. Include both fields for portability:
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?

Root AGENTS.md supplies standing rules; skills load on demand for specific workflows. Both can live in repositories or Drive. Repository skills version with the code. Drive skills persist outside git for threads in their scope. Ask Capy to create a skill by describing the workflow and where it should live.