DSH Plugins

Custom skills, plugins, and tools for DeepSeek Harness (DSH), maintained by sredevopsorg.

DSH loads three kinds of extension:

Kind	What it is	Where it lives here
Skill	A SKILL.md (or flat <name>.md) instruction bundle discovered from a skills root and loaded on demand by the model or with /name.	skills/
Plugin	A Cordis plugin package loaded into a DSH profile (dsh plugin …).	plugins/ — none yet
Tool	A model-facing tool registered by a plugin via ctx.tools. Usually shipped inside a plugin package.	plugins/<name>/ — none yet

Verified against @deepseek-ai/dsh 0.2.x (0.2.0-rc.2). The CLI version gate is strict, so check dsh --version before reporting plugin issues.

---

Contents

Skills

Skill	Surface	Use it for
software-architecture	model + user	Choosing the simplest sufficient design, patterns to apply or skip, engineering practices, tool/skill selection
fullstack-development	model + user	Container-based Python and Node.js/TypeScript backends, frontends, monorepos, Docker, e2e testing
supabase	model + user	Anything touching Supabase: DB, Auth, Edge Functions, Realtime, Storage, CLI, MCP, logs, debugging
supabase-postgres-best-practices	model + user	Postgres schema, migrations, RLS, indexes, locking, query plans — load before touching a database
ghost-theme-development	model + user	Authoring Ghost Handlebars themes: templates, contexts, helpers, settings, routing, GScan
ghost-theme-modern-frontend	model + user	Wiring a Ghost theme to Vite, Tailwind CSS, and React/Vue/Svelte islands

Plugins and tools

No plugin or tool packages are published from this repository yet. The intended layout is described in Plugins and tools.

---

Repository layout

.
├── README.md
├── LICENSE
├── NOTICE.md                              # third-party attribution
├── install.sh                             # register skills with a DSH skill root
├── .shellcheckrc
├── scripts/
│   └── validate-skills.mjs                # frontmatter contract check (CI)
├── .github/workflows/ci.yml
├── docs/
│   └── ghost-themes.md                    # repo doc — NOT a skill
└── skills/
    ├── software-architecture/
    │   └── SKILL.md
    ├── fullstack-development/
    │   └── SKILL.md
    ├── supabase/
    │   ├── SKILL.md
    │   ├── references/
    │   └── assets/
    ├── supabase-postgres-best-practices/
    │   ├── SKILL.md
    │   └── references/                    # one file per rule + _sections/_template/_contributing
    ├── ghost-theme-development/
    │   ├── SKILL.md
    │   └── references/
    └── ghost-theme-modern-frontend/
        ├── SKILL.md
        ├── references/
        └── scripts/                       # scaffold-theme.mjs, verify-theme.sh

A skill directory may carry any supporting files — references/, scripts/, assets/ — because the whole directory is the skill's resource base.

---

Requirements

• DSH — npx @deepseek-ai/dsh …, or a global dsh install (@deepseek-ai/dsh).
• Node.js ≥ 18 and npm/npx — for the Ghost toolchain scripts and for npx gscan.
• Ghost 6.x + gscan — only for the two Ghost theme skills.
• pnpm — only when installing DSH plugin packages (dsh plugin … forwards to pnpm).

---

Installing the skills

DSH's filesystem skill provider scans these roots, in precedence order:

Rank	Root
100	<projectRoot>/.dsh/skills
200	<projectRoot>/.agents/skills
300	customSkillDirs (configured)
400	~/.dsh/skills
500	~/.agents/skills

<projectRoot> is the nearest ancestor containing .git.

This repository's skills/ directory is not one of those roots, so cloning alone does not register anything. Pick one of the options below.

Option A — install.sh (recommended)

./install.sh                                   # all skills -> ~/.dsh/skills
./install.sh --project /path/to/your/project   # -> <project>/.dsh/skills (rank 100)
./install.sh ghost-theme-development \         # only a subset
             ghost-theme-modern-frontend
./install.sh --dry-run                         # show what would change
./install.sh --uninstall                       # detach again

It links each skill by symlink, skips anything that is not a managed link, and refuses to overwrite real files. After installing into the user root, restart DSH so the catalog is rebuilt.

Option B — manual symlinks

# into a project (rank 100)
PROJECT=/path/to/your/project
mkdir -p "$PROJECT/.dsh/skills"
for d in skills/*/; do
  [ -f "${d}SKILL.md" ] || continue
  ln -sfn "$PWD/${d%/}" "$PROJECT/.dsh/skills/$(basename "$d")"
done

# or into the user root (rank 400), available from every project
mkdir -p ~/.dsh/skills
for d in "$PWD"/skills/*/; do
  [ -f "${d}SKILL.md" ] || continue
  ln -sfn "${d%/}" ~/.dsh/skills/
done

Option C — configure customSkillDirs

Point the filesystem provider at this repository's skills/ directory in your profile's cordis.patch.yml:

- name: '@deepseek-ai/dsh-skill-filesystem'
  config:
    customSkillDirs:
      - /absolute/path/to/dsh-plugins/skills

The provider watches roots, so new, renamed, or deleted skills appear without restarting DSH. Restart DSH after changing customSkillDirs itself, since that is plugin configuration.

Using a skill

