Maximum Nesting Depth for Skill Discovery in Superpowers

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

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

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:

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.
• The findSkillsInDir() function accepts a maxDepth parameter that defaults to 3 but can be overridden.
• Skill definition files (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 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. This file contains the findSkillsInDir() function that recursively searches directories for 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 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.

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