Separate the file, discovery root, and activation

The SKILL.md contains reusable instructions and metadata. Its parent directory provides identity. A discovery root determines whether DSH can see it. Project-level roots should take precedence when the behavior belongs to one repository; user-level roots are appropriate for personal behavior that should follow you across workspaces.

Start with a minimal, valid Skill

Keep the description explicit about when the Skill applies. Put detailed examples and scripts beside the main file when the behavior becomes large, rather than turning the entry file into an unstructured knowledge dump.

Minimal SKILL.md shape · markdown
---
name: repository-release-check
description: Verify build, tests, and release artifacts before a repository release.
---

# Repository release check

1. Read repository instructions.
2. Run the documented validation commands.
3. Report failures with evidence.

Choose the narrowest useful scope

Use a project root for instructions coupled to its framework, commands, or policies. Use a user root for reusable personal workflows. Use custom roots only when there is a deliberate shared source and the precedence behavior is understood. Never copy a third-party Skill into a trusted root without reading every instruction and referenced script.

  • Project: repository-specific commands and architecture.
  • User: personal workflows that apply broadly.
  • Custom/shared: team-maintained source with explicit ownership.
  • Third-party: inspect content, references, and scripts before enabling.

Verify discovery with a controlled prompt

Restart or refresh discovery as required, confirm the Skill appears with the expected name and description, and issue a narrow prompt that should trigger it. A correct file that is not discovered is a path problem; a discovered Skill that never triggers is usually a description or scope problem.

Paths and precedence are not yet fully reproduced

HarnessBase still needs to verify project, user, and custom roots on Windows and a Unix-like environment, then record conflict precedence and frontmatter failure states before indexing this page.

Sources and evidence boundary

Primary sources establish product facts. HarnessBase labels direct testing separately and does not convert community observations into verified results.

Target query cluster: DeepSeek Harness skills · DeepSeek Harness SKILL.md · install DSH skill