dsh-doc-writing
Skill282k starsChanged 3 months agoMITView on GitHub
Create, restructure, review, audit, or migrate DeepSeek Harness Markdown documentation, package READMEs, and the documentation website using audience-first hierarchy, kind-mapped YAML metadata, bilingual line alignment, summary/contents navigation, progressive user-to-developer detail, executed-operation fact-checking, and repository validation. Use for new or revised DSH docs, docs-tree organization, documentation-quality audits and budgets, website page publishing, and bilingual documentation structure changes.
Adopted by
Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data
Who's talking about deepseek-ai/deepseek-harness
- @timkellogg.me“DeepSeek Harness v0.1 the idea is everything is a plugin — models, tools, sessions, skills, sandboxes, …”Bluesky · Aug 13, 2026 · 77 likes
- pingdotgg/t3code“Is DeepSeek Harness provider support something you'd want?”GitHub · Aug 17, 2026 · 30 reactions
- farion1231/cc-switch“可以尝试兼容Deepseek Harness吗”GitHub · Aug 13, 2026 · 21 reactions
- @midu.dev“¡DeepSeek hace de código abierto su Agent Harness! 144.000 estrellas en 4 días. Todo lo cambias a base de …”Bluesky · Aug 17, 2026 · 18 likes
- Javis603/token-monitor“希望增加DSH(DeepSeek Harness)的用量统计支持”GitHub · Aug 13, 2026 · 9 reactions
The biggest 5 of 75 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 75
Talked about on GitHub, Bluesky, the web and Hacker News (75 times).
On GitHub · 50
- Aug 17, 2026Is DeepSeek Harness provider support something you'd want? — pingdotgg/t3code30 reactions · 12 comments
- Aug 13, 2026可以尝试兼容Deepseek Harness吗 — farion1231/cc-switch21 reactions · 25 comments
- Aug 13, 2026希望增加DSH(DeepSeek Harness)的用量统计支持 — Javis603/token-monitor9 reactions · 1 comment
- Aug 22, 2026`npm install -g @deepseek-harness-tui/dsh-tui` 在 npm 12 崩溃:`Cannot read properties of null (reading 'children')` — ccch1mneyyy/dsh-TUI7 reactions · 6 comments
- Aug 17, 2026Feature Request: Please add DeepSeek Harness as an Agent harness — block/buzz6 reactions · 1 comment
45 more on GitHub
- Aug 13, 2026package request: deepseek-harness(dsh) — numtide/llm-agents.nix4 reactions · 5 comments
- Aug 13, 2026[Feature] Add DeepSeek Harness as a first-class client integration — lidge-jun/opencodex3 reactions · 3 comments
- Oct 22, 2026[Engine] Engine crashes unexpectedly (exit code 1 / 3221226505) during DeepSeek Harness session on Windows 11 — Niko1221/Strata2 reactions · 3 comments
- Oct 14, 2026免费模型不可用,附D老师给的解决方法,自测恢复,望修复 — Ebony-Vinyl/dsh-our-free-model2 reactions · 8 comments
- Sep 29, 2026Make Codacy reviews available to every MDE coding agent — amoai-tech/mdeai2 reactions · 7 comments
- Sep 6, 2026[Bug] DeepSeek Harness "startup timed out" with dsh 0.1.2-rc.1 (readiness check incompatible) — CherryHQ/cherry-studio2 reactions · 2 comments
- Aug 31, 2026合作邀请:Blue TUI 生态适配(适配工作我们来做) — dream12347/dsh-session-manager2 reactions · 5 comments
- Aug 21, 2026[Bug]: DeepSeek Harness (dsh web) auto-opens system browser — Cherry should pass --no-open — CherryHQ/cherry-studio2 reactions · 1 comment
- Aug 17, 2026dsh: Needs `/bin/bash` to be present — numtide/llm-agents.nix2 reactions · 1 comment
- Nov 6, 2026Sign the DeepSeek Harness and Kimi Code through their own accounts — storytold/craft-anything1 reaction · 2 comments
- Nov 4, 2026Check plugin against DSH 0.2.2-rc.1 — JonyFang/dsh-plugin-custom-profile1 reaction · 1 comment
- Oct 28, 2026chore(deps): 升级 dsh peers 到 0.2.1-rc.4 / upgrade dsh peers to 0.2.1-rc.4 — btspoony/mstar-harness1 reaction · 2 comments
- Oct 13, 2026docs(dsh): select synchronization by host capability — mindfold-ai/marketplace1 reaction · 2 comments
- Oct 11, 2026Add umialpha/dsh-session-groups (alpha source preview) — imsai-sh/awesome-deepseek-harness-plugins1 reaction · 2 comments
- Oct 7, 2026replan(解决)的硬 cancel 触发 DSH 0.2.x turn/end reason:null,导致对话区永久空白——建议默认软 steer — PC2005-cloud/dsh-pet1 reaction · 1 comment
- Sep 30, 2026[Request]: DeepSeek Harness Desktop Preview — ScoopInstaller/Versions1 reaction · 2 comments
- Sep 29, 2026chore(deps): 升级 dsh peers 到 0.2.0-rc.2 / upgrade dsh peers to 0.2.0-rc.2 — btspoony/mstar-harness1 reaction · 1 comment
- Sep 24, 2026feat(adapters): add a DeepSeek Harness adapter with a full hook bridge — affaan-m/ECC1 reaction · 46 comments
- Sep 16, 2026fix(llm): 将会话头限定到 OpenCode 路由,避免发给无关 provider — dsh-tauri/deepseek-harness-desktop1 reaction · 1 comment
- Sep 14, 2026支持官方 v3 会话日志计量 — le-soleil-se-couche/dsh-token-cost1 reaction · 1 comment
- Sep 11, 2026chore(deps): 升级 dsh peers 到 0.1.5-rc.2 / upgrade dsh peers to 0.1.5-rc.2 — btspoony/mstar-harness1 reaction · 1 comment
- Sep 10, 2026Some cases that RTL is not working as expected + Visual Examples — kfirsch/dsh-hebrew-rtl1 reaction · 1 comment
- Sep 10, 2026chore(deps): 升级 dsh peers 到 0.1.5-rc.1 / upgrade dsh peers to 0.1.5-rc.1 — btspoony/mstar-harness1 reaction · 1 comment
- Sep 9, 2026chore(deps-dev): bump the deepseek-harness group across 1 directory with 2 updates — blaxel-ai/deepseek-harness-blaxel-sandbox1 reaction · 1 comment
- Sep 4, 2026chore(dsh): 升级 dsh host 线到 0.1.3-alpha.1 / upgrade dsh host line to 0.1.3-alpha.1 — btspoony/mstar-harness1 reaction · 2 comments
- Sep 3, 2026chore(deps): bump the deepseek-harness group with 4 updates — blaxel-ai/deepseek-harness-blaxel-sandbox1 reaction · 1 comment
- Sep 3, 2026chore(dsh): 升级 dsh host 线到 0.1.2-rc.1 / upgrade dsh host line to 0.1.2-rc.1 — btspoony/mstar-harness1 reaction · 1 comment
- Sep 2, 2026chore(dsh): 升级 dsh host 线到 0.1.2-alpha.5 / upgrade dsh host line to 0.1.2-alpha.5 — btspoony/mstar-harness1 reaction · 1 comment
- Sep 2, 2026chore(dsh): 升级 dsh host 线到 0.1.2-alpha.4 / upgrade dsh host line to 0.1.2-alpha.4 — btspoony/mstar-harness1 reaction · 1 comment
- Sep 1, 2026chore(dsh): 升级 dsh host 线到 0.1.2-alpha.3 / upgrade dsh host line to 0.1.2-alpha.3 — btspoony/mstar-harness1 reaction · 1 comment
- Aug 30, 2026chore(dsh): 升级 dsh host 线到 0.1.2-alpha.2 / upgrade dsh host line to 0.1.2-alpha.2 — btspoony/mstar-harness1 reaction · 1 comment
- Aug 29, 2026合作邀请:Blue TUI 生态适配(适配工作我们来做) — zh667/TokenLedger1 reaction · 5 comments
- Aug 27, 2026chore(dsh): 升级 dsh host 线到 0.1.2-alpha.1 / upgrade dsh host line to 0.1.2-alpha.1 — btspoony/mstar-harness1 reaction · 1 comment
- Aug 27, 2026🌱 Show official DeepSeek Harness logo — sesori-ai/sesori_apps_monorepo1 reaction · 2 comments
- Aug 26, 2026Feature Request: Add support for DeepSeek Harness — sodiumsun/agenttrail1 reaction · 1 comment
- Aug 22, 2026[Compatibility] DSH Desktop built-in Market cannot load this catalog under fake-IP DNS proxies (client-side blocked-address) — imsai-sh/dsh-1024store1 reaction
- Aug 21, 2026chore(dsh): upgrade dsh host line to 0.1.1-rc.2 — btspoony/mstar-harness1 reaction · 1 comment
- Aug 19, 2026docs(blog): Cordisの時空間合成可能性を解説 — penpenguin/portfolio1 reaction
- Aug 17, 2026Add native DSH Student OS tools — Gu-Heping/college-student-workflow1 reaction · 22 comments
- Aug 17, 2026MIM-164 提供可复用的代码熵回收 Skill — gaixianggeng/codex-skills1 reaction
- Aug 14, 2026【功能请求】 支持 dsh(deepseek-harness) — crafter-station/petdex1 reaction · 2 comments
- Aug 13, 2026docs(analysis-site): correct the ecosystem claims against upstream evidence — zhanglunet/deepseek-harness1 reaction · 1 comment
- Nov 15, 2026[reimplement] github.com/deepseek-ai/deepseek-harness dsh-linux-support-1b2e3f10 needs a human decision — with-fh/.forkhub0 reactions
- Nov 14, 2026[Update Request]: DeepSeek.DeepSeekHarness version 0.1.7-rc.2 — microsoft/winget-pkgs0 reactions · 1 comment
- Nov 8, 2026Исследование DeepSeek Harness: зрелость, модульность и независимость от провайдера — TeaShaman-cyber/local-lab0 reactions · 1 comment
On Bluesky · 13
- Aug 13, 2026DeepSeek Harness v0.1 the idea is everything is a plugin — models, tools, sessions, skills, sandboxes, loops, … github.com/deepseek-ai/... — @timkellogg.me77 likes and reposts · 7 replies
- Aug 17, 2026¡DeepSeek hace de código abierto su Agent Harness! 144.000 estrellas en 4 días. Todo lo cambias a base de plugins: El modelo, las tools, el… — @midu.dev18 likes and reposts · 1 reply
- Aug 13, 2026github.com/deepseek-ai/... — @sungkim.bsky.social5 likes and reposts
- Aug 29, 2026github.com/deepseek-ai/... I haven't used it myself but idk I'd consider this a "first party harness" I guess. — @itisamystery.com4 likes and reposts · 2 replies
- Aug 19, 2026DeepSeek Harness github.com/deepseek-ai/... A Programming Paradigm for Spatiotemporal Composability github.com/cordiverse/p... Interesting… — @inamiy.bsky.social3 likes and reposts
8 more on Bluesky
- Aug 14, 2026maybe this? github.com/deepseek-ai/... — @bisks.net3 likes and reposts · 2 replies
- Nov 14, 2026DeepSeek open-sourced an agent harness where everything is a plugin, and it launches with one npx command. 🔗… — @prosperflowio.bsky.social2 likes and reposts
- Sep 13, 2026GitHub - deepseek-ai/deepseek-harness: DeepSeek Harness: Everything is a Plugin. https://github.com/deepseek-ai/deepseek-harness — @tech-trending.bsky.social1 likes and repost
- Aug 23, 2026github.com/deepseek-ai/... it's real check it out, they're linking the paper — @daniel-j-h.bsky.social1 likes and repost
- Aug 13, 2026DeepSeek Harness https://github.com/deepseek-ai/deepseek-harness — @hnbot.gsuscs.xyz1 likes and repost
- Aug 13, 2026github.com/deepseek-ai/... 5分钟前还是 404 的,现在打开已经 700 多星了 抢票呢你们? — @icecodenew.bsky.social1 likes and repost
- Aug 14, 20265. Writer Launches New GLM-5.2 Based Model for Lower Token Costs LINK 6. DeepSeek Releases Open-Source Agent Harness LINK — @hackobar.bsky.social0 likes and reposts · 1 reply
- Aug 14, 2026DeepSeek acaba de soltar su propio Claude Code: DeepSeek Harness, open source. 82K⭐ en GitHub el primer día. Repo aquí — @lluis154.bsky.social0 likes and reposts · 1 reply
On the web · 10
- Sep 9, 2026DeepSeek Harness Review: Agent Loop & Plugin ... — deepinfra.com
- Sep 3, 2026DeepSeek Harness: An Architecture Review and Getting-Started Guide — zyvop.com
- Aug 22, 2026DeepSeek Harness is out. What is it, really? — taoproductleader.substack.com
- Aug 21, 2026I tried deepseek harness on local workflows invoices x trend archives and custom tools — medium.com
- Aug 19, 2026I tried the new claude code rival deepseek harness thats wild free — medium.com
5 more on the web
- Aug 18, 2026DeepSeek Harness Review: 3 Runs Said Done, Only 1 ... — atlascloud.ai
- Aug 14, 2026DeepSeek Harness 入门指南:一切皆插件的 Agent 到底怎么用 • Feisky — feisky.xyz
- Aug 14, 2026深度体验DeepSeek Harness,我原谅它涨价了 – 量子位 — qbitai.com
- Aug 13, 2026What is deepseek harness — medium.com
- Aug 13, 2026DeepSeek Harness 2026: Everything Is a Plugin — Developer Preview Guide — dev.to
On Hacker News · 2
- Aug 21, 2026DeepSeek harness: what doors does config over code open?3 points · 1 comment
- Aug 18, 2026DeepSeek Harness1 point
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/notes/AGENTS.mdAGENTS.md
- .agents/notes/archived/AGENTS.mdAGENTS.md
- .agents/notes/implemented/AGENTS.mdAGENTS.md
- apps/cli/tests/profiles/AGENTS.mdAGENTS.md
- benchmarks/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- .github/AGENTS.mdAGENTS.md
- native/system/AGENTS.mdAGENTS.md
- packages/AGENTS.mdAGENTS.md
- packages/client/AGENTS.mdAGENTS.md
- packages/experimental/AGENTS.mdAGENTS.md
- packages/schedule/AGENTS.mdAGENTS.md
- packages/web/AGENTS.mdAGENTS.md
- scripts/AGENTS.mdAGENTS.md
- snapshots/AGENTS.mdAGENTS.md
- snapshots/session/agent-instructions-budget-chains/workspace/AGENTS.mdAGENTS.md
- snapshots/session/agent-instructions-budget-chains/workspace/.dsh/AGENTS.mdAGENTS.md
- snapshots/session/agent-instructions-budget/workspace/.agents/AGENTS.mdAGENTS.md
- snapshots/session/agent-instructions-budget/workspace/AGENTS.mdAGENTS.md
- snapshots/session/agent-instructions-budget/workspace/.dsh/AGENTS.mdAGENTS.md
- snapshots/session/agent-instructions-group-failure/workspace/.agents/AGENTS.mdAGENTS.md
- snapshots/session/agent-instructions-group-failure/workspace/.dsh/AGENTS.mdAGENTS.md
- snapshots/session/agent-instructions/workspace/.agents/AGENTS.mdAGENTS.md
- snapshots/session/ptc-workspace-context/workspace/AGENTS.mdAGENTS.md
- snapshots/session/ptc-workspace-context/workspace/nested/AGENTS.mdAGENTS.md
- website/AGENTS.mdAGENTS.md
- agent-experienceSkill
- cordis-styling-nitpickingSkill
- dsh-archive-agent-notesSkill
- dsh-ci-test-reliabilitySkill
- dsh-client-ui-uxSkill
- dsh-code-reviewSkill
- dsh-create-upgrade-guideSkill
- dsh-cua-macos-signingSkill
- dsh-error-handlingSkill
- dsh-find-simplificationsSkill
- dsh-merging-stacked-prsSkill
- dsh-official-plugin-artworkSkill
- dsh-pr-descriptionSkill
- dsh-pre-push-checksSkill
- dsh-prose-standardSkill
- dsh-responsive-uiSkill
- dsh-session-projectionSkill
- dsh-speed-up-perfSkill
- dsh-translate-docsSkill
- dsh-trim-cot-leakageSkill
- record-browser-gifSkill
- preview-tourSkill
- dsh-docSkill
- diagnose-windows-sandbox-aclSkill
- office-docxSkill
- office-pptxSkill
- officeSkill
- office-xlsxSkill
- editing-cordis-compositionsSkill
- model-only-skillSkill
- snapshot-skillSkill
- user-only-skillSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
Follow this sequence for each requested scope.
- Distinctive: line 30
Read root and more-specific AGENTS.md, the documentation standard, the target page, its source/tests, navigation owner, and bilingual …
- Very specific: line 32
Place the page at its nearest owner.
- Very specific: line 34
Add or revise YAML metadata — assign the kind that maps to the template for this document's job — then write Summary, Table of Contents, …
- Distinctive: line 35
Update the bilingual counterpart in the same pass.
- Distinctive: line 36
Verify every claim against code, tests, generators, package metadata, or a current decision owner — and run the operations the page …
- Very specific: line 37
Run focused checks, then pnpm run test:docs, pnpm run doc-sync, pnpm run lint, and git diff --check.
- Distinctive: line 45
Delete what you could not reproduce: Never carry a command, field, default value, or behavior from memory, analogy, or a neighboring …
- Very specific: line 46
Check old docs against latest master: Before revising pre-existing pages, git fetch origin and compare the section against origin/master.
- Distinctive: line 76
Use these definitions in review.
- Distinctive: line 85
Do not apply a universal word limit to exhaustive references.
- Very specific: line 128
Run pnpm run test:docs for the quick comprehensive documentation checks (pairing, wrap, links, README gates, budgets, skill metadata, Agent …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
DeepSeek Harness documentation
Summary
The DeepSeek Harness documentation standard: make every page searchable, newcomer-readable, and exact enough for agents and maintainers, and keep the documentation website a tested projection of repository Markdown. Apply repository AGENTS.md files and executed gates first, then this workflow for kind-mapped metadata, progressive detail, line-aligned bilingual pages, corpus audits, and website publication. Preserve one owner per fact: source, tests, generated catalogs, package READMEs, guides, Agent Notes, and scratch each keep their own kind of truth. The session-persistence-jsonl README pair is the reference example of the format.
Table of Contents
- Workflow
- Fact-check procedure: test, do not assume
- Kind system and templates
- Voice rules
- Quality criteria
- Audit the corpus
- Wordcount budgets
- Website publication
- Detailed references
- Validation
- Dev Note
Workflow
Follow this sequence for each requested scope. Keep the common reader path brief, but do not delete failures, ownership, limitations, or other required contracts merely to reduce words.
- Read root and more-specific
AGENTS.md, the documentation standard, the target page, its source/tests, navigation owner, and bilingual record. - Classify the page by one primary job and reader: product quick start, user task guide, contributor tutorial, architecture overview, package/subsystem reference, generated reference, agent instruction, decision record, or scratch.
- Place the page at its nearest owner. Keep package contracts beside package code; use
docs/for cross-package learning, user, developer, architecture, discussion, and expiring scratch material. - Define the reader's starting state, observable outcome, likely failure, recovery path, and next useful depth before writing details.
- Add or revise YAML metadata — assign the
kindthat maps to the template for this document's job — then writeSummary,Table of Contents, user-facing content, developer-facing content, optionalFurther Exploration, and finalDev Notein that order where the document type permits. - Update the bilingual counterpart in the same pass. Keep headings, lists, tables, code, links, frontmatter layout, and physical line count aligned.
- Verify every claim against code, tests, generators, package metadata, or a current decision owner — and run the operations the page instructs, per the fact-check procedure below. Update the owner before any derivative artifact.
- Run focused checks, then
pnpm run test:docs,pnpm run doc-sync,pnpm run lint, andgit diff --check; re-read the complete diff for correctness and then for brevity and repository fit.
Fact-check procedure: test, do not assume
Documentation states how the product behaves today, and the only admissible evidence for an operation claim is having run it. This procedure is mandatory for every new document and every new paragraph that claims an operation, command, default, error, or platform difference.
- Classify the subject before writing install guidance. Read the facts, never the folder name:
package.jsonfor adsh.bundle.patchdeclaration, and the entry file for the plugin shape (applyexport or a default service export is a plugin; a plain module API is a library). A bundle installs withdsh plugin --profile <name> add <package>and is the only package shape for which that command activates a profile layer; a plugin mounts as acordis.ymlrow; a library is a dependency with no install path of its own. Packages with special status (libraries, bundles) get their own README template — never a plugin README with install guidance that does not apply. - Run every claimed operation against the current checkout. Execute each CLI command, config snippet, and profile or patch example exactly as the document will show it; write down only what you observed, including the exact output, warnings, and failure modes. If a claim depends on a key or a network you do not have, say so and name the verification owner instead of asserting the behavior.
- Delete what you could not reproduce. Never carry a command, field, default value, or behavior from memory, analogy, or a neighboring package's README. When a claim fails to reproduce, fix the claim — not the test.
- Check old docs against latest master. Before revising pre-existing pages,
git fetch originand compare the section againstorigin/master; the pairing sidecar recovers the last-confirmed text of either side. A stale statement on master is still wrong: correct it against the code, not against the old prose. - Re-record the pair after every edit. Each paired edit re-runs
pnpm run verify-translation-pairing --write <pair>so the sidecar tracks the confirmed pair.
Kind system and templates
The kind frontmatter field selects exactly one README template. Every kind in the metadata reference maps to one template file in templates/, and every template backs exactly one kind; the documentation check derives the expected kind from the same mechanical facts.
package-group→ templates/package-group.md: group maps (packages/README.md,packages/<group>/README.md) — orient the family, map its direct packages, link package-owned details.package-reference→ templates/package-reference.md: a Cordis plugin or service package — mount configuration, the config table, folded implementation, Model Experience and Known Limitations in the gate-owned forms.package-library→ templates/package-library.md: a package with no plugin surface — consumer entry points, no profile-install path, no mount configuration.package-bundle→ templates/package-bundle.md: a package declaringdsh.bundle.patch— the verifieddsh plugininstall path, layer semantics, patch document.persistence-change→ templates/persistence-change.md: a dated record indocs/persistence-changes/— acknowledge a detected type transition with per-root predecessors and generated after schemas.persistence-release→ templates/persistence-release.md: a pinned tag indocs/persistence-changes/releases/— compare reconstructed historical types without claiming compatibility acknowledgement.persistence-format→ templates/persistence-format.md: a historical Session format checkpoint indocs/persistence-changes/historical-formats/, with complete schemas; the current writer uses the existing catalog.upgrade-guide→ templates/upgrade-guide.md:docs/upgrade-guide/v<version>/<item>/guide.mdand its Chinese sibling — migration steps for one externally perceptible break, owned by dsh-create-upgrade-guide.
Open the template before writing and follow its skeleton and rules; it states what the kind is, how the page is structured, and the fact checks each section owes. Add a new kind only together with a distinct template file, a documented repository position or declared owner, and a focused check that maps documents to it.
Voice rules
These rules decide what a section may say. They apply to every authored human-facing page, and to package READMEs with particular force.
- Summary says what the subject does. The opening
Summaryand the user-facing sections describe what a user or agent can DO with the subject — outcomes, benefits, when to choose it, main cost — never its role, type, or internal identity. In a package Summary, “what it is” means only its reader-visible capability, not its Cordis role, registrations, or internal components. Omit source identifiers unless the reader directly uses them in configuration, a command, or a public API. "The seam registersctx.xand appendsx/eventrecords" is identity narration; "you can save a note per message and it survives restarts" is what it does. - Developer sections explain, never enumerate. Folded implementation content covers the overall design concept, architecture, and hand-waving dataflow — enough to understand how the package works — and links code for exact detail. No full API catalogs, exhaustive column lists, event-payload enumerations, or JSDoc restatement inside the folds.
- Dev Note is the only slop zone. Partial ideas, scratches, undecided directions, measured artifacts, and working hypotheses live only in the final Dev Note, marked explicitly non-authoritative. Every other section is polished, current-state prose.
- Current state only. Ordinary documentation describes the current codebase. Dedicated
persistence-change,persistence-release, andpersistence-formatrecords retain historical type evidence; release comparisons and format checkpoints describe observed history without asserting compatibility. Anupgrade-guidedescribes the change from its version directory's release to the next one. Agent Notes and postmortems retain their own historical scope. - Use controlled technical English. Give each sentence an explicit actor and one main action when ambiguity can change behavior. Reuse one term per concept, prefer direct verbs, split stacked instructions and conditions, and preserve modality and exceptions. Apply the non-certified, ASD-STE100-inspired discipline in the page-style reference. Do not force a shorter sentence when precision would fall.
Quality criteria
Use these definitions in review. Each section opens with a short orienting paragraph before subsections or exhaustive detail.
- Brief: the common path contains only facts needed for its outcome; exhaustive truth remains one direct link or detail layer away.
- Intuitive: prerequisites precede dependent concepts, one next action is obvious, and headings use terms readers search for.
- Friendly: readers can recognize success, understand risk before acting, recover from likely failure, and choose whether to continue deeper.
- Accurate: each durable claim has one owner and a verification path proportionate to its risk.
- Agent-readable: metadata, stable headings, anchors, terminology, ownership, and current/proposed status support targeted retrieval without loading the corpus.
- Newcomer-complete: a professional engineer with no repository context can reconstruct the relevant architecture or feature through three to five linked pages.
Do not apply a universal word limit to exhaustive references. Measure entry-path length, unrelated material scanned for one lookup, largest section, heading count, and page size; split by an existing domain owner when retrieval cost is high.
Audit the corpus
Read, do not re-summarize, the owning contracts: docs/AGENTS.md for hierarchy, tutorial/reference forms, taxonomy, budgets, and the slop checklist; .agents/notes/README.md for Agent Note lifecycle; docs/i18n/README.md for the bilingual pairing rules; and root AGENTS.md for standing orders. Exclude .agents/notes/archived/ from audits and edits — archived notes are frozen history.
Apply the standard's authoring order to every human-facing document in scope (not to Agent Notes): locate the document and state its own subject; set the permitted detail level and move deeper explanations to owning descendants with links; classify tutorial or reference from intended use, not path; for a tutorial, order concepts by prerequisite and difficulty; split substantial mixed forms. Then check placement constraints: paired docs cost a counterpart update and a --write re-record on every edit; generated catalogs are never hand-edited; a move is atomic with every inbound link repaired in the same change.
After the structural pass, hunt the slop checklist with the cheapest probes first. Use dsh-trim-cot-leakage for reasoning-transcript leakage, grep distinctive phrases to find duplicated rules, replace hand-written catalogs and status inventories with their authoritative owners, and remove migration plans and future-tense spec language from implemented Agent Notes. Measure outliers with pnpm run verify-doc-budgets --list and a word-count scan; if removing prose changes a promised behavior rather than its explanation, propose the behavior change first (follow dsh-find-simplifications). Keep every load-bearing rule, preferably as one to three lines plus a link to its rationale; do not create a new explanation merely to relocate disposable reasoning.
Wordcount budgets
pnpm run verify-doc-budgets compares standing documents against ceilings in scripts/doc-budgets.manifest.json; a red gate follows the ordered relocate-condense-raise policy in docs/AGENTS.md. Ceilings are guardrails, not reduction targets: at or below target, retain at least 5% headroom; raise a ceiling only when the words need the space, and justify the manifest diff in the PR.
Website publication
The website is a tested projection, never a second copy: website/docs.ts is the explicit public allowlist mapping canonical docs/ sources into route trees, scripts/project-doc-site.ts rewrites them into the disposable website/.generated/ tree, and VitePress builds that tree. Repository Markdown stays the only editable content source; translations stay sibling pairs (foo.md, foo.zh.md, foo.i18n.yaml), never locale directories. Edit an already published page in its canonical source only; add one manifest entry for a new page; update source, manifest entry, and inbound links atomically for a move or removal; never edit website/.generated/, website/.cache/, or website/.dist/. Set every DocsPage field deliberately and honor the projector's link rules; see references/website-sync.md for the fields, sidebar collections, and preview commands. Synchronizing content into the build does not publish it: deployment stays a separate, explicitly requested step.
Detailed references
Load only the reference needed for the task. Each reference links directly from this file so the skill has no deep reference chain.
- Metadata, links, and bilingual pairs: README frontmatter, the kind system and its derivation, description semantics, repository paths, line alignment, and the sidecar record.
- Page structure and hierarchy: mandatory section order, section summaries, user-to-developer progression, docs tree placement, small rule files, Further Exploration, and Dev Note ownership.
- Page style: short Summary,
-----section separators, foldable content sections, and emphasis discipline. - Review criteria: newcomer test, evidence checks, package README review, the reference example, and verification commands.
- Website publication: manifest fields, projector link rules, preview and validation, and deployment separation.
The templates in templates/ provide one working skeleton per kind; open the one your document's kind names before writing.
Use dsh-prose-standard for sentence-level contract coverage and editorial judgment. The session-persistence-jsonl README pair (English, Chinese) is the reference example: searchable YAML, Summary and Table of Contents, user-to-developer progression with a folded developer section, Further Exploration, canonical Model Experience and Known Limitations sections, and a final Dev Note.
Validation
Validate the affected format, not merely Markdown syntax. A strong promise needs a focused valid fixture and an invalid fixture that proves the top-level gate can fail.
- README metadata: parse YAML, map
kindto its template and document standard, rejectname,audience, ungovernedtags, and README-locali18nmetadata, and reject missing or advertisement-style descriptions. - Bilingual pages: verify structure, exact line count, terminology, link parity, and the sidecar record.
- Tutorials: exercise the documented entry path or name an explicit manual verification owner.
- Generated references: run the deterministic freshness check and report retrieval-size measures.
- Package READMEs: run the Summary gate, which limits each English Summary to 100
wc -w-style words and directs failures back to this skill and the kind template; run model-experience and limitation checks, then package-focused tests when behavior claims changed; re-run every command the README instructs before merging a claim about it. - Skills: run the repository's skill-invocation metadata check.
Run pnpm run test:docs for the quick comprehensive documentation checks (pairing, wrap, links, README gates, budgets, skill metadata, Agent Note gates) before the full pnpm run doc-sync.
Dev Note
None.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

