A Skill is a Markdown-based guide package rooted at a SKILL.md file, giving Finch reusable task instructions, references, templates, or scripts. It needs no compilation — this page covers where developers place skills and how Finch discovers them.
Where to put them
Finch scans the following directories for skills:
| Level | Path | Use case |
|---|---|---|
| Current project / Space | <cwd>/.finch/skills/<skill-name>/SKILL.md | Skills specific to the current project or a directory-bound Space |
| Finch home directory | <finchHomeDir>/.finch/skills/<skill-name>/SKILL.md | Personal skills reused across projects |
| Global | ~/.finch/skills/<skill-name>/SKILL.md | Base skills available to every Finch workspace |
The dev-build global directory is ~/.finch-dev/skills/. In general, prefer putting project-specific skills under the current directory's .finch/skills/.
Minimal structure
my-skill/
└── SKILL.md
SKILL.md should include a name and description:
---
name: my-skill
description: What this skill does and when it should be used.
---
# My Skill
## Usage
When the user needs to ..., follow these steps.
Scripts, references, and templates can live alongside it under scripts/, references/, and assets/ in the same directory.
Discovery and priority
Skills with the same name are resolved by priority:
Current Space / authorized directory > current working directory > Finch home directory > global directory
If the highest-priority skill with a given name is disabled, Finch does not fall back to a lower-priority version with the same name.
Finch does not watch the filesystem continuously. The directories above are rescanned when:
- The
Skillstool is called - Skill search is opened in the Composer
- The skills list is opened in the toolbox
- A skill is enabled or disabled in settings or the toolbox
After adding a skill to one of these directories, reopen Composer skill search or the toolbox to confirm it was discovered.