Plugin Write

Write DeepSeek Harness Plugins

Create a plugin package. First classify the repository mode and plugin form, then read the matching reference files, and finally validate the published entry with the smallest set of gates that covers the change.

Select the Repository Mode First

Derive Cordis, Schemastery, and DSH package names and version ranges from the manifest of the exact target version. Current examples use scoped @deepseek-ai/* identifiers. Older targets may differ and must follow their own published contracts.

For every new external plugin, read references/naming-conventions.md before choosing public identifiers. Create dsh-plugin.naming.json at the plugin repository root and run the bundled read-only validator before final package validation. Treat compatibility errors as target-contract failures and prefix warnings as community recommendations; use --strict only when the plugin adopts the collision-resistant profile. This is not an official Harness manifest or a global reservation. For an existing external plugin, report naming deviations but preserve published names unless the user explicitly authorizes a compatibility-breaking rename. Packages inside the official monorepo follow the exact target checkout instead of this external naming profile.

After the offline declaration passes, read references/registry-check.md and run the separate central lookup when public network access is available. Supply the exact target Harness version. Treat a completed no-match result only as “no reviewed match”; treat timeout, malformed data, unsupported contract, or network failure as “unknown/not checked.” Never let the online lookup modify the local manifest, automatically rename a published surface, or turn an automated discovery candidate into a reservation. A formal reservation exists only after a source-backed entry is reviewed and merged in the central registry.

Then Classify the Plugin Form

A plugin may combine forms freely, such as a configurable tool plugin or a service that also registers tools. Every included form still has to satisfy its own contract. When a requirement does not match one of the five forms above, map it to an existing extension point and write a plugin that registers there. Never modify the Agent loop directly.

Package Checklist

1. Create an in-repository package — Only in the official monorepo, create packages/<group>/<pkg>/ with package.json, tsconfig.json, src/index.ts, and README.md. Copy packages/core/tools/package.json from the target checkout, then adjust its name, description, and dependencies. Preserve target-version invariants: private: true; the root package version; type: module; main: "lib/index.js"; types: "lib/types/index.d.ts"; both types and default in exports["."] pointing to lib; the same target Cordis range in peer and development dependencies; every DSH peer dependency mirrored in development dependencies; the target Schemastery package declared in dependencies; and the target files layout plus package-specific runtime artifacts. CLI application packages must include the built bin. Do not publish undeclared source or stale artifacts. Follow relative-import conventions from the target checkout. Prefer an existing group with the matching role. A new group is only a container, and the package must sit exactly one level below it.

2. Register an in-repository package — Only in the official monorepo, add the package to the Host or Client aggregate exactly as required by the development guide in the target checkout. A normal package belongs to one aggregate only. Do not copy historical exceptions or file lists without checking the target version. External plugins must never modify Harness root configuration.

3. Create an external package — Preserve the existing package manager and build system. For a new plugin, apply the external naming policy and include a validated dsh-plugin.naming.json; for an existing plugin, do not silently rename public surfaces. Keep main, types, exports, files, optional bin, packaged-composition or Profile metadata, and the packed tarball consistent. Declare every runtime dependency explicitly and mirror the DSH peer dependencies needed for compilation in development dependencies. Do not make a publishable external plugin private or give it workspace version ranges merely because an in-repository template does so.

4. Choose the package topology — For a replaceable capability, split service definition, provider, and consumer into separate packages only when they will evolve independently. Keep a single-purpose plugin in one package.

5. Write the in-repository package README — Only when required by the target monorepo, put package-specific service APIs, configuration, events, extension points, and design notes first. End the README with the canonical "Model Experience" ordering and "Known Limitations" section from the target checkout. Describe each direct, conditional, capped, lifecycle, or auxiliary-model surface in its own H3 with the following three H4 sections, each containing a prose paragraph. Quote stable text owned by the package. For a tool Schema surface, describe only differences not already present in the generated tool catalog. Under "KV Cache Impact," distinguish append-only growth, stable repeated prefixes, replacement of earlier request tokens, and independent model requests. Then list the package changes that invalidate reuse.

   ## Model Experience
   
   ### Request Surface and Activation Conditions
   
   #### What the Model Sees
   
   Name the exact data-dependent field, link to the generated catalog with an anchor, or introduce the verbatim text below.
   
   ##### Place the Verbatim Field Text Here When Needed
   
   ```markdown
   Copy any stable system-prompt body or other long nongenerated literal exactly from source.
   ```
   
   #### Token Impact
   
   State whether the impact is fixed, conditional, retained, replaced, capped, or has zero direct token impact.
   
   #### KV Cache Impact
   
   Describe append-only, prefix-stable, replacement, or independent behavior, including exact conditions that may invalidate reuse.
   
   ## Known Limitations and Deferred Work
   
   - **Consumer-visible gap** — State the exact missing operation or condition, its consequence, and any maintainer constraint.

6. Validate — For a new external plugin, first run node <plugin-write-skill>/scripts/validate-names.mjs --manifest ./dsh-plugin.naming.json; add --strict only for the collision-resistant community profile. After it passes, run node <plugin-write-skill>/scripts/query-registry.mjs --manifest ./dsh-plugin.naming.json --harness-version <exact-semver> when network access is available, and report an unavailable query as unknown rather than available. Then run the applicable validation block below, focused checks, and coverage gate required by the changed behavior.