ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness Skills Missing: SKILL.md Single-Level Scan

TroubleshootingPublished 2026-11-03Author: DeepSeek Plugin Market
DeepSeek Harnessskill discoverySKILL.mdskill-filesystemcategory directoriessilent failure
A skills library at <root>/<category>/<skill>/SKILL.md stays invisible in DeepSeek Harness: dsh-skill-filesystem scans one level and silently skips categories.

The most common "skills installed but not working" complaint in DeepSeek Harness (DSH) has a cause that is easily mistaken for a misconfiguration: skill discovery scans only one level. @deepseek-ai/dsh-skill-filesystem discovers skills from a fixed set of roots, and each root is scanned exactly one level down; if your library is organized as library/category-a/skill-1/SKILL.md, then category-a has no SKILL.md of its own, fails the shape check, and is silently discarded by a bare continue — 3 skills expected, 0 actual, no warning, no log. This is a design limitation, not a regression: a community reply cross-references #9608 and #9375, confirming it is the "discovery" layer of silent failures on the skill surface, and the only one of the three with no diagnostics at all (#11898).

Reproduce first: a three-level directory yields zero skills

The decisive signal: pointing the root at the parent of the category directories gives 0 skills, while pointing it at a category directory itself gives the normal count. Steps:

  1. Arrange a skill library by category.
text
library/
  category-a/
    skill-1/SKILL.md
    skill-2/SKILL.md
  category-b/
    skill-3/SKILL.md
  1. Point customSkillDirs at the library root.
yaml
- id: skill-filesystem
  config:
    customSkillDirs:
      - /path/to/library

Expected: 0 skills in the list, and no line in the log saying "skipped", "rejected" or "unrecognized".

  1. Point customSkillDirs at each category directory instead.
yaml
    customSkillDirs:
      - /path/to/library/category-a
      - /path/to/library/category-b

Expected: all 3 skills appear. This step is crucial: it proves the skill files themselves are fine and the problem is only "how many levels sit between the root and the skill".

  1. Rule out other causes. If step 3 still gives 0, change direction to the observability layer (complete:false) or the rendering layer (whenToUse) instead of applying this conclusion.

The code location: the continue where locator is undefined

In one sentence: discoverRoot() requires <child>/SKILL.md for every direct child, a category directory has no such file, so locator is empty and the entry is skipped. Unpacked:

  1. Directory children: when the child is a directory, locator becomes { path: join(entry.path, 'SKILL.md'), directory: entry.path }.
  2. File children: when the child ends in .md, locator points at that file and directory takes the root path.
  3. Everything else: locator is void 0, immediately followed by if (locator === void 0) continue; — a category directory lands exactly in this branch, and the comment verbatim reads a category is dropped here, silently.
  4. A second silent path: when parseSkillFile returns undefined, it likewise continues, with no log.
  5. The watch is also depth: 1: consistent with the watch depth noted in #9608, showing that "one level" is not just a scan policy but an observation policy too.

So this is not something "file permissions" or "bad YAML" can explain: the directory really was seen, and then judged "not a skill directory" at the shape check.

Neither knob composes "project-level plus category granularity"

In one sentence: roots() hardcodes two project paths, customSkillDirs is host/preset level, and no combination expresses "this project only sees category A". The facts:

  1. The project layer is fixed: <project>/.dsh/skills and <project>/.agents/skills are hardcoded in roots(), with no configuration entry.
  2. Custom directories are global: customSkillDirs hangs off the provider, so changing it affects the whole host or preset and cannot be separated per project.
  3. The only workable project-level trick is a link per skill: one link per skill inside <project>/.dsh/skills, costing O(n) per project, needing rework as the library grows, and conflating "source" with "skill".
  4. No diagnostic outlet: SkillCatalogSnapshot has only { skills, complete } and no reason, so a consumer that wants to explain cannot even name the root at fault.

That is also why "category directories are invisible" and "skill libraries are not portable" often show up together: they come from the same root model.

Workarounds: flatten, or enumerate each category

In one sentence: without touching source, either flatten skills to one level under the root or register every category directory separately; both work, and both give up the convenience of category organization. Two options:

  1. Flatten: move library/category-a/skill-1/ bodily to library/skill-1/ so <root>/<skill>/SKILL.md holds. Expected: all skills visible. The cost is losing the category hierarchy and relying on name prefixes instead.
  2. Enumerate per category: write each category directory into customSkillDirs. Expected: 3 skills visible. The cost is editing config every time the library grows, plus a host-or-preset-wide scope.
  3. Link approach: create one link per skill inside the project-level fixed root. Expected: visible within the project. The cost is O(n) maintenance and blurred meaning between "source" and "skill".
  4. Self-check before and after an upgrade: restart after changing the config, confirm the skill count matches expectations, and watch whether complete changes — it can at least tell you "a root failed to be observed".

Three layers of silent failure: work out which one you are in

In one sentence: the discovery, observability and rendering layers have similar symptoms but different mechanisms, and investigating them together misleads you. The comparison:

