> ## 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 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: | Source | Where it lives | Available to | | - | - | - | | [Built in](#built-in-skills) | Ships with Capy | Every thread | | [Repository](#repository-skills) | `.agents/skills/` in your repo, committed to git | Threads on that repo's project | | [Drive](#drive-skills) | `skills/` in a [Drive](/drive) scope, outside git | Threads in that scope | ## 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". | Skill | What it does | Ask for it with | | - | - | - | | `capy-setup` | Sets up, repairs, or audits your project's [environment](/environment), testing each command on a machine before saving it. | "Set up this repo so tests run" | | `computer-use` | Guides Capy when it controls desktop apps on a cloud machine or on your own Mac. | "Open the report in Numbers and export it as PDF" | | `gh-stack` | Splits large changes into a stack of small, dependent pull requests with the `gh stack` GitHub CLI extension. | "Split this into stacked PRs" | | `greptile-migrate` | Moves your explicit review rules and referenced files from Greptile into [Capy Review](/review). | "Migrate our Greptile rules" | | `paper` | Rules for design work in Paper, such as building editable designs rather than pasted screenshots. | "Design the settings page in Paper" | 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//SKILL.md` in a [Drive](/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: | Scope | Skill is available to | | - | - | | Organization | Everyone's threads, across all projects | | Project | Everyone's threads in one project | | Personal | Your threads, across all projects | | Project + personal | Your threads in one project | 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](https://skills.sh/) format install with the `skills` CLI. Run it in your repository and commit the result, and Capy picks the skill up from `.agents/skills/`: ```bash theme={null} npx skills add / --skill --agent universal ``` 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: ```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 ` 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/`: ## Skill or AGENTS.md? Root [`AGENTS.md`](/instructions) 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.