# ๐งฉ dsh-skills-manager
**Proactive skill activation, hook orchestration, and GitHub sync for DeepSeek Harness.**
English ยท
็ฎไฝไธญๆ
[](https://www.npmjs.com/package/@existence001100/dsh-skills-manager)
[](https://github.com/Existence001100/dsh-skills-manager/actions/workflows/ci.yml)
[](./LICENSE)
[](https://nodejs.org/)
[](https://github.com/Existence001100/dsh-skills-manager/commits/main)
[](https://github.com/Existence001100/dsh-skills-manager/stargazers)
**๐ Quick install**
```sh
dsh plugin --profile web add @existence001100/dsh-skills-manager
```
Restart the Web profile after installation. See [requirements and installation options](#quick-start).
> **Changed in 1.1.1:** a model-initiated `skill_manager install` or `skill_manager update` now needs one approval decision. To restore the 1.0.x behavior, run `skill_manager set-config config={"installGate":"off"}`. See [install consent gate](#install-consent-gate).
[๐ Installation](#quick-start) ยท [โจ Features](#highlights) ยท [โ๏ธ Configuration](#skill-configuration) ยท [๐ Feedback](https://github.com/Existence001100/dsh-skills-manager/issues)
## Table of contents
- [Why this plugin](#why-this-plugin)
- [Highlights](#highlights)
- [How it works](#how-it-works)
- [Quick start](#quick-start)
- [Compatibility](#compatibility)
- [Skill configuration](#skill-configuration)
- [Hook compatibility](#hook-compatibility)
- [GitHub-managed skills](#github-managed-skills)
- [Install consent gate](#install-consent-gate)
- [Candidate catalog](#candidate-catalog)
- [Project-scoped skills](#project-scoped-skills)
- [Management and observability](#management-and-observability)
- [Permissions and data](#permissions-and-data)
- [Security](#security)
- [Decisions we deliberately do not make](#decisions-we-deliberately-do-not-make)
- [Development](#development)
## Why this plugin
The built-in DSH `skill` tool relies on the model to notice a short summary and decide to load the full skill. In practice, useful skills are often missed, skill files cannot directly declare lifecycle behavior, and locally scattered skills are difficult to keep synchronized.
`dsh-skills-manager` closes those gaps:
- matches every user turn against available skills;
- loads strong matches automatically and suggests weaker matches;
- maps Claude Code-style hook declarations onto DSH host events;
- manages skill sources from GitHub;
- keeps user and project overrides isolated;
- exposes controls in Settings and through the `skill_manager` model tool.
## Highlights
| Icon | Capability | Description |
| --- | --- | --- |
| ๐ | Proactive activation | Full skill injection for strong matches and lightweight reminders for suggestions |
| ๐ช | Skill-level hooks | `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, and `SessionStart` |
| ๐ | GitHub lifecycle | Install, update, authoritative sync, uninstall, and commit-change reporting |
| ๐งญ | Workspace-aware scope | Project skills override user skills without leaking configuration between workspaces |
| ๐ ๏ธ | Built-in management | Settings UI plus the `skill_manager` model tool |
| ๐ | Install consent gate | A model-initiated `install` or `update` asks once. It fails closed without an approval channel. |
| ๐งฉ | Capability proposal | An opt-in catalog proposes missing skills. One card per turn. It never auto-installs. |
| ๐ก๏ธ | Guardrails | Source allowlisting, argument-array Git execution, hook path validation, and no shell execution for hooks |
## How it works
```mermaid
flowchart LR
U[User message] --> M[Pre-step matcher]
M -->|auto| A[Inject full skill]
M -->|suggest| S[Inject reminder]
M -->|gap| P2[Candidate catalog]
P2 -->|opt-in| PR[Inject proposal]
T[Tool call] --> P[PreToolUse policy]
R[Tool result] --> O[PostToolUse activation]
I[Model calls install/update] --> G{Install gate}
G -->|allowed-once| Y[Git clone or fetch]
G -->|rejected / unavailable| D[Deny with degradation]
Y --> C[DSH skill catalog]
C --> M
```
Before each agent step, the plugin scores available skills:
1. explicit skill-name mention: **+12**;
2. trigger phrase or regular expression: **+7**;
3. description or `whenToUse` token overlap: **+4 to +6**.
By default, a turn can auto-load up to two skills and suggest up to three. Activation markers are stored in conversation history, so full skill content is not injected repeatedly while it remains visible. After context compaction removes a marker, the skill can be loaded again automatically.
Two separate constraints keep the model from acting on its own:
- **Install consent gate.** Before a model-initiated `skill_manager install` or `skill_manager update` runs any Git command, the plugin asks the host approval seam for one decision. Only `allowed-once` proceeds. Rejection, cancellation, a missing channel, or a thrown request all deny. The model receives a degradation note and a structured code (see [Install consent gate](#install-consent-gate)).
- **Capability proposal.** When an opt-in candidate catalog names sources that are not installed, the matcher may inject a proposal into the turn's first step. The proposal is model context, not a UI card, and it never installs anything on its own โ the model must still call `install`, which the gate above will intercept. The branch is off by default and stays silent when the catalog is missing, the score is low, or every declared skill is already installed (see [Candidate catalog](#candidate-catalog)).
## Quick start
### Requirements
- DeepSeek Harness `0.1.1-rc.2`, `0.1.2-alpha.3`, `0.1.3-alpha.1`, or `0.2.0-rc.2`;
- Node.js `^22.19.0 || >=24.0.0`;
- pnpm available on `PATH` for `dsh plugin`.
### Install from npm (recommended)
```sh
dsh plugin --profile web add @existence001100/dsh-skills-manager
```
DSH recognizes the package's `dsh.bundle` manifest and adds `@existence001100/dsh-skills-manager` to the Web profile automatically. Restart a running Web profile after installation.
### Install from GitHub
```sh
dsh plugin --profile web add github:Existence001100/dsh-skills-manager
```
Use the GitHub source when testing unreleased changes from `main`. Pin a commit when reproducibility matters.
### Update or remove
```sh
dsh plugin --profile web update @existence001100/dsh-skills-manager
dsh plugin --profile web remove @existence001100/dsh-skills-manager
```
Restart the profile after either operation so its composition matches the installed bundle set.
### Install a local checkout for development
```sh
git clone https://github.com/Existence001100/dsh-skills-manager.git
cd dsh-skills-manager
pnpm install --frozen-lockfile
dsh plugin --profile web add .
```
The included `cordis.patch.yml` inserts `skill-manager` into the host composition for all sessions.
## Compatibility
| Component | Supported or continuously verified |
| --- | --- |
| DeepSeek Harness | `0.1.1-rc.2` dependency contract; `0.1.2-alpha.3` dependency contract plus isolated install and UI smoke tests; `0.1.3-alpha.1` tagged-source API review and session-hook regression tests; `0.2.0-rc.2` isolated install, Web boot, Settings API, and live `/name` skill invocation |
| Node.js | `22.19.0` and `24.19.0` |
| pnpm | `11.19.0` with a frozen lockfile |
| Operating systems | Ubuntu and Windows CI matrix |
The `0.1.3-alpha.1` adaptation supports `session.snapshotEvents()` and array-based surface nodes while retaining the legacy events API. Full install/UI smoke testing for that release is pending availability of its host packages on npm.
For DSH `0.2.0-rc.2`, use plugin `1.0.6` or later: older plugin versions emit `source.kind: "plugin"`, which DSH's v4 session format rejects. A live Web-profile test invoked `/ponytail-help`, loaded its full instructions (`skill-invocation`), recorded the manager notice as `plugin:dsh-skills-manager`, and completed the turn. This verifies explicit skill invocation and manager injection; other `0.2.x` host versions are outside the current peer range.
DSH is in developer preview. Pin the plugin to a commit when reproducibility matters, and re-run the install smoke test when upgrading DSH dependencies.
## Skill configuration
Declare activation and hooks directly in SKILL.md frontmatter:
```yaml
---
name: repo-hardening
description: Review and harden a repository with build/test gates.
metadata:
activation: auto # auto | suggest | off
triggers:
- "harden"
- "build fails"
- "re:exit code \\d+"
hooks:
UserPromptSubmit:
inject: "Run build and tests before reaching a conclusion."
PreToolUse:
- tool: bash
when: "git push" # substring or re: