When a project skill and a user skill in DeepSeek Harness share a name, which one wins?

In DeepSeek Harness the smaller rank wins, so a project-level project-dsh skill (100) overrides a user-level user-dsh skill (400) with the same name. Put the override at project level, or move the shared version to user level to apply it everywhere.

How do I name a skill file in DeepSeek Harness, and how do SKILL.md and .md differ?

DeepSeek Harness uses kebab-case skill names and supports two layouts: the directory form /SKILL.md and the single-file form .md. Use the directory form when the skill ships scripts or templates, and the single-file form for a lightweight skill that is just prose.

How do I let a skill be invoked only manually and never automatically by the model?

Use the skill frontmatter switch disable-model-invocation to turn off model invocation, and user-invocable to control whether the skill is exposed to users. Combining the two gives manual-only, auto-only or fully open behavior.

Can I customize DeepSeek Harness skill directories, and how does the model trigger a skill?

Yes. Add custom directories with Config.customSkillDirs, which are ranked 300. On the model side, skills are invoked by name through the skill({ name }) tool, so the name must match the directory or file naming.

Where DeepSeek Harness finds Skills: skill directory ranks

Q: Which directories does DeepSeek Harness scan for skills, and how is priority ordered?

DeepSeek Harness discovers skills across six ranked sources: project-dsh (100), project-agents (200), custom (300), user-dsh (400), user-agents (500) and bundled (600), where a smaller rank wins. Project-level paths are /.dsh/skills and .agents/skills, while the user-level path is /skills.

DeepSeek Harness discovers Skills across six ranked directories from 100 to 600, where a smaller rank wins: project .dsh/skills (100) → .agents/skills (200) → custom customSkillDirs (300) → user <dshHome>/skills (400) → user agent directory (500) → bundled (600). This guide covers where to put files, how to name them and which switches to set.

Where DeepSeek Harness finds Skills: six directories and their ranks

DeepSeek Harness discovers skills in ascending rank order: project-dsh (100), project-agents (200), custom (300), user-dsh (400), user-agents (500) and bundled (600), where the smaller rank wins (source). Here is each source:

project-dsh (100) — <projectRoot>/.dsh/skills. Expected: applies only to this project, with the highest priority.
project-agents (200) — .agents/skills at the project root. Expected: honors the agent convention directory, also scoped to this project.
custom (300) — directories named by Config.customSkillDirs. Expected: good for team-shared skills kept on a standalone path.
user-dsh (400) — <dshHome>/skills, that is $DSH_HOME/skills. Expected: applies to every project on this machine.
user-agents (500) — the user-level agent convention directory. Expected: lower priority than user-dsh.
bundled (600) — skills shipped with the distribution, located via DSH_BUNDLED_SKILL_DIR and BUNDLED_SKILL_RANK. Expected: lowest priority, acting as the fallback.

On name collisions the smaller rank wins: a project skill overrides a user skill with the same name.

How to name a DeepSeek Harness skill file: directory and single-file layouts

DeepSeek Harness uses kebab-case skill names and supports both the <name>/SKILL.md directory layout and the <name>.md single-file layout (source). Pick the layout you need:

Directory layout <name>/SKILL.md — the directory name is the skill name and the instructions live in SKILL.md inside it. Expected: best when the skill ships scripts or templates.
Single-file layout <name>.md — the file name itself is the skill name. Expected: best for a lightweight skill that is just prose.
Name consistently in kebab-case — for example code-review or release-notes. Expected: the name matches the name used when invoking.
Place the file, then verify — restart or reload after adding it. Expected: the skill shows up in the skill list.

How to control skill invocation in DeepSeek Harness: frontmatter switches and the skill tool

A skill's frontmatter supports disable-model-invocation and user-invocable, which control whether the model may invoke it automatically and whether it is exposed to the user; the model side invokes by name through the skill({ name }) tool (source). Configure by combination:

Fully open by default — with no switches set, the model can invoke automatically and the user can invoke manually. Expected: fine for general-purpose skills.
Manual only: disable-model-invocation — turn off automatic model invocation. Expected: it fires only when the user explicitly invokes it, which suits side-effecting operations.
Auto only: leave user-invocable unset — use this when the user entry point must be limited. Expected: the model decides from context whether to invoke it.
How the model invokes — the model passes the skill name to skill({ name }). Expected: a mismatched name cannot be reached.
Limit directory description length — catalogDescriptionMaxLength defaults to 500 and caps how long a skill's description may be in the catalog. Expected: overly long descriptions are truncated.

Skills are a common pattern for extending DSH plugins; to find ready-made skill plugins, filter by purpose in the DSH Plugin Hub.

Caveats and limits of DeepSeek Harness Skills configuration

Priority is rank only: project beats user and user beats bundled, so on a name collision the lower rank never takes effect.
customSkillDirs is not top priority: it sits at 300, still below the two project-level sources.
Names must be kebab-case: mixed case or underscores can break discovery or leave the invocation name unmatched.
Switches define the safety boundary: give side-effecting skills disable-model-invocation so the model cannot fire them automatically.
Many directories shadow each other: when the same name appears at several ranks, only the highest-priority one takes effect, so check first whether a project-level copy is overriding it.

Sources: Skills (official docs), dsh CLI README (official repository)