Skip to main content
A connected repository can ship its own Agent Skills: reusable instructions (and optional scripts) for a specific task, written in the standard Anthropic skill format and checked into your repo. Twill detects them automatically, surfaces them in the task composer, and the agent reads and follows a skill when your task references it. There is no setup or enabling step for discovery.
This is different from the Twill Agent Skill, which is a skill you install into your local coding agent so it can delegate work to Twill. Repository skills live in your repo and are followed by Twill’s agent.

​
What is a repository skill?

A skill is a directory containing a SKILL.md file with YAML frontmatter:
SKILL.md
---
name: deploy
description: Ship the app to production and verify the release.
---

# Deploy

1. Run the test suite and confirm it passes.
2. Run `scripts/release.sh` from this directory.
3. Verify the deployed version responds, and report the released commit.
Frontmatter keyRequiredUsed for
nameNoThe skill’s display name. Falls back to the directory name when omitted.
descriptionNoShown in the composer menu so you can tell skills apart. Recommended.
The body is free-form Markdown: the instructions the agent follows. A skill may include a scripts/ directory that the SKILL.md references; the agent runs those from the skill’s own directory. Skills live in your repository and are read live from GitHub. Twill never persists them or loads them into the agent’s built-in skill set; they are discovered on demand.

​
Where Twill looks

Twill scans every connected repository for skills in two locations:
PathLayout
.claude/skills/<name>/SKILL.mdCanonical Anthropic layout (preferred)
.agents/skills/<name>/SKILL.mdVendor-neutral layout
A repository’s tree therefore looks like: 
.claude/skills/
  deploy/
    SKILL.md
    scripts/
      release.sh
  triage-bug/
    SKILL.md
If the same skill name appears in both .claude/skills and .agents/skills within one repository, the .claude/skills copy wins and the skill is listed once. The same name defined in two different repositories is kept as two distinct entries, labeled by repo.

​
Using a skill in a task

In the task composer, type / at the start of a word to look up skills. The menu opens only when matching skills are found, or briefly while the first lookup is loading; if your connected repos contain no skills, nothing appears.
The task composer slash menu listing repository skills from a connected repo, each with its name, description, and source repository
  1. The menu lists the skills found across your connected repositories, each labeled with its name and source repo. The first lookup queries GitHub and may take a moment; a loading indicator shows while it runs.
  2. Keep typing to filter by skill name or description.
  3. Choose a skill with the arrow keys and Enter, with Tab, or by clicking. Press Esc to dismiss the menu.
Selecting a skill inserts a plain reference such as use the `deploy` skill into your message. You are not required to use the menu: writing “use the deploy skill” yourself does exactly the same thing. The menu is purely an aid for finding which skills exist and referencing one without typos.

​
How the agent uses it

When the task runs, the agent:
  1. Locates the referenced SKILL.md in the cloned repository.
  2. Reads it and follows its instructions, running any scripts/ it documents from the skill’s directory.
  3. If the same skill name exists in more than one repo, picks the one most relevant to the task and states which it chose.

​
Security

A SKILL.md is repository-authored content. The agent treats its instructions as guidance for the current task, but it continues to apply its built-in safety rules: it will not exfiltrate secrets, and it ignores any embedded directives that try to redirect it away from your actual request. Only connect repositories you trust, and review skills the same way you review any code in your repo.