简体中文

docgen — Document Workshop skill pack

A set of document-generation skills in pure prompt (Agent Skills) form, providing four capabilities for plugin-based agent harnesses such as dsh: README generation, PR description generation, changelog generation, and code review. All skills follow the Agent Skills open standard (SKILL.md + YAML frontmatter), are self-contained, have no third-party dependencies, and work offline.

Included skills

| Skill | What it does | When to use | |---|---|---| | readme-forge | Generate/rewrite README.md from a codebase, writing only content backed by evidence | "Write a README for this project" | | pr-dossier | Generate a complete PR description (change dossier) from a diff and commit history | "Write a PR description for this change" | | changelog-curator | Categorize, merge, and rewrite git history into a CHANGELOG | "Update the changelog and get ready for release" | | diff-verdict | Output structured review opinions: verdict + graded issue list + highlights | "Review this PR" |

Each skill is a self-contained single SKILL.md: the body contains input-collection guidance, a workflow, output templates with a template-variable table, language-style options, an output-quality checklist, a "don't" list, and edge-case handling.

Directory structure

docgen/
├── README.md                     # this document: installation, usage, interface
├── package.json                  # npm manifest: name (dsh-docgen) + dsh.bundle
├── cordis.patch.yml              # bundle patch consumed by `dsh plugin` installs
├── index.js                      # skill-mount adapter (registers skills/ onto ctx.skills)
├── manifest.json                 # plugin manifest (self-describing metadata)
├── SKILLS.md                     # entry index file
├── LICENSE                       # MIT license
├── skills/                       # skills root (point here or copy entries when integrating)
│   ├── readme-forge/SKILL.md
│   ├── pr-dossier/SKILL.md
│   ├── changelog-curator/SKILL.md
│   └── diff-verdict/SKILL.md
├── examples/
│   ├── prompts.md                # example invocation prompts for each skill
│   └── dsh-patch-enable-skills.yml  # example dsh integration patch (enables skills in web profile + registers directory)
├── scripts/
│   └── validate_skills.py        # skill-pack validation script (Python standard library, no dependencies)
└── tests/
    ├── test_validate_skills.py   # regression tests for the validation script
    └── index.test.mjs            # node smoke tests for the skill-mount adapter

Installing in DSH

docgen ships a dsh.bundle manifest, so it installs and activates with the plugin loader:

dsh plugin --profile demo add github:JohnXu22786/docgen

The bundle inserts a plugin row (id: docgen, name: dsh-docgen) that resolves this package's entry (index.js); its apply(ctx) scans the bundled skills/ directory and registers every SKILL.md onto ctx.skills at runtime — no copying, no extra config. The file-based integration paths below remain available for harnesses or profiles where the skills service or skill components are not loaded.

Installation and dsh integration

dsh discovers skills through the skill-filesystem provider by skills root directory (one level deep: directory bundles <root>/<name>/SKILL.md or flat files <root>/<name>.md). Pick any one of the following ways to integrate this pack:

Way zero: plugin loader (dsh.bundle, recommended)

dsh plugin --profile demo add github:JohnXu22786/docgen

The bundle's entry (index.js) registers the four skills/ entries onto ctx.skills at load time. This is the one-step path; the ways below are for manual or file-based integration.

Way one: project-level (zero config, no plugin loader)

Put the four skill directories under skills/ (or the whole skills/) into the project's skills root:

# Any of these in the project root (the nearest ancestor containing .git):
#   <project>/.dsh/skills/    or   <project>/.agents/skills/
cp -r skills/* <project>/.dsh/skills/

Way two: user-level (available in all projects)

# $DSH_HOME defaults to ~/.dsh; $DSH_AGENTS_HOME defaults to ~/.agents
cp -r skills/* ~/.dsh/skills/

Way three: custom directory (in-place integration of the plugin, no copying)

Register customSkillDirs for the skill-filesystem provider via configuration, e.g. with a patch file (see examples/dsh-patch-enable-skills.yml):

npx @deepseek-ai/dsh web --patch ./examples/dsh-patch-enable-skills.yml

Note: dsh's web profile disables skill-related components by default (skill-filesystem / tool-skill); enable them with a patch or preset. The headless profile has them enabled by default. The exact config key paths depend on your installed version — check dsh --dump-config and the official docs.

Verifying the installation

python scripts/validate_skills.py            # validates this pack's skill format (exit code 0 when all pass)
python scripts/validate_skills.py --strict   # additionally checks the body line-count cap
python -m unittest discover -s tests -t .    # runs the validation script's own regression tests
npm test                                     # runs the skill-mount adapter's node smoke tests

After integration, just make natural-language requests in a session and the model loads the matching skill via the skill tool:

Write a README for this project
Generate a PR description for the change I just made
Update the changelog from git history and prepare 1.2.0
Help me review this PR

Usage

• Triggering: describe the need naturally in your prompt (see the "When to use" column of the skill table); you don't need to remember skill names. The harness routes automatically based on description / whenToUse.
• Style options: each skill supports three overridable dimensions — language (defaults to the language of the prompt), length (concise/standard/detailed or full), and tone/depth. Just append them in natural language: length=concise, focus=security, language=en.
• Output shape: skills produce markdown text directly; README/changelog-type skills give complete content you can save to a file as-is, while PR/review-type skills give structured descriptions or opinion lists.
• Example prompts: see examples/prompts.md.

Interface

Skill interface (dsh native contract)

Each skill is a directory bundle whose SKILL.md frontmatter is the only contract the harness reads:

| Field | Required | Constraints | Usage in this pack | |---|---|---|---| | name | yes | kebab-case (lowercase letters/digits/hyphens), ≤ 64 chars, identical to the containing directory name | see each skill | | description | yes | non-empty, ≤ 1024 chars, states what it does + when to use + trigger keywords | Chinese description + English keywords | | whenToUse | no | string, extra routing hint (community-established camelCase extension field) | provided by every skill | | metadata | no | string key-value map | author / version / family | | license | no | string | MIT | | compatibility | no | string, environment requirements | pure prompts, no network needed | | allowed-tools | no | string, pre-approved tool list (experimental) | unused |

dsh additionally recognizes (not written in this pack, defaults apply): disable-model-invocation and user-invocable (both open by default). Note: field names must be spelled exactly as in the table — allowed-tools contains a hyphen, and whenToUse is the established camelCase spelling; inconsistent spellings (e.g. writing allowed_tools or when-to-use) cause the field to be unrecognized; if an invocation-policy field is misspelled or mis-typed, dsh drops the entire skill (fail-closed).

Plugin manifest and entry

• package.json + cordis.patch.yml: the dsh.bundle manifest consumed by dsh plugin add. During install, dsh reads cordis.patch.yml, inserts the docgen plugin row, and loads index.js — whose apply(ctx) registers the bundled skills onto ctx.skills (name / description / whenToUse / content / metadata / source: bundled) and returns a disposer that unregisters them on unload.
• manifest.json: the plugin's self-describing metadata (id / version / kind / entry / interface / skills / scripts). dsh's skill discovery does not read it; it serves human reference, publishing flows, and harnesses that support "entry file" style loaders; the interface field declares the skill-discovery contract.
• SKILLS.md: entry index listing the loading-contract summary and the skill list.

How dsh loads skills (summary)

dsh's skill capabilities are provided by three plugins working together — skill (registry), skill-filesystem (local discovery), and tool-skill (model catalog and skill tool): at startup it scans the root directories' frontmatter to build a catalog (the model only sees name + description); when the model decides to call a skill it reads the latest body by name; relative references in the body resolve against the skill directory. All four skills in this pack are single-file self-contained and do not depend on relative resources.

Development and extension

• Adding a skill: create a new directory + SKILL.md under skills/ (frontmatter per the table above), run python scripts/validate_skills.py until it passes, and update manifest.json and SKILLS.md accordingly.
• Modifying a skill: only edit the corresponding SKILL.md; the harness reads the new content on the next load (body changes need no catalog-cache restart).
• Validation script: scripts/validate_skills.py uses only the Python standard library and can be used standalone on any skill pack; it accepts arbitrary directories/files. Its parsing scope is a flat YAML subset (top-level key-values + metadata indented maps + quoted/list literals), without anchors, comments, or other full-YAML features.

Dependencies and privacy

• Zero third-party dependencies: pure prompts + a Python standard-library script;
• No network requests, no data collection; the only capabilities required are reading codebase files and git history (provided by the harness);
• License: MIT, see LICENSE.

FAQ

• Skills not visible in the web UI? The dsh web profile disables skill components by default; enable them with the Way-three patch (or use the CLI/headless profile).
• Changed SKILL.md but no effect? Skill bodies are read per invocation — just send a new request; if you changed the frontmatter name/description, the catalog refreshes via filesystem watching.
• Name collision with an existing skill? dsh resolves same-name skills by root-directory priority and layer proximity; all skill names in this pack are original — if there is a conflict, first check whether a same-name skill is already installed.

---

License

MIT — see LICENSE.