PerryLink/dsh-plugin-guide

Compatibility

What you get

dsh-plugin-guide is the DSH plugin-development knowledge base, packaged as an installable bundle that registers the whole thing as the dsh-plugin-guide agent skill. The skill stays visible in every session catalog and loads its workflow steps, official docs, and community deep-dives on demand.

• Plugin contract & hard rules — effects/disposers, waterfall next(), model-visible ⟺ logged, Schemastery config.
• Official docs archive — a verbatim copy of the official repo docs (EN + ZH), byte-identical to upstream at the last verified snapshot.
• Cordis primer — the five concepts and the mechanism timeline (repository-plugin introduced 0809, removed 0811; the two install channels).
• 20+ real-world pitfalls with root cause + fix (cordis dual copies, tsconfig trio, multi-frame zstd sessions, Windows junctions, stale npm latest, …).
• Community deep-dives — 114 community repositories archived (15 deep-dived), plus a full source index where every fact links to its origin.

Knowledge base

Quick start

# 1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-plugin-guide#main"

# or from npm (published releases)
dsh plugin --profile web add dsh-plugin-guide

# 2. restart and verify the row
dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-guide'

Then just ask your agent: “Use the dsh-plugin-guide skill to build me a … plugin.”

Install & uninstall

• git channel (latest main): dsh plugin --profile web add github:PerryLink/dsh-plugin-guide#<sha> — pin a commit for reproducibility; the entry point is plain ESM JS, no build step.
• npm channel (published releases): dsh plugin --profile web add dsh-plugin-guide.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./dsh-plugin-guide-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-plugin-guide.

Copy as a plain agent skill

You can also copy the whole folder into your agent’s skill directory (relative paths stay intact):

# Windows (PowerShell)
pwsh -File scripts/install-skill.ps1 `
  -Target "$env:USERPROFILE\.deepseek\skills\dsh-plugin-guide"   # or <project>\.agents\skills\dsh-plugin-guide

# macOS / Linux
pwsh -File scripts/install-skill.ps1 -Target ~/.deepseek/skills/dsh-plugin-guide   # or <project>/.agents/skills/dsh-plugin-guide

The installer skips downloads/ (generated) and .github/, then verifies every copied file byte-for-byte. A manual Copy-Item -Recurse of the whole folder also works.

Configuration

dsh-plugin-guide exposes no Schemastery Config — it registers the knowledge base as an agent skill with no tunable keys.

Tools & surfaces

Permissions & data

• Permissions: declares filesystem:read in its workshop manifest.
• Data: read-only — reads its own bundled guide/ and references/ files. No network requests, no writes, no model calls.

Security boundaries

• Read-only knowledge base. The bundle only reads its own files; it never writes, never calls the network, and never invokes a model.
• Official docs are verbatim copies. references/official-docs/ is never edited here; report issues upstream and re-sync only with scripts/sync-official-docs.ps1.
• Distribution boundaries. Bundled third-party content keeps its upstream license; see NOTICE.md (e.g. downloads/ is local-only; awesome-dsh-plugins must not be redistributed).

Known limitations

• Official docs are a snapshot. Re-sync with scripts/sync-official-docs.ps1 when upstream moves; the freshness stamp and commit hash reference references/official-docs/SNAPSHOT.md.
• downloads/ is generated, not committed. Raw snapshots (community repo archives, Discussions, articles) must be generated with the scripts before use.
• awesome-dsh-plugins content is local-only. Its upstream declares an internal-use constraint, so it is not redistributed with the repo.

Keeping it fresh

pwsh -File scripts/sync-official-docs.ps1                     # verbatim docs copy from a local checkout
pwsh -File scripts/download-sources.ps1                       # official site/docs, Cordis, paper
pwsh -File scripts/download-community-repos.ps1               # community repositories (codeload tarballs)
pwsh -File scripts/download-community-articles.ps1            # zh/en/HN community articles
pwsh -File scripts/archive-discussions.ps1                    # official Discussions (needs $env:GH_TOKEN)
pwsh -File scripts/gen-topic-snapshot.ps1 -OutDir <dir>       # dsh-plugin topic census
pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>        # critical paths + link scan + docs drift

Development

The bundle is plain ESM — no build step. CI runs the integrity gate on every push and pull request:

pwsh -File scripts/verify-kit.ps1   # critical paths + link scan (+ docs drift with -Checkout <checkout>)

Topics

dsh, deepseek-harness, dsh-plugin, cordis, agent-skill, plugin-development, knowledge-base

Contributors

• PerryLink — creator and maintainer: knowledge-base content, the installable-bundle transformation, ecosystem submissions, and community engineering.
• Day-to-day maintenance is assisted by DeepSeek Harness agents (they hold no GitHub account and are listed here for transparency, not as contributors).

PerryLink DSH Plugin Family

This project is one of the 15 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

Disclaimer

Community-maintained, not an official DeepSeek product. DeepSeek Harness is in developer preview and ships breaking changes; when in doubt, the official docs in references/official-docs/ are the source of truth.

License

Apache License 2.0 © 2026 dsh-plugin-guide contributors — our own text (SKILL.md, guide/, references/, scripts/, this README) is Apache-2.0; bundled third-party content is documented in NOTICE.md.