# How to Use the `--full-depth` Flag for Recursive Skill Discovery in the Skills CLI

> Master recursive skill discovery with the Skills CLI full-depth flag. Learn how to find all SKILL.md files in any subdirectory, even with existing root files.

- Repository: [Vercel Labs/skills](https://github.com/vercel-labs/skills)
- Tags: how-to-guide
- Published: 2026-04-23

---

**The `--full-depth` flag forces the skills CLI to recursively search all subdirectories for [`SKILL.md`](https://github.com/vercel-labs/skills/blob/main/SKILL.md) files, even when a root-level skill file exists.**

When working with the `vercel-labs/skills` repository, you may encounter situations where a top-level [`SKILL.md`](https://github.com/vercel-labs/skills/blob/main/SKILL.md) masks nested skills in subdirectories. The `--full-depth` flag solves this by overriding the default early-return behavior and ensuring complete skill discovery across your entire codebase.

## What `--full-depth` Does Inside the Skills CLI

The skills CLI optimizes discovery by default: if it finds a [`SKILL.md`](https://github.com/vercel-labs/skills/blob/main/SKILL.md) in the root directory, it stops searching and returns only that skill. This prevents unnecessary filesystem traversal but can hide legitimate skills in subdirectories.

The `--full-depth` flag, defined in `src/cli.ts#L143`, changes this behavior:

```bash
skills add <repo> --full-depth

```

When enabled, the CLI continues scanning after finding a root skill, executing a full recursive search through all subdirectories.

## Where the Flag Is Implemented

The `--full-depth` functionality spans four key files in the `vercel-labs/skills` codebase:

### CLI Help Definition ([`src/cli.ts`](https://github.com/vercel-labs/skills/blob/main/src/cli.ts))

```typescript
// From src/cli.ts#L143
`--full-depth           Search all subdirectories even when a root SKILL.md exists`

```

This displays the flag in help output and establishes the user-facing contract.

### Option Parsing ([`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts))

```typescript
// From src/add.ts#L99-L101
else if (arg === '--full-depth') {
  options.fullDepth = true;
}

```

The `parseAddOptions` function converts the CLI flag into a boolean on the `AddOptions` object.

### Discovery Logic ([`src/skills.ts`](https://github.com/vercel-labs/skills/blob/main/src/skills.ts))

The core algorithm in [`src/skills.ts`](https://github.com/vercel-labs/skills/blob/main/src/skills.ts) implements the conditional behavior:

```typescript
// From src/skills.ts#L39-L52
// Early-return guard: skipped when fullDepth is true
if (!options.fullDepth && rootSkillFound) {
  return [rootSkill];
}

// Priority directories scan continues...

// Recursive fallback: executes when fullDepth is true OR no skills found
// From src/skills.ts#L11-L23
if (options.fullDepth || skillsFound.length === 0) {
  const nestedSkills = await findSkillDirs(basePath);
  // Deduplication via seenNames Set
}

```

### Test Suite ([`tests/full-depth-discovery.test.ts`](https://github.com/vercel-labs/skills/blob/main/tests/full-depth-discovery.test.ts))

The comprehensive test validates both behaviors:

```typescript
// With fullDepth: false → only root skill
await discoverSkills(testDir, undefined, { fullDepth: false });
// Returns: [{ name: 'root-skill', ... }]

// With fullDepth: true → root + all nested skills
await discoverSkills(testDir, undefined, { fullDepth: true });
// Returns: [{ name: 'root-skill' }, { name: 'nested-skill-1' }, ...]

```

## Practical Usage Examples

### Command-Line Examples

Basic recursive discovery:

```bash
skills add vercel-labs/agent-skills --full-depth

```

Combined with other flags for automation:

```bash
skills add vercel-labs/agent-skills --full-depth -g -y --all

```

- `--full-depth`: Search all subdirectories
- `-g`: Install globally
- `-y`: Skip confirmation prompts
- `--all`: Install every discovered skill

### Programmatic Usage

From a custom script or build tool:

```typescript
import { discoverSkills } from 'skills/src/skills';

const repoPath = '/tmp/my-repo';

// Discover all skills, overriding default early-return
const allSkills = await discoverSkills(repoPath, undefined, {
  fullDepth: true
});

console.log(`Found ${allSkills.length} skills:`);
allSkills.forEach(s => console.log(` - ${s.name}`));

```

## When to Use `--full-depth`

The flag is essential in three common scenarios:

**Monorepos with documentation roots**
A top-level [`SKILL.md`](https://github.com/vercel-labs/skills/blob/main/SKILL.md) describes the repository, but each package in `packages/*` contains its own skill. Without `--full-depth`, only the root skill installs.

**Plugin or extension bundles**
A core skill ships with optional sub-skills in subdirectories. Users need `--full-depth` to discover and install the complete set.

**CI/CD and automation pipelines**
Scripts that must enumerate every available skill regardless of repository structure need predictable, complete discovery behavior.

## Summary

- The `--full-depth` flag in the skills CLI disables the default early-return optimization and forces recursive scanning of all subdirectories
- The flag is defined in [`src/cli.ts`](https://github.com/vercel-labs/skills/blob/main/src/cli.ts), parsed in [`src/add.ts`](https://github.com/vercel-labs/skills/blob/main/src/add.ts), and implemented in [`src/skills.ts`](https://github.com/vercel-labs/skills/blob/main/src/skills.ts) via conditional logic around `options.fullDepth`
- When `fullDepth` is `true`, the discovery algorithm continues past root-level [`SKILL.md`](https://github.com/vercel-labs/skills/blob/main/SKILL.md) files and executes `findSkillDirs()` for complete enumeration
- Use cases include monorepos, plugin bundles, and automated pipelines requiring deterministic skill discovery

## Frequently Asked Questions

### What happens if I don't use `--full-depth`?

Without the flag, the skills CLI stops at the first [`SKILL.md`](https://github.com/vercel-labs/skills/blob/main/SKILL.md) it finds in the root directory and returns only that skill. This optimization prevents unnecessary filesystem traversal but may hide nested skills in subdirectories.

### Can I combine `--full-depth` with other flags?

Yes. The flag works with all other `skills add` options including `-g` (global install), `-y` (auto-yes), and `--all` (install every discovered skill). The parsed options are passed together through the `AddOptions` object.

### Where is the discovery logic actually implemented?

The core algorithm lives in [`src/skills.ts`](https://github.com/vercel-labs/skills/blob/main/src/skills.ts) in the `discoverSkills()` function. This function checks `options.fullDepth` to decide whether to return early on root skill detection or continue with recursive directory scanning via `findSkillDirs()`.