DeepSeek Harness Skills Missing: SKILL.md Single-Level Scan
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:
- Arrange a skill library by category.
library/
category-a/
skill-1/SKILL.md
skill-2/SKILL.md
category-b/
skill-3/SKILL.md
- Point
customSkillDirsat the library root.
- 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".
- Point
customSkillDirsat each category directory instead.
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".
- 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:
- Directory children: when the child is a directory,
locatorbecomes{ path: join(entry.path, 'SKILL.md'), directory: entry.path }. - File children: when the child ends in
.md,locatorpoints at that file anddirectorytakes the root path. - Everything else:
locatorisvoid 0, immediately followed byif (locator === void 0) continue;— a category directory lands exactly in this branch, and the comment verbatim readsa category is dropped here, silently. - A second silent path: when
parseSkillFilereturnsundefined, it likewisecontinues, with no log. - 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:
- The project layer is fixed:
<project>/.dsh/skillsand<project>/.agents/skillsare hardcoded inroots(), with no configuration entry. - Custom directories are global:
customSkillDirshangs off the provider, so changing it affects the whole host or preset and cannot be separated per project. - 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". - No diagnostic outlet:
SkillCatalogSnapshothas only{ skills, complete }and noreason, 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:
- Flatten: move
library/category-a/skill-1/bodily tolibrary/skill-1/so<root>/<skill>/SKILL.mdholds. Expected: all skills visible. The cost is losing the category hierarchy and relying on name prefixes instead. - 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. - 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".
- Self-check before and after an upgrade: restart after changing the config, confirm the skill count matches expectations, and watch whether
completechanges — 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:
| Layer | Symptom | Any log? | Key location |
|---|---|---|---|
| Discovery (this article) | A whole category of skills invisible | None at all | The bare continue in discoverRoot() |
| Observability (#9608) | One root's watch fails, the group flips to complete:false | replaceWatcher logs | A per-root failure invalidates the whole observation |
| Rendering (#9375) | whenToUse is written but the model never sees it | None | The 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:
- 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. - Add a
maxDepthoption, defaulting to 1. Setting it to 2 discovers<category>/<skill>/SKILL.mddirectly, with zero impact on existing deployments since the default preserves old behavior. - 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. - Optional: wildcard support for
customSkillDirs(/path/to/library/*). Nice to have, not required. - 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:
- Nature: a design limitation, not a regression, so "roll back to an older version and it will be fine" does not apply.
- Observability: even
complete:falsemay not appear — it covers observation failures, not "a directory was rejected". That is exactly why the proposal puts the warn first. - How to report: the repository's
CONTRIBUTING.mdsays external PRs are not accepted and feedback goes through Discussions; attaching the directory structure, thecustomSkillDirsconfig 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:
- 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.
- Point the root at a category directory as a control, which proves the files are intact in one step.
- Do not ignore "no log" as a signal: the discovery layer's signature is complete silence, not filtered logging.
- Flattening is the least trouble, so get skills running first and discuss category organization afterwards.
- Keep the three layers apart; do not treat a
whenToUsefailure as a discovery failure. - 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.
FAQ
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.
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.
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.
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
- #11898 — Skills discovery is single-level only — category folders are unsupported and skipped silently· deepseek-ai (GitHub Discussions)