dsh-plugin-forge

dsh-plugin-forge

An agent skill for developing DeepSeek Harness plugins — from requirement to merged PR.

The skill walks one plugin through six phases, each with a completion criterion:

1. Design — whether a plugin is needed at all, one package or a three-role capability seam, host plane or preset plane, and a design-questions checklist (model-visible? configurable? side effects? secrets? durable state? UI?).
2. Scaffold — the workspace package skeleton with its package.json/tsconfig invariants.
3. Implement — the two plugin forms, Config with schemastery, declaration merging, and a pattern library distilled from the harness's own core packages (effects, events, tool execution, durable state, errors).
4. Wire — cordis.yml composition: bundle patches vs agent presets, and the verify-cordis-config / --dump-config checks.
5. Test — the spec matrix (unit + HMR-safety + export shape / loader-composition / integration / projection) and the testkits to reuse instead of hand-rolling mocks.
6. Ship — canonical README sections, generated catalogs, Agent Notes, PR labels.

Plus symptom-first debugging (PENDING fibers, silent load failures, HMR leaks), an error-text lookup for traps that compile but fail at load or first use, and the interaction seams (approval, credentials, user questions).

Install

Copy or symlink this directory into your agent's skills directory (e.g. .agents/skills/dsh-plugin-forge/, .claude/skills/, or your Codex skills path). The skill is model-invoked: it fires when a task involves creating, changing, debugging, testing, wiring, or shipping a dsh plugin.

For the best experience, also point the agent at a local checkout:

export DEEPSEEK_HARNESS_REPO=/path/to/deepseek-harness

Structure

SKILL.md            # workflow, cheat card, pitfalls, reference routing
references/
  design.md         # requirement → plugin plan; splitting rules; plane selection
  blueprints.md     # package skeleton, plugin bodies, cordis.yml wiring
  patterns.md       # proven shapes from the core packages, with sources
  testing.md        # spec matrix, testkits, coverage and snapshot duties
  external-bundle.md # installable bundles from a standalone repo; the web client-half format
  interaction.md    # approval, credentials, user questions
  debugging.md      # PENDING diagnosis, --dump-config, silent failures
  contract-traps.md # error text → cause → fix (schema DSL, export shape, tsconfig, runtime)
  shipping.md       # README gates, catalogs, Agent Note, PR requirements
agents/openai.yaml  # Codex invocation metadata
tests/check-skill.mjs  # self-checks (see below)

Self-checks

node tests/check-skill.mjs validates the skill itself: SKILL.md frontmatter (name matches the directory, description present), balanced code fences, internal link targets and anchors, and the reachability of every pinned upstream GitHub link. Pass --offline to skip the HTTP probes. GitHub Actions runs it on every push and PR; run it after any edit, and always after a re-pin.

Link and versioning policy

Documentation links pin to the dsh-v0.2.1-rc.3 tag of the harness repository — stable and auditable, at the cost of requiring network access. Set DEEPSEEK_HARNESS_REPO to a local checkout for live source; when the checkout disagrees with a pinned page, the checkout wins and the skill needs a re-pin. To re-pin: replace the tag in every link and re-verify the referenced sections still say what this skill claims.