• Model-invoked — skills with modelInvocable appear in the session catalog; the agent calls the skill tool with the exact kebab-case name before acting.
• User-invoked — type / in the composer and pick a skill, or type /software-architecture directly.

install.sh deliberately skips docs/ghost-themes.md and any _- or .-prefixed entry, so repository documentation is never registered as a skill.

---

Quick start — Ghost theme toolchain

scaffold-theme.mjs generates a GScan-clean theme wired for Vite, optional Tailwind, and optional React islands. It needs only plain Node ≥ 18.

# Scaffold a Vite + Tailwind + React-islands theme
node skills/ghost-theme-modern-frontend/scripts/scaffold-theme.mjs \
  --name my-theme --out ./themes --react

cd themes/my-theme
npm install
npm run build
npm test          # build + GScan

# Fuller pre-flight: build → GScan → zip → archive assertions
bash "$OLDPWD/skills/ghost-theme-modern-frontend/scripts/verify-theme.sh" .

node skills/ghost-theme-modern-frontend/scripts/scaffold-theme.mjs --help

Flags: --name, --out, --react, --no-tailwind, --force.

---

Authoring a skill

Create skills/<kebab-case-name>/SKILL.md (directory bundle) or skills/<kebab-case-name>.md (flat file). A directory bundle may include any supporting files; nested **/SKILL.md files are not discovered.

Frontmatter:

---
name: my-skill                     # required — must match the kebab-case directory/file name
description: >-                    # required — shown in the catalog, capped (~500 chars)
  One paragraph on what the skill does and when it should trigger.
whenToUse: >-                      # optional — extra routing guidance
  Use when …
metadata:                          # optional, free-form
  author: sredevopsorg
  version: "1.0.0"
disable-model-invocation: false    # optional — keep out of model-facing catalogs
user-invocable: true               # optional — keep out of `/` commands
---
# Skill title

Instructions…

Rules the provider enforces:

• name and description are mandatory; a skill missing either is dropped.
• *invocable keys accept YAML booleans and true/false, yes/no, on/off, 1/0. A rejected spelling drops the whole skill with a warning.
• Prefer disable-model-invocation: true for human-only workflows and user-invocable: false for model-only ones.
• Keep description trigger-focused — it is the only thing the model sees before loading the body.

Conventions used in this repo:

• One skill per concern; put long material in references/ and load it from SKILL.md.
• Frontmatter first line, fenced by ---; no BOM, no leading blank line.
• The name must match its directory (or flat-file) name exactly — scripts/validate-skills.mjs enforces this.
• Scripts live in scripts/, are dependency-light, and document --help.
• Cite upstream sources in the body when guidance is derived from official docs.

Run node scripts/validate-skills.mjs before committing; see Verifying.

---

Plugins and tools

A DSH plugin is an npm package that Cordis loads; a bundle additionally declares its patch layer:

{
  "name": "@sredevopsorg/dsh-<name>",
  "type": "module",
  "main": "lib/index.js",
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" }
  }
}

Install and select it into a profile:

dsh plugin --profile web add <package-spec>      # pnpm args are forwarded
dsh plugin --profile web list
dsh --profile web --dump-config                   # inspect the composed tree, no boot

Conventions this repository will follow once plugins land:

plugins/<name>/
├── package.json          # dsh.bundle.patch when it is a bundle
├── cordis.patch.yml      # plugin rows / config
├── src/index.ts
└── README.md             # configuration table + observable behavior

Model-facing tools are registered from a plugin via ctx.tools; they should declare a JSON-schema input, fail with actionable messages, and never leak stack traces.

---

Verifying

node scripts/validate-skills.mjs            # frontmatter contract; exits 1 on errors
node scripts/validate-skills.mjs --json     # machine-readable results
node scripts/validate-skills.mjs --strict   # warnings become failures

validate-skills.mjs reproduces the checks DSH's filesystem provider makes at discovery, where a malformed skill is dropped with only a log line. It enforces the frontmatter contract and flags nested SKILL.md files, duplicate names, unknown keys, and descriptions the catalog will truncate. CI runs it on every push and pull request.

Beyond the validator:

• dsh --version matches the peer range you target.
• Start a session and confirm the skill appears in the catalog (/ in the composer lists user-invocable skills).
• Load it once by exact name to confirm the body parses and the resource paths resolve.
• For plugins: dsh --profile <name> --dump-config composes without booting.
• For Ghost themes: bash skills/ghost-theme-modern-frontend/scripts/verify-theme.sh <theme-dir>.

---

Contributing

1. Branch from main; keep one concern per branch.
2. Add or update the skill/plugin and this README's catalog table in the same change.
3. Run node scripts/validate-skills.mjs — CI runs it too, and a malformed skill is invisible until discovery.
4. Verify the skill loads in a real DSH session (frontmatter errors are only visible at discovery).
5. Keep shell scripts shellcheck-clean and preserve their executable bits.
6. Never commit secrets, tokens, personal paths, or session data.

---

Provenance and license

Released under the MIT License. Third-party attribution is listed in NOTICE.md.

• supabase and supabase-postgres-best-practices are derived from Supabase's published agent skills (MIT). Metadata is preserved in each SKILL.md.
• ghost-theme-development and ghost-theme-modern-frontend are grounded in the official docs.ghost.org documentation and the MIT-licensed community reference theme christopher-b/vapour.