Repository skills

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:

.claude/skills/deploy/SKILL.md

---
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:

The composer's slash menu listing repository skills

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

Repository skills teach Twill’s agents procedures in your codebase. The Twill agent skill is the inverse — it teaches your local agent to delegate to Twill.

How Twill worksThe architecture: real CLI agents, specialized sub-agents, and self-verification against a running app.

​Writing a skill

​Where skills live

​Using skills

Writing a skill

Where skills live

Using skills