develop-dsh-plugin

An agent skill for building out-of-tree DeepSeek Harness (dsh) plugins.

dsh has no privileged core to patch: every part of the product is a plugin, and you extend it by mounting a package beside the others. This skill turns that architecture into an executable workflow — research the existing surface first, pass a design gate, mount through a documented seam, validate against a real composition, and unload cleanly.

Written as an SKILL.md package, so it works in any agent runtime that scans a skill directory (Claude Code, dsh's own skill-filesystem, and similar).

What it does

The workflow is seven steps, each with explicit stop conditions:

1. Research before designing — inspect official packages, community plugins, and the target project's installed composition. Do not create a plugin when something installed already owns the surface.
2. Pass the design gate — one sentence naming the capability owner, the seam, Host/Client, model visibility, durability, and the unload boundary.
3. Scaffold — generate a minimal buildable Host plugin from the bundled template.
4. Implement within the seam — named name/inject/Config/apply exports, services over imports, fiber-owned reversible effects, misconfiguration that fails loudly.
5. Validate the real plugin — eight escalating levels of evidence, ending at a real Loader composition, a real session, and an unload check.
6. Package and publish — exports, pinned runtime deps, packaged files, bundle references.
7. Report honestly — exact commands and real evidence; never claim completion from source inspection.

Layout

SKILL.md                              main workflow
references/
  package-contract.md                 package shape, manifests, exports, bundles
  seam-router.md                      which seam a capability belongs on
  validation-and-casebook.md          evidence levels; real gap vs. operational trace
assets/minimal-host-plugin/           Host-only starter template
scripts/
  scaffold_plugin.py                  generate a plugin from the template
  audit_plugin.py                     deterministic package-shape audit
  test_scripts.py                     tests for the two scripts above
agents/openai.yaml                    agent-surface metadata

Install

Clone into whichever skill root your agent scans, keeping the directory name develop-dsh-plugin:

# Claude Code (user scope)
git clone https://github.com/ableclaw/ablemind-dsh-plugin-skill.git \
  ~/.claude/skills/develop-dsh-plugin

# dsh — user scope, or point Config.customSkillDirs at the parent directory
git clone https://github.com/ableclaw/ablemind-dsh-plugin-skill.git \
  ~/.dsh/skills/develop-dsh-plugin

dsh's skill-filesystem does not scan nested trees, so link or clone each skill directory individually.

Using the scripts without the skill

Both scripts are standalone Python 3, no dependencies. Take both exact versions from the runtime you target.

# scaffold — inspect the dry run first; it refuses to overwrite a non-empty directory
python3 scripts/scaffold_plugin.py ./dsh-plugin-example \
  --package-name dsh-plugin-example \
  --dsh-version "$TARGET_DSH_VERSION" \
  --cordis-version "$TARGET_CORDIS_VERSION" \
  --dry-run

# audit — run after building
python3 scripts/audit_plugin.py <plugin-dir> \
  --dsh-version "$TARGET_DSH_VERSION" \
  --require-built

The audit covers manifests, exports, pinned runtime dependencies, scripts, packaged files, bundle references, and common function-plugin export mistakes. It cannot prove service activation, double mounting, model behavior, replay, UI behavior, or cleanup — those need the real-composition steps in the skill.

Scope

Covers source packages: Host or Client plugins using Cordis services, typed events, model tools, session injection, slots, themes, bundles, patches, packaging, loading, replay, and disposal.

Does not cover temporary runtime-defined Cordis plugins driven by cordis_inspect_* / cordis_define / cordis_run — those are a different workflow and should not be scaffolded as packages.

The skill instructs the agent to read the target repository's own AGENTS.md / CLAUDE.md and treat those as the local contract. It deliberately does not transplant commands or dependency versions across checkouts. One line in SKILL.md names the internal repository this was extracted from; it is a routing hint, harmless elsewhere.

Provenance

Extracted from AbleMind's dsh productization workspace, where it is the source of truth for out-of-tree plugin work. Upstream dsh does not accept external pull requests; the supported contribution path is publishing plugins beside the official repository, which is what this skill is built to do.

License

MIT. See LICENSE.