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

The --full-depth flag forces the skills CLI to recursively search all subdirectories for 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 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 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:

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)

// 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)

// 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)

The core algorithm in src/skills.ts implements the conditional behavior:

// 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)

The comprehensive test validates both behaviors:

// 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:

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

Combined with other flags for automation:

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:

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 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, parsed in src/add.ts, and implemented in src/skills.ts via conditional logic around options.fullDepth
• When fullDepth is true, the discovery algorithm continues past root-level 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 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 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().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}