Skills
A skill is a reusable workflow, such as a deploy procedure or a release checklist, that Capy follows when your request matches. Capy sees each skill's name and description, and reads the full instructions when it needs them.
Use a skill
To use a skill on purpose, name it in the message box:
$lists skills and filters by name, like$deploy./offers Skills and filters by name, like/dep.@offers Skills.


Outside the app, such as in Slack, type the name with a $ in front. You can also ask in plain words, like "use gh-stack to split this into stacked PRs".
Skill sources
Built-in skills
Built-in skills work in every thread and update with Capy.
| Skill | What it does |
|---|---|
artifact | Hands back a file with a share link when you ask for one. |
capy-setup | Sets up, repairs, or audits your project's setup, testing each command on a machine before saving it. |
find-mcp-server | Finds an MCP server or plugin for a service and proposes it for you to approve. |
gh-stack | Splits a large change into stacked pull requests with gh stack. |
make-a-deck, make-a-page, make-a-prototype | Build a slide deck, a document page, or a clickable prototype as one HTML file. |
paper | Rules for design work in Paper. |
spreadsheets | Reads, checks, and writes Excel and OpenDocument workbooks. |
Repository skills
Put a repository skill in .agents/skills/<name>/ or .claude/skills/<name>/ at the repository root. Capy prefers .agents/skills/. It versions with your code and works in other agents that read these folders.
Capy reads repository skills from the branch the thread starts from. Threads you start after you push a new skill to that branch see it, and running threads don't. In a thread on your own computer, Capy reads them from your disk.
Create a deploy skill in .agents/skills from the steps in our release runbook.
To reuse skills from Claude Code or Cursor, copy the folders into .agents/skills/ and commit them. Install skills from the skills CLI into the same folder. Copied skills don't update on their own, so copy them again to get a new version.
Drive skills
A Drive skill lives at skills/<name>/SKILL.md in a Drive scope, outside git. Use Drive for skills your whole organization needs, or for workflows that span repositories.
| Scope | Available to |
|---|---|
| Organization | Everyone's threads, in all projects |
| Project | Everyone's threads in one project |
| Personal | Your threads, in all projects |
| Project + personal | Your threads in one project |
Drive has New skill for each scope. You can also ask Capy:
Install the skills from github.com/acme/agent-skills into our organization drive.


Plugin skills
A plugin can carry skills. They work in threads on cloud machines where the plugin is available, and the plugin page lists them under Skills. Sync updates a GitHub plugin's skills.
The SKILL.md file
Each skill is a folder with a SKILL.md. The file starts with frontmatter that has a name and a description:
---
name: deploy
description: Deploy the application to staging or production. Use when asked to deploy, release, or push to an environment.
---
1. Run `scripts/deploy.sh <environment>`
2. Verify the deployment at the environment URLBefore Capy opens the file, it sees only the name and the description. Start the description with when to use the skill, like "Use when asked to deploy".
A repository skill needs both fields, or Capy skips it without an error. Plugin skills need a description and take their name from the folder. Drive skills also take their name from the folder. A Drive skill without a description loads, but Capy can't tell when to use it.
The folder can also hold scripts/, references/, and assets/. For rules that apply to every task, use AGENTS.md instead.
Good to know
- To see which skills Capy found, type
$in the message box. The list shows the selected project's skills. - Capy doesn't read skills from other folders, such as
.capy/,.cursor/, or.devin/, or from a skills folder below the repository root. - When two skills share a name, Capy uses the first match in this order: repository, then Drive, then built in, then plugin.
- In a project with several repositories, Capy lists the first repository's skills from the start, and adds another repository's skills when it first works there.