简体中文

dsh-praxis

Praxis is an engineering-methodology skill library plugin for DeepSeek Harness (dsh): it hardens senior engineer workflows (design conversations, writing plans, executing plans, test-first, system debugging, completion verification, parallel division of labor, code review, branch conclusion, etc.) into a set of SKILL.md skills conforming to the Agent Skills open standard, wired into dsh's skill system as a self-contained plugin.

• Plugin form: dsh bundle (dsh.bundle declaration in package.json + cordis.patch.yml patch line)
• Capability interface: Cordis plugin → ctx.skills skill provider → the platform's built-in dsh-tool-skill consumer → model-visible skill catalog and skill loading tool
• Skill format: Agent Skills standard (SKILL.md + YAML frontmatter), fully compatible with dsh's local skill discoverer (dsh-skill-filesystem)

Skills

Skill	Trigger scenario	Group
method-compass	Starting any task: understand the skill library, pick the first skill	meta
design-conversation	Requirements are vague, multiple options, design undecided—converse before coding	planning
implementation-blueprint	Design is settled, write an executable step-by-step plan	planning
blueprint-execution	Execute the plan: sequential steps, checkpoint validation, deviation reporting	planning
test-first-cycle	Writing any code with testable behavior: red, green, then refactor	testing
fault-isolation	Any abnormal behavior: find the root cause with evidence, not guesses	debugging
completion-proof	Before claiming "done": prove it with observable evidence	debugging
task-splitting	Parallel division of labor: split by contract, dispatch, integrate	collaboration
delegated-build	Hand a plan to a sub-agent: two rounds of review gatekeeping	collaboration
review-preflight	Before requesting review: self-check, self-test, write a good review request	review
feedback-assimilation	After receiving review feedback: digest, fix, and respond item by item	review
lane-isolation	Parallel development in the same repo: each branch has an independent working area	delivery
branch-conclusion	Full wrap-up flow before a branch completes and merges into the trunk	delivery
skill-authoring	Writing, modifying, or validating new skills	meta

Environment requirements

• DeepSeek Harness dsh ≥ 0.1.0-rc.6 (the skill capability family is enabled in the standard profile, i.e., dsh-skill and dsh-tool-skill are mounted)
• Node.js ≥ 22 (required by dsh itself; this plugin runs as pure ESM JavaScript at runtime)

Installation

Installing in DSH

dsh plugin --profile demo add github:JohnXu22786/skill-framework

Option A: Install from a local package (recommended)

# 1. Install dependencies and build in the plugin directory
npm install
npm run build

# 2. Pack (output includes lib/, skills/, cordis.patch.yml)
npm pack

# 3. Install into a dsh profile
dsh plugin --profile web add ./dsh-praxis-0.1.0.tgz

Option B: Install from a local directory (development)

dsh plugin --profile web add /absolute/path/to/dsh-praxis

When installing from a directory, the profile must authorize local builds per the dsh docs.

Option C: Development mode (source mounted directly, with a Harness source environment)

# 1. In examples/dev.patch.yml, set the value of name to the absolute path of this plugin's src/index.ts
# 2. Start (defaults to the web profile; `dsh --profile <name>` selects another profile)
dsh web --patch ./examples/dev.patch.yml

