| name | docmd-dev |
| description | Use this skill when contributing to the docmd framework itself — working in the cloned `docmd/` monorepo. Covers plugin authoring, template authoring, engine loaders, the public Node API, and the hooks/action system. docmd is Node.js and TypeScript only, so it enforces a security and quality gate (see the security-and-regression-checklist reference) before any framework change ships. |
| audience | developer |
| load_command | docmd-skills dev <dir> |
| version | 1.1.0 |
| verified_against | {"docmd":"0.8.7","node":">=20","dev_node":">=24","tested_on":"2026-06-19T00:00:00.000Z"} |
| repository | https://github.com/docmd-io/docmd-skills |
| docs | https://docs.docmd.io |
| llms_context | https://docs.docmd.io/llms-full.txt |
| siblings | [{"name":"docmd-skills","when":"building, configuring, or operating a docmd site"},{"name":"docmd-writer","when":"writing or reviewing the prose inside a docmd site"}] |
docmd — Agent Skill (Developer)
Use this skill when the user wants to modify the docmd framework itself, not a site that consumes it. This skill is loaded by npx docmd-skills dev <dir> and adds docmd-dev/ alongside an existing docmd-skills/ install.
When to use this skill
Use it when any one of these signals is true:
- The user's current working directory is a clone of the docmd monorepo. The local clone directory is named just
docmd/ (the GitHub path is docmd-io/docmd/). Telltale markers: pnpm-lock.yaml, packages/core/src/, packages/ui/src/, packages/api/src/, packages/plugins/<name>/, packages/engines/. To clone it: git clone https://github.com/docmd-io/docmd.git docmd && cd docmd.
- The user explicitly says they want to "write a plugin", "write a template", "extend the engine", "modify the core", "add a hook", or similar.
- The user is editing files inside
packages/core/src/, packages/api/src/, packages/ui/src/, packages/plugins/*/src/, or packages/engines/*/ of the docmd monorepo.
If the user wants framework help but no docmd/ clone exists in the working directory, ask before doing anything: would they like you to clone the monorepo (git clone https://github.com/docmd-io/docmd.git docmd) or refresh an existing one (git -C docmd pull)? Do not start editing framework source without an up-to-date local clone.
Do not use it for: site-level configuration or operations (use docmd-skills), or for page-prose quality (use docmd-writer).
Loading rules
- Only load this skill when the user is actively working inside the docmd monorepo or asks explicitly about framework internals.
- When in doubt, default to docmd-skills (user). Switching to this skill implies the user is comfortable running
pnpm commands against the monorepo.
Reference index
Each row is a reference file. The CLI column shows which install subcommand adds this file.
| Reference | CLI install subcommand | Use it for |
|---|
references/api-dev.md | docmd-skills dev | Public Node API for framework authors: EngineLoader, URL utilities, createActionDispatcher, TemplateSlot, hook/action contracts |
references/plugin-development.md | docmd-skills dev | Authoring a docmd plugin: package shape, manifest, apply() lifecycle, template capability, hooks, testing |
references/template-development.md | docmd-skills dev | Authoring a docmd theme/template: 12 template slots, asset pipeline, manifest.json, template plugins |
references/engines.md | docmd-skills dev | JS vs Rust build engines, swapping engines, engine-specific config, performance trade-offs |
references/security-and-regression-checklist.md | docmd-skills dev | docmd-specific security and quality gate: container parser invariants, plugin HTML-injection contract, public API honesty, i18n/versioning silent-failure rules, deploy/Docker hardening, migration correctness, CLI honesty, loud fallbacks. Load before any framework change ships. Builds on ai-dev's nodejs-cautions.md and security-must-checks.md. |
Workflows
1. Cloning or refreshing the monorepo
No clone yet — clone and install:
git clone https://github.com/docmd-io/docmd.git docmd
cd docmd
pnpm install
Existing clone — refresh and re-install dependencies if needed:
git -C docmd pull
pnpm install
To check whether a clone is behind before deciding, run git -C docmd status (look for "Your branch is behind") or git -C docmd log -1 --oneline and compare to https://github.com/docmd-io/docmd/commits/main.
The local clone directory is docmd/ (not docmd-io/docmd/). Inside it you will find the canonical package layout referenced throughout this skill.
2. Writing a plugin
- Read
references/plugin-development.md end-to-end before scaffolding.
- Pick the closest existing plugin under
packages/plugins/<name>/ and copy its shape.
- Cross-check
references/api-dev.md for the Plugin type, hook names, and the template capability introduced in 0.8.7.
- Add tests under the plugin's own
tests/; the monorepo's pnpm prep runs the universal failsafe.
3. Writing a template
- Read
references/template-development.md for the 12 template slots and the asset pipeline.
- Match the manifest shape used by an existing template (
packages/templates/summer/ is the reference).
- Validate against
references/api-dev.md for the TemplateSlot union (no header slot — there are 12).
4. Engine work
references/engines.md first — confirms which engine you're targeting and its config keys.- For Node-level changes to the engine loader,
references/api-dev.md § "Engine Loader API".
5. Hard checks before any framework change ships
docmd is Node.js and TypeScript only, so the generic Node rules always apply. Run this gate before declaring a framework change done:
- Generic Node triage from
ai-dev: references/nodejs-cautions.md §1.1 grep checklist, the Appendix 5-minute review, and Part 12 (contract honesty and silent failures).
ai-dev references/security-must-checks.md Rules 1 to 7, with docmd's common-miss spots in mind (plugins, MCP tools, container blocks, deploy templates).references/security-and-regression-checklist.md — run every section that touches the area you changed. This is the docmd-only layer and the direct output of the v0.8.x battle test (battle-test-reports/unified-issues.md).pnpm prep for anything non-trivial.- One regression test per bug class fixed, named after the report ID where possible.
If any MUST in those references is unresolved, the change is not done.
Cross-skill navigation
- docmd-skills — for site-level work; load it as the default first.
- docmd-writer — load it when the task drifts into prose quality inside template demos or example docs.
