dsh-review-skills

Readme

# dsh-review-skills

**Engineering-discipline skill pack for DeepSeek Harness** — five battle-tested procedures delivered as a bundled skill provider: code review, simplification, plan-then-execute, test-first, and conflict resolution.

## Overview

dsh-review-skills packages the discipline that senior engineers apply by habit into model-visible skills. Once installed, the harness discovers five `SKILL.md` bundles through the standard `ctx.skills` registry and can invoke them when a task matches.

**The skills**

| Skill | When to use |
|---|---|
| `code-review` | Before merging: review a diff for correctness, test coverage, edge cases, needless complexity, and security. Produces severity-ranked findings. |
| `simplify` | After a change lands: find and remove accidental complexity — clearer names, fewer layers, less code that does the same thing. |
| `plan-then-execute` | Before implementing anything non-trivial: write a plan, get it accepted, then execute it. |
| `test-first` | TDD discipline: red → green → refactor, with honest tests and no fake green. |
| `resolve-conflict` | When a merge or rebase hits conflicts: understand both sides, resolve deliberately, verify. |

**Who is it for?**

- Solo developers who want a senior-engineer checklist without hiring one.
- Teams that want consistent review and planning standards across sessions.
- Anyone building on the dsh skill system who wants a reference-quality skill pack to copy.

## Compatibility

- Built and verified against `@deepseek-ai/dsh@0.1.0-rc.6` / `@deepseek-ai/cordis@^4.0.1` / `@deepseek-ai/dsh-skill@^0.1.0-rc.6`.
- **Last verified:** 2026-08-14.
- Requires a dsh composition that mounts the `ctx.skills` service (the `dsh-base` bundle ships it).
- dsh is in developer preview; the skill frontmatter contract (`name` / `description` / `whenToUse` / invocation flags) may evolve. The included unit tests pin the format this pack targets.

## Install / Uninstall

Install into a dsh profile (local checkout):

```sh
cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add /path/to/dsh-review-skills
```

From GitHub (source install — pnpm runs the `prepare` script, so allow it once):

```sh
pnpm dsh plugin --profile web add github:<you>/dsh-review-skills
```

From npm (once published):

```sh
pnpm dsh plugin --profile web add dsh-review-skills
```

Uninstall:

```sh
pnpm dsh plugin --profile web remove dsh-review-skills
```

## Quick start

Install the bundle, restart dsh, then simply ask:

```text
Use the code-review skill on the current diff before we merge.
```

or mention a skill by name in context:

```text
Plan-then-execute: refactor the auth module, then implement.
```

The harness resolves the skill through `ctx.skills` and injects its procedure when the model invokes it.

## Configuration

None. The plugin registers its provider with no config; the skills and their routing metadata live in `skills/*/SKILL.md` frontmatter (`name`, `description`, `whenToUse`, `disable-model-invocation`, `user-invocable`).

## Permissions & data

- **Read-only:** the plugin reads its own packaged `skills/` directory; it writes nothing and touches no user files.
- **No network:** all five skills are static Markdown bundled in the package.
- **Model-visible content:** skill bodies are injected into the model context only when the skill is invoked, per the harness skill catalog policy.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Skills not discoverable | `ctx.skills` service not mounted in the composition | Verify the profile loads `dsh-base` (which ships the skill service) |
| `missing YAML frontmatter` at boot | A packaged `SKILL.md` lost its `---` block | Rebuild/reinstall; the tests (`pnpm test`) catch this before publish |
| Skill does not apply to the conversation | The model decided it was not relevant | Ask explicitly: "use the code-review skill" |
| Stale skill content | Old `lib/` after editing `skills/` | Rebuild (`pnpm run build`) and reinstall; skill bodies load lazily from disk |

## Development

```sh
pnpm install
pnpm run build         # tsc → lib/
pnpm run test          # vitest: frontmatter contract + 5 bundled skills present
```

Structure:

- `skills/<name>/SKILL.md` — one skill per directory; frontmatter drives routing, body carries the procedure.
- `src/skills.ts` — frontmatter parser and the bundled provider (lazy body loading).
- `src/index.ts` — plugin entry registering the provider on `ctx.skills`.
- `tests/` — pins the frontmatter contract and asserts all five bundles are parseable.

Design notes:

- Follow the existing skill-file conventions in the dsh repo (`@deepseek-ai/dsh-skill` types: `SkillCandidate`, `SkillDefinition`, `SkillProvider`) — this pack mirrors the `dsh-skill-badge` precedent.
- Keep each skill body focused: when-to-use, procedure steps, pitfalls, verification. A skill that tries to cover everything covers nothing.

## License & security

MIT. Report security issues privately via the repository's security advisory. The pack ships static Markdown only; it executes no code of its own.