简体中文 # 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 sh dsh plugin --profile demo add github:JohnXu22786/skill-framework ### Option A: Install from a local package (recommended) sh # 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) sh 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) sh # 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: sh # 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): yaml - 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 sh 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.