# Maximum Nesting Depth for Skill Discovery in Superpowers

> Discover the maximum nesting depth for skills in Superpowers. Learn how to configure it via the maxDepth parameter to optimize your skill discovery process.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: deep-dive
- Published: 2026-02-19

---

**The default maximum nesting depth for skill discovery in the Superpowers framework is 3 levels deep, configurable via the `maxDepth` parameter in `findSkillsInDir()`.**

The `obra/superpowers` repository implements a recursive skill discovery system that scans directory trees for [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files. Understanding the maximum nesting depth for skill discovery is essential when organizing complex skill hierarchies, as the system imposes a default limit to prevent excessive recursion while maintaining flexibility through configuration options.

## How Skill Discovery Works

The core skill discovery logic resides in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js). The primary entry point is the `findSkillsInDir()` function, which recursively traverses directories looking for skill definition files.

The function signature includes a default recursion limit:

```javascript
findSkillsInDir(dir, sourceType, maxDepth = 3)

```

As the function traverses the directory tree, it increments a depth counter at each level. When the current depth exceeds the `maxDepth` value, the recursion stops, preventing the scanner from descending further into deeply nested subdirectories.

## Default Maximum Nesting Depth

Out of the box, the maximum nesting depth for skill discovery is **3 levels**. This default is hardcoded in the function signature at line 59 of [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) (lines 59-68 implement the depth-checking logic).

This limit means that when scanning for skills:

- Level 1: The root directory passed to `findSkillsInDir()`
- Level 2: Immediate subdirectories  
- Level 3: Sub-subdirectories

Any [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files located deeper than the third level will not be discovered during the default scan.

## Customizing the Nesting Depth

While the default depth of 3 suits most projects, you can override this limit by passing a custom `maxDepth` value.

### Overriding maxDepth Per Call

To increase the scanning depth for a specific invocation, pass an integer as the third argument:

```javascript
import { findSkillsInDir } from './lib/skills-core.js';

// Scan up to 5 levels deep
const skills = findSkillsInDir('/path/to/skills', 'superpowers', 5);
console.log(skills);

```

This approach allows you to scan deeper hierarchies without modifying the core library code.

### Implementing Project-Wide Configuration

For consistent depth limits across your application, create a wrapper function that enforces your project's standards:

```javascript
import { findSkillsInDir } from './lib/skills-core.js';

const PROJECT_MAX_SKILL_DEPTH = 4;

export function discoverAllSkills(root) {
  return findSkillsInDir(root, 'superpowers', PROJECT_MAX_SKILL_DEPTH);
}

```

This pattern centralizes configuration and makes it easy to adjust the maximum nesting depth for skill discovery across your entire codebase.

## Summary

- The default **maximum nesting depth for skill discovery** in Superpowers is **3 levels**, defined in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js).
- The `findSkillsInDir()` function accepts a `maxDepth` parameter that defaults to 3 but can be overridden.
- Skill definition files ([`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md)) located deeper than the configured limit are ignored during discovery.
- Best practice involves creating wrapper functions to enforce project-specific depth limits consistently.

## Frequently Asked Questions

### What is the default maximum nesting depth for skill discovery?

The default maximum nesting depth is **3 levels**. This limit is hardcoded in the `findSkillsInDir()` function signature in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) at line 59, where `maxDepth` defaults to 3.

### Can I increase the nesting depth beyond 3 levels?

Yes, you can increase the depth by passing a custom integer as the third argument to `findSkillsInDir()`. For example, calling `findSkillsInDir('/path', 'superpowers', 5)` allows the scanner to descend up to 5 levels deep.

### Where is the skill discovery logic implemented?

The core skill discovery logic is implemented in **[`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js)**. This file contains the `findSkillsInDir()` function that recursively searches directories for [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files while respecting the `maxDepth` parameter.

### What happens if I set maxDepth to 0 or a negative number?

Setting `maxDepth` to 0 would prevent any recursion beyond the initial directory, meaning only [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) files in the root directory would be discovered. Negative values would likely cause immediate termination of the recursion or unexpected behavior, though the function is designed to expect positive integers for proper operation.