---
type: reference
title: Skills CLI Skill Discovery
description: How the skills CLI discovers SKILL.md files in repositories — flat layout, catalog layout, plugin manifests.
tags:
  - unverified
  - skills
  - discovery
  - repository
timestamp: 2026-07-18
verified: 2026-08-28
---

# Skill Discovery

The CLI searches for skills in these locations within a repository. Each skill container directory is walked:

- **One level deep** for the common flat layout: `skills/<name>/SKILL.md`
- **One extra level deep** for catalog layouts: `skills/<category>/<name>/SKILL.md`

A `SKILL.md` discovered at the shallower level shadows anything nested below it. Use `--full-depth` to also discover `SKILL.md` files outside these container directories.

## Standard Discovery Locations

- `SKILL.md` in root directory (if present)
- `skills/`
- `skills/.curated/`
- `skills/.experimental/`
- `skills/.system/`
- `.agents/skills/`
- `.claude/skills/`
- `.goose/skills/`
- `.openhands/skills/`
- `.pi/skills/`
- And many more per-agent directories (see [Agent Support](/tools/vercel-labs-skills/agent-support.md))

## Plugin Manifest Discovery

If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered. This enables compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem.

Example `marketplace.json`:

```json
{
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "my-plugin",
      "skills": ["./skills/review", "./skills/test"]
    }
  ]
}
```

Skill paths declared in a manifest are searched at their declared depth.

If no skills are found in standard locations, a **recursive search** is performed as a fallback.

## Related

* [SKILL.md Format](/tools/vercel-labs-skills/skill-format.md) — What a discovered skill looks like
* [Commands](/tools/vercel-labs-skills/commands.md) — add and use commands