---
title: "Skills · Finch Agent"
description: "Developer guide to the Skill directory and discovery rules"
source: https://finchwork.app/en/docs/skills
---

# Skills

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

```text
my-skill/
└── SKILL.md
```

`SKILL.md` should include a name and description:

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

```text
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 `Skills` tool 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.