Preface¶

The built-in skill-filesystem provider of DSH only scans the first layer of the skill root directory. If you organize skills into container folders by their purpose, for example obsidian-skills/defuddle/SKILL.md, the built-in provider won’t find it, effectively making the skill non-existent. The dsh-skill-recursive plugin solves this problem: it recursively scans standard skill root directories, indexing SKILL.md files nested at the second layer or deeper, while leaving the first-layer skills to be managed by the built-in provider. The author is DanielEstrada971102, it belongs to the Workflow category, and the license is MIT.

Below, I will introduce its origin, installation methods, configuration options, and boundaries that need attention.

What is it¶

In one sentence: a DSH bundle plugin that supplements DeepSeek Harness with recursive SKILL.md discovery capabilities. The maintainer is DanielEstrada971102.

It has a clear division of labor with the built-in provider:

.dsh/skills/
├── flat-skill/SKILL.md            ← built-in provider
└── obsidian-skills/               ← container folder
    ├── defuddle/SKILL.md          ← this plugin
    └── json-canvas/SKILL.md       ← this plugin

The first-layer flat-skill is still handled by the built-in provider, while the plugin only adds nested skills at depth 2 or deeper. This avoids the two providers from redundantly claiming ownership of the same skill.

Core Features¶

1. Scan Scope. It recursively traverses the following root directories: project-level .dsh/skills and .agents/skills (taking the nearest .git ancestor of the session working directory), $DSH_HOME/skills (default ~/.dsh/skills), $DSH_AGENTS_HOME/skills (default ~/.agents/skills), and extraRoots appended in the configuration.

2. Recursive Traversal. It descends to maxDepth from each root directory, skipping directory names listed in ignoreDirs.

3. Depth Protection. Only nested bundles at depth 2 or deeper are included, so ownership of first-layer skill discovery remains with the built-in provider and is not taken over by this plugin.

4. Priority. In cases of the same name, nested candidates rank lower than the corresponding first-layer root directory. In other words, if there are skills with the same name, the flat one wins.

5. Frontmatter Parsing. It reads name, description, optional whenToUse, disable-model-invocation, and user-invocable. Files that fail to parse will be logged and skipped without interrupting the overall scan. Supported YAML forms are scalars, quoted scalars, block scalars (|, >), and booleans. Any nested structure will not be forwarded.

6. Hot Reload. It listens for changes in root directories and invalidates skill directory caches; it falls back to polling in environments where recursive watching is unavailable.

Installation and Enabling¶

The plugin is a standard DSH bundle, usable in both the Desktop application (desktop profile) and the browser-hosted harness (web profile). Each profile only loads the content actually installed in it.

For the Desktop application, choose one of the two methods: install via the in-app plugin manager, or let the Harness session execute:

plugin_manager action=install_bundle target=github:DanielEstrada971102/dsh-skill-recursive#v0.2.0

For the Web profile, use the command line:

dsh plugin --profile web add github:DanielEstrada971102/dsh-skill-recursive#v0.2.0

Local clone method (only applicable if already cloned, commands provided in the README):

git clone https://github.com/DanielEstrada971102/dsh-skill-recursive.git
dsh plugin --profile <profile> add link:<absolute path to the clone>

After installing or updating the bundle, the host process needs to be restarted.

Configuration¶

The configuration entry is Settings → Plugins → Recursive Skill Discovery. The bundle page renders the configuration form, and changes take effect immediately after saving by DSH; no restart is required. The table below comes from the configuration description in the README.

You can also write a profile patch as the default configuration during deployment:

- insert:
    - id: skill-recursive
      name: dsh-skill-recursive
      config:
        maxDepth: 6
        extraRoots:
          - C:/shared/skills

Compatibility and Runtime Environment¶

The testing environment marked in the README is DeepSeek Harness 0.2.1-rc.5, Node.js 20 and above. The engines field in package.json also requires node >= 20. The only dependency is @deepseek-ai/schemastery ~3.18.5, with no other runtime dependencies. The settings form is rendered by the same Web client used for both Desktop and Web profiles.

Use Cases and Notes¶

Suitable for developers who organize skills by topic into containers and store SKILL.md files in .dsh/skills, .agents/skills, or user-level skill root directories. If your skills are all flat at the first layer, this plugin offers no extra benefit, as the built-in provider is sufficient.

A few points to note:

1. This plugin is a supplement to skill-filesystem, not a replacement. If that built-in provider is disabled, flat skills will not be discovered by this plugin.

2. Skill files are read directly via node:fs within the host process, behaving consistently with the built-in provider. The plugin runs with the permissions of the current dsh process. Before installing, check the source code and the MIT license to ensure the code and configuration meet your environment requirements.

3. A watcher is retained for each unique root directory path for the duration of the process lifecycle. If there are many root directories, pay attention to the usage of file handle watchers.

4. The directory scan depth defaults to 8, which is usually sufficient when combined with the default ignoreDirs. If extraRoots points to shared directories belonging to others, it is recommended to verify the trustworthiness of the SKILL.md files within them first, as they will be read directly into the skills directory.

Conclusion¶

The value of this plugin is narrow and clear: it fills the gap in DSH skill discovery for nested directories without altering the discovery logic of existing flat skills. If your project already organizes skills into subdirectories by topic, it is worth installing to try out; users who keep skills flat at the first layer do not need it.

Directory page: https://www.skillhub.cn/plugins/DanielEstrada971102/dsh-skill-recursive

GitHub: https://github.com/DanielEstrada971102/dsh-skill-recursive