LayerSymptomAny log?Key location
Discovery (this article)A whole category of skills invisibleNone at allThe bare continue in discoverRoot()
Observability (#9608)One root's watch fails, the group flips to complete:falsereplaceWatcher logsA per-root failure invalidates the whole observation
Rendering (#9375)whenToUse is written but the model never sees itNoneThe field is discarded at render time

All three share "no error is raised", and differ in whether you can read it from code or logs: the rendering layer parses, validates and ships the field to the client before dropping it, so reading the code confirms it; the observability layer at least logs; the discovery layer cannot even let downstream infer that "this directory existed".

Making the failure visible: add a warn at the shape check

In one sentence: the smallest and cheapest improvement is a warning with the path at locator === undefined, leaving behavior untouched and only turning silence into visibility. The proposals from the thread, ordered by cost:

  1. One warning per root, for example skill-filesystem: <root>/<dir> contains SKILL.md at depth 2 but is not a skill directory; ignored. It needs no new configuration surface, just one log line.
  2. Add a maxDepth option, defaulting to 1. Setting it to 2 discovers <category>/<skill>/SKILL.md directly, with zero impact on existing deployments since the default preserves old behavior.
  3. Project-level additional roots, for example declaring roots: in <project>/.dsh/skills.yml. Combined with option 2, "this project only sees category A" goes from N links to a single declaration.
  4. Optional: wildcard support for customSkillDirs (/path/to/library/*). Nice to have, not required.
  5. Scoping must be static: the proposal stresses that option 3 is "static for the project lifetime" and directory prefixes stay stable, so KV cache reuse is unaffected; dynamic per-turn trimming is deliberately avoided because changing every turn breaks the cache prefix and nets out negative.

Fix status and expectations

In one sentence: as of that discussion there is no upstream fix and no patch branch; on the user side you can only work around it as above or wait for a capability like maxDepth. Three notes:

  1. Nature: a design limitation, not a regression, so "roll back to an older version and it will be fine" does not apply.
  2. Observability: even complete:false may not appear — it covers observation failures, not "a directory was rejected". That is exactly why the proposal puts the warn first.
  3. How to report: the repository's CONTRIBUTING.md says external PRs are not accepted and feedback goes through Discussions; attaching the directory structure, the customSkillDirs config and the actual skill count saves a round of clarification.

Debugging notes

The rule for skills that do not take effect is: count the skills first, then look at directory levels, and only then at rendering fields. Six points:

  1. Establish whether it is "0" or "a few missing" first: 0 is usually a root-level problem, while a few missing points at observability or rendering.
  2. Point the root at a category directory as a control, which proves the files are intact in one step.
  3. Do not ignore "no log" as a signal: the discovery layer's signature is complete silence, not filtered logging.
  4. Flattening is the least trouble, so get skills running first and discuss category organization afterwards.
  5. Keep the three layers apart; do not treat a whenToUse failure as a discovery failure.
  6. Recheck the skill count after an upgrade or a config change; this class of silent failure never reminds you on its own.

Source: Discussion #11898, related discussions #9608 and #9375.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why are DeepSeek Harness skills invisible with no log?

Because DeepSeek Harness's dsh-skill-filesystem scans only one level per root. It requires a root's direct children to be skill directories passing a <child>/SKILL.md shape check, and category-a has no SKILL.md of its own, so its locator is undefined and a bare continue throws it away — zero skills and zero warnings.

Is DeepSeek Harness single-level skill discovery a bug?

It is a DeepSeek Harness design limitation, not a regression. The responder cross-references #9608 and #9375 and confirms this is the discovery layer of the same family of problems; the watch is also depth: 1 but that is by design. It is not a rendering or observability defect you can spot without changing code — the discovery layer simply has no concept of a second directory level.

Load categorized skills in DeepSeek Harness without edits?

In DeepSeek Harness, flatten the skill directories to one level under the root, so SKILL.md sits directly at <root>/<skill>/SKILL.md. Or point customSkillDirs at each category directory separately, for example /path/to/library/category-a, at the cost of enumerating per category and a scope that covers the whole host or preset.

Is DeepSeek Harness skill invisibility the whenToUse bug?

No, in DeepSeek Harness they are three different silent failures on the skill surface. This one is the discovery layer: a directory is seen but not recognized, with no log at all; #9608 is observability: a failed watch on one root flips the whole group to complete:false, and at least replaceWatcher logs something; #9375 is rendering: whenToUse is parsed and validated, then discarded when rendering.

Related Terms

discoverRoot
discoverRoot is the function in dsh-skill-filesystem that enumerates skill directories for each root. It shape-checks every direct child: a directory must contain <child>/SKILL.md, a file must end in .md; anything else is skipped by continue with no log at all.— https://github.com/deepseek-ai/deepseek-harness/discussions/11898
customSkillDirs
customSkillDirs is a dsh-skill-filesystem configuration option for adding skill directories beyond the default roots. It applies at the host or preset level, not the project level, so it cannot express 'this project only sees category A'.— https://github.com/deepseek-ai/deepseek-harness/discussions/11898
SkillCatalogSnapshot
SkillCatalogSnapshot is the snapshot type the skill catalog exposes, with only { skills, complete } and no reason field. So even when a consumer wants to explain 'why is a root missing', there is no way to say which level or which path caused it.— https://github.com/deepseek-ai/deepseek-harness/discussions/11898

Sources