> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twill.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository skills

> Teach Twill your team's procedures with SKILL.md files that live in your repos.

A skill is a procedure the agent can follow — "how we deploy", "how to add an API endpoint", "how to write a migration" — written as Markdown in your repo. Twill discovers skills across all connected repos and uses them when tasks call for them.

## Writing a skill

A skill is a directory containing a `SKILL.md`:

```markdown .claude/skills/deploy/SKILL.md theme={"theme":"github-dark"}
---
name: deploy
description: Deploy a service to staging and verify it's healthy
---

1. Run `make build SERVICE=<name>`.
2. Push the image: `make push SERVICE=<name>`.
3. Apply with `kubectl apply -f k8s/<name>/staging/`.
4. Verify: `curl https://staging.example.com/<name>/health` returns 200.
```

* `name` is optional (falls back to the directory name); `description` is recommended — it's how the agent decides when the skill applies.
* The body is free-form Markdown. Add a `scripts/` directory alongside for helper scripts.

## Where skills live

| Location                         | Notes                      |
| -------------------------------- | -------------------------- |
| `.claude/skills/<name>/SKILL.md` | Canonical, preferred       |
| `.agents/skills/<name>/SKILL.md` | Vendor-neutral alternative |

If both define the same name in one repo, `.claude/skills` wins. The same name in different repos yields two entries, labeled by repo. Skills are read live from GitHub at task time — nothing to sync.

## Using skills

Type `/` in the task composer to browse and insert a skill reference:

<Frame>
  <img src="https://mintcdn.com/twill/_EquMIMkAlREVsPX/images/repository-skills-slash-menu.png?fit=max&auto=format&n=_EquMIMkAlREVsPX&q=85&s=fc845bea1e62315d35823eb2e2df3d1f" alt="The composer's slash menu listing repository skills" width="632" height="506" data-path="images/repository-skills-slash-menu.png" />
</Frame>

Agents also find and follow skills on their own when a task matches a skill's description.

<Note>
  Repository skills teach Twill's agents procedures in *your* codebase. The
  [Twill agent skill](/local-agents) is the inverse — it teaches your local
  agent to delegate to Twill.
</Note>