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.
Composer skill picker with available skillsComposer skill picker with available skills
Name a skill in your message to use it explicitly.

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.

SkillWhat it does
artifactHands back a file with a share link when you ask for one.
capy-setupSets up, repairs, or audits your project's setup, testing each command on a machine before saving it.
find-mcp-serverFinds an MCP server or plugin for a service and proposes it for you to approve.
gh-stackSplits a large change into stacked pull requests with gh stack.
make-a-deck, make-a-page, make-a-prototypeBuild a slide deck, a document page, or a clickable prototype as one HTML file.
paperRules for design work in Paper.
spreadsheetsReads, 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.

ScopeAvailable to
OrganizationEveryone's threads, in all projects
ProjectEveryone's threads in one project
PersonalYour threads, in all projects
Project + personalYour 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.

New skill form in DriveNew skill form in Drive
Drive skills share reusable workflows outside git.

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:

Markdown
---
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 URL

Before 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.
Open in Capy