Install a Harness Skill

Do this first — one command

Almost every install is this:

node "<skillDir>\scripts\install-skill.cjs" <source> [--scope global] [--dry-run] [--json]

<source> is a local folder, or a git source: https://github.com/o/r, github:owner/repo, github:owner/repo#subdir@v1.0.

It resolves the scope root, clones remote sources to staging outside the workspace, auto-detects the layout (single / collection / plugin), installs each real skill as a direct child of the skills root, puts any runtime payload in a sibling dir, copies a shared/ reference area inside the root, validates everything, and prints a compact result.

Read the rest of this file only if that script fails, or the case is unusual.

Exit codes: 0 ok · 1 validation problems · 2 usage/network error · 3 nothing installable.

Pick the scope

• "this workspace only" → <projectRoot>/.dsh/skills
• "globally" / "all workspaces" → <dshHome>/skills ($DSH_HOME or ~/.dsh)

projectRoot = nearest ancestor with .git, else the cwd. If the user gave no scope word and it is genuinely ambiguous, ask one short question; otherwise default to workspace.

Full root table and rank order: references/ecosystem-and-cli.md.

Three rules that explain every install failure

1. Discovery is exactly one level deep. A skill is <root>/<folder>/SKILL.md or a flat <root>/<name>.md. A SKILL.md two levels down (<root>/<wrapper>/<folder>/SKILL.md) is deliberately ignored — this is why a manual copy "doesn't work."
2. Identity is the frontmatter name, not the folder name. 00-orchestrator with name: saas-pipeline registers as saas-pipeline. Never rename the folder to match and never reject a skill over the mismatch.
3. Everything in the skills root is a skill, or ignored. Every *.md sitting directly in the root registers as a skill; a subdir with no SKILL.md is skipped silently. So never drop README.md, CHANGELOG.md, or agents/*.md in there, and keep runtime payloads out.

Frontmatter: what makes a skill silently vanish

Validated by the installer; these are the real rules:

• name and description are required, non-empty strings.
• name must match ^[a-z0-9]+(?:-[a-z0-9]+)*$ — lowercase, hyphen-separated. No uppercase, underscores, or --.
• The file must begin with --- as its first three characters. A UTF-8 BOM makes the first line "\uFEFF---", so the frontmatter is never found and the skill is skipped with no visible cause. Windows PowerShell 5.1 (Set-Content -Encoding UTF8) writes a BOM by default — write UTF-8 without BOM.
• Unknown keys are ignored, not rejected. Claude Code's argument-hint, license, compatibility, allowed-tools are harmless — do not "fix" them.
• Four legacy camelCase keys are fatal (skill skipped): disableModelInvocation, modelInvocable, userInvocable → use disable-model-invocation / user-invocable.
• Invocation flags must be boolean-ish (true/false/1/0/yes/no/on/off) or the skill is skipped.
• Folded (description: >) and literal (|) block scalars and quoted strings are all fine.

Runtime-dependent skills

A skill whose body says "run scripts/foo.py" or "invoke the plugin launcher" is not installed by copying SKILL.md alone — it will describe work it cannot execute.

1. Grep the bodies for the delegation: CLAUDE_PLUGIN_ROOT|CLAUDE_PLUGIN_DATA|\bbin/|scripts/\w+\.py|plugin root.
2. Install the payload to a sibling of the skills root (<projectRoot>/.dsh/<tool>/), never inside it.
3. Patch the launcher prose — usually one orchestrator file, not all of them. Leave the rest byte-identical so the install stays diffable against upstream.
4. Provision and prove it: run the tool's own setup/doctor, then one real command, and check the output.

Detail, worked example, and what does/doesn't survive a port: references/porting-non-dsh-skills.md.

Gotchas worth the tokens

• Never clone a source repo into the workspace. Repos ship AGENTS.md / CLAUDE.md, and DSH loads those from workspace directories as agent instructions that then steer every later session in that project. Clone to temp (install-skill.cjs does this automatically) and delete it afterwards; DSH confirms with an "Instructions removed" notice.
• There is no core dsh skills command. The CLI registers only plugin and web. dsh skills add comes from a third-party plugin, not the harness — don't reach for it, and don't tell the user it exists. See references/ecosystem-and-cli.md.
• Sandbox denials are policy, not a broken repo. Symptoms: git.exe failed to run: Access is denied, schannel: AcquireCredentialsHandle failed, dropped connections. Escalate that exact command once with a one-line justification, or use web_fetch (which often still has network) for inspection. If approvals are disabled, a denial is final — report it.
• Windows: upstream bin/<tool> launchers are bash and will not run; add a .cmd sibling. py -3 may resolve to a different interpreter than python.
• Keep the payload inside the workspace where you can — state written outside it may be blocked by a stricter sandbox later, breaking a working install. Check whether a manifest file (.claude-plugin/, runtime.json) controls where the tool puts its data before copying it.
• Never edit the bundled skill root ($DSH_BUNDLED_SKILL_DIR); upgrades overwrite it.

Verify — evidence, not assertions

node "<skillDir>\scripts\install-skill.cjs" --check-only <skillsRoot>

Exit 0 plus a registered-name list is the proof. "I found the folder" ≠ installed; "the script exists" ≠ it runs. The harness also pushes a replacement available-skills catalog when the watcher notices the change — the registered name there is the frontmatter name.

Report back

• Destination + scope (and for global: now live in all workspaces).
• What it was: single skill / multi-skill collection / another harness's plugin.
• Every registered skill name — never summarize a 25-skill collection as "the plugin".
• Runtime payload, if any, and where it went.
• Exactly which files you modified from upstream, and why.
• Evidence: validator result, catalog appearance, and one real execution with its output.
• Provisioning state: ready, or still needing setup.
• Fidelity gaps, stated plainly. For another harness's plugin: agent definitions that are inert rather than registered subagents, slash-command syntax that doesn't apply, extensions not installed, credentials not configured.