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, waterfall, durable state, errors).
4. Wire — cordis.yml composition: bundle patches vs agent presets, and the verify-cordis-config / --dump-config checks.
5. Test — the five-spec matrix (unit + HMR-safety + export shape / loader-composition / integration / invariant / 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) 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
  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.1.0-rc.8 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.