Option D: Zero-code integration (without this plugin's loader)

The skills/ directory in this repo is itself a standard Agent Skills collection; it can be dropped directly into one of dsh's local skill root directories:

# User level (applies to all projects)
cp -r skills/* ~/.dsh/skills/

# Or project level
mkdir -p .dsh/skills && cp -r skills/* .dsh/skills/

This path is loaded by dsh's built-in dsh-skill-filesystem discoverer; no need to install this plugin. The skill content is identical across both integration approaches.

Usage

No manual configuration is needed after installation: when the model encounters a trigger scenario from the skill catalog during a session, it loads the matching skill automatically. You can also specify directly in conversation, for example:

First give me an implementation plan (implementation-blueprint), then execute it (blueprint-execution).

When troubleshooting, the model prioritizes the fault-isolation workflow; before claiming completion, it provides verification evidence per completion-proof. Skills explicitly mark dependencies between each other via **REQUIRED SUB-SKILL:** praxis:xxx.

Integration notes: how the plugin is loaded by dsh

dsh startup
 └─ profile composes the plugin tree by layer
     └─ bundle layer: reads dsh.bundle.patch in package.json → cordis.patch.yml
         └─ patch inserts a plugin config line:
              - id: praxis
                name: dsh-praxis          # resolved by npm package name → main → lib/index.js
             └─ dsh loads the module's named exports { name, inject, apply }
                 └─ apply(ctx) calls ctx.skills.registerProvider(...)
                     └─ PraxisSkillProvider registered in the skill registry (rank 600, source: bundled)
                         └─ dsh-tool-skill consumer generates the skill catalog and skill loading tool
                             └─ model-visible: catalog entries (name + description) + skill body

Key points:

1. manifest: the "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } field in package.json declares this package as a bundle; dsh plugin --profile <name> add <package> activates it through that.
2. entry file: lib/index.js (build output, pointed to by main) exports the three Cordis plugin elements—name (line id: praxis), inject (service dependencies: ['skills']), and apply(ctx, config) (registers the provider). Source entry is src/index.ts.
3. skill interface: the provider implements list() (returns the candidate catalog with name, description, invocation policy, resource base) and get() (returns the full skill body for a candidate). The registry handles merging, deduplication, and validation; plugin unload automatically removes registration effects with no residual state.
4. events: this plugin is a static library and neither listens to nor emits events; registration and deregistration trigger the registry's skills/change invalidation notification, and consumers refresh the catalog accordingly.

Plugin configuration

The plugin line supports two optional config fields (written in the profile's cordis.patch.yml or a --patch overlay):

- insert:
    - id: praxis
      name: dsh-praxis
      config:
        providerName: praxis-bundled   # provider name registered on ctx.skills (default)
        skillsDir: ./skills            # skill root directory; relative paths resolve against package root; array accepted

• providerName: a non-empty string; must be unique within the same scope (duplicate registrations are rejected by the registry).
• skillsDir: one or more skill root directories. Default is <package root>/skills (registered with bundled source at rank 600; explicitly configured directories register with custom source at rank 300, consistent with the platform's custom-directory semantics). Two standard layouts are accepted within a directory: <name>/SKILL.md directory bundles, or flat <name>.md files; the frontmatter name must match the directory/file name, otherwise the entry is skipped with a warning.

Exported interfaces (programmatic use)

Besides the three plugin elements, lib/index.js exports:

Export	Description
PraxisSkillProvider	Provider class: constructed with { providerName, roots }; list() / get() follow the platform SkillProvider contract
resolveSettings(config)	Config validation and resolution (defaults, relative path resolution, argument validation)
scanLibrary(root)	Scans a skill root directory, returning entries and warnings
parseSkillDocument(raw) / splitFrontmatter(raw)	Skill document parsing and frontmatter splitting (with field validation)
SkillDocumentError、MAX_DESCRIPTION_LENGTH	Parse error type and description length cap (1024)
CUSTOM_SKILL_RANK	Registration priority constant for custom skill directories (300, matching platform docs)
PACKAGE_ROOT	Absolute path of the plugin package root (resolved at runtime)

Local development

npm install
npm run build       # tsc → lib/
npm run typecheck   # full type check of src + tests
npm test            # all tests: parser, catalog scan, provider, library integrity, real Cordis integration

Test notes:

• tests/frontmatter.test.js / catalog.test.js / provider.test.js: unit tests for parsing and discovery logic.
• tests/library.test.js: integrity checks on skills/—the skill set is fixed at 14, frontmatter is valid, directory names match name, and all cross-references resolve. This file will block you when adding or renaming skills.
• tests/integration.test.js: mounts a real @deepseek-ai/cordis + @deepseek-ai/dsh-skill to verify catalog, loading, snapshots, and duplicate-registration rejection—i.e., the runtime path by which dsh actually loads this plugin.

For new skills, follow the workflow in skills/skill-authoring/SKILL.md and keep the skill list in tests/library.test.js in sync.

Directory structure

skill-framework/
├── package.json          # manifest: dsh.bundle → cordis.patch.yml
├── cordis.patch.yml      # bundle patch layer: inserts the praxis plugin line
├── tsconfig.json         # build config (src → lib)
├── tsconfig.tests.json   # full type-check config (src + tests, checkJs)
├── examples/dev.patch.yml  # development-mode overlay example
├── src/                  # plugin source (TypeScript)
│   ├── index.ts          # plugin entry: name / inject / apply / config resolution
│   ├── provider.ts       # ctx.skills provider implementation
│   ├── catalog.ts        # skill library catalog scan
│   ├── document.ts       # document field validation
│   └── frontmatter.ts    # frontmatter splitting
├── tests/                # node:test tests (run against lib/)
└── skills/               # skill library (Agent Skills standard)
    └── <skill-name>/SKILL.md [+ references/]

License

Released under the MIT License.