Docgen

简体中文 # 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: bash 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) bash 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: bash # 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) bash # $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): bash 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 bash 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.