dsh-creator

name

dsh-creator

description

Create and validate extensions for DeepSeek Harness (dsh), including Cordis plugin bundles, model-facing tools, LLM adapters, native or compatibility hooks, Agent Skills, MCP connections, Web conversation nodes, protocol drivers, and profile/bundle/patch configuration. Use when designing, scaffolding, packaging, debugging, or reviewing a DSH extension or when deciding which DSH capability seam should own a customization.

DSH Creator

Build extensions against the selected DeepSeek Harness release, not against remembered APIs. DSH is a developer preview with breaking changes. The initial evidence baseline for this skill is @deepseek-ai/dsh@0.1.0-rc.6 plus the official source contracts recorded in the repository's COMPATIBILITY.md.

Establish the target

Before generating code, determine:

1. Runtime version — capture dsh --version or npx @deepseek-ai/dsh --version.
2. Capability — plugin, tool, adapter, hook, skill, MCP, UI node, protocol, or config.
3. Delivery form — local overlay, installable bundle, built-in plugin configuration, or skill-only directory.
4. Surface/profile — web, headless, a custom profile, or a source checkout.
5. Verification boundary — config dump, typecheck, keyless smoke, or real-provider test.

If the user cannot provide a version, inspect the installed package or package manager metadata before choosing types or examples.

Choose the delivery form

Form	Use it for	Activation
Agent Skill directory	Reusable instructions without runtime code	Place under a discovered skill root
Built-in plugin config	MCP and published compatibility bridges	Insert/configure the published package in a patch
Local overlay	Fast development from a source checkout	dsh web --patch ./overlay.yml
Installable bundle	Reusable tools, adapters, hooks, or composed extensions	dsh plugin --profile <name> add <package-or-git-spec>

Do not treat npx as a reduced API mode. Current DSH profiles can install out-of-tree bundles and their dependencies. A bare local TypeScript file referenced from a profile still has module-resolution constraints; package reusable work as a bundle instead of removing types and imports.

Route to one focused reference

Load only the reference needed for the current capability:

Goal	Reference
Build a model-facing tool	tools.md
Connect an LLM provider	llm-adapters.md
Intercept lifecycle or reuse command hooks	hooks.md
Author a DSH-compatible Agent Skill	skills.md
Connect an MCP server	mcp-bridges.md
Add a Web conversation node	ui-nodes.md
Drive DSH from another process	protocol-drivers.md
Compose profiles, bundles, and patches	yml-config.md

Use the Cordis plugin contract

A function plugin uses named exports and declares every required service:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'
export const inject = ['tools']

export function apply(ctx: Context): void {
  // Register one capability through ctx.
}

Keep name, inject, Config, and apply as named exports. Do not add a default export to a function plugin: the loader can unwrap the default and lose the named namespace. Registrations made through ctx are effect-owned; use ctx.effect() for external resources that need an explicit disposer.

Package reusable plugins as bundles

An installable bundle owns a patch layer:

{
  "name": "dsh-my-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "lib/index.js",
  "files": ["lib", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

- insert:
    - id: my-plugin
      name: dsh-my-plugin

Install a checkout or GitHub source into a profile:

dsh plugin --profile web add ./dsh-my-plugin
dsh plugin --profile web add github:owner/dsh-my-plugin#<commit>
dsh --profile web --dump-config

Git-hosted TypeScript packages need a self-contained prepare build and explicit pnpm build permission from the installer. Prefer prebuilt npm packages or tarballs when install-time code execution is unnecessary.

Work from evidence

For every implementation:

1. Read the selected release's exported types and official documentation.
2. Prefer a shipped reference implementation over a hand-invented abstraction.
3. Keep runtime configuration in Schemastery Config, with secrets supplied through DSH credential/config layers or environment expressions.
4. Make replayed UI presentation pure and deterministic.
5. Propagate cancellation signals and make disposal reach quiescence.
6. Validate the composed tree with --dump-config before booting.
7. Run the smallest smoke test that crosses the real registration and loading boundary.

Clearly label pseudocode or an intentionally incomplete scaffold. Never call it verified or copy-ready.

Verification matrix

Change	Minimum verification
Skill content	Skill validation and discovery through npx skills add ... --list
Patch/config only	dsh --profile <name> --dump-config
Plugin bundle	package build, profile install, config dump, activation smoke
Tool or hook	registration plus one success and one denial/error path
LLM adapter	chunk-order tests, cancellation, error mapping, one provider smoke when credentials exist
MCP	discovery, one call, reconnect/disposal behavior appropriate to the transport
UI node	replay, pagination/prepend, incremental update, and render-error checks
Protocol driver	handshake, one complete run, transport loss, and child-process reap

Assets

Use the bundled starters only after choosing the capability and checking its reference:

Asset	Purpose
assets/templates/tool/	Typed defineTool example
assets/templates/llm-adapter/	Adapter protocol scaffold
assets/templates/hook/	Native lifecycle hook example
assets/templates/mcp-bridge/	Built-in MCP client patch
assets/templates/ui-node/	Replay-safe conversation node starter

Treat the official DSH source and installed type declarations as authoritative when an asset disagrees with the selected release.