docs-craft
Documentation discipline for code comments, API docs, and docs pages. Use when writing or reviewing doc comments, JSDoc or rustdoc, README sections, or framework docs pages — or when comments and docs read as filler and need cutting.
- License 许可
- MIT
- 所属仓库
- hadronomy/skills
- 最近更新
- 2026-10-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- docs-craft
- description
- Documentation discipline for code comments, API docs, and docs pages. Use when writing or reviewing doc comments, JSDoc or rustdoc, README sections, or framework docs pages — or when comments and docs read as filler and need cutting.
02 资源文件 5
- 参考文档agents/openai.yaml137 B
- 参考文档references/api-docs.md1.3 KB
- 参考文档references/comments.md915 B
- 参考文档references/pages.md1.0 KB
- 参考文档references/sources.md863 B
03 SKILL.md 正文
Docs Craft
Every doc has one job and one reader mode. Comments say what the code cannot. API docs describe the contract with runnable proof. Pages answer exactly one of learning, task, lookup, or understanding. Anything else is slop: delete it rather than polishing it.
This is a routed skill. Always apply the core contract. Read only the reference layers the task needs.
Core contract
- One doc, one job. Name the job before writing: explain a reason, specify a contract, teach a task, or record a fact. A doc doing two jobs splits in two.
- Match the reader mode. Learning, task, lookup, and understanding each take different shapes. Never mix instruction into reference or background into steps.
- Prove behavior with runnable examples. Every example executes in CI: doctests for code, copy-paste runs for pages. An example with no observation goes out.
- Delete over repair. A doc that restates its subject, opens with filler, or carries praise without measure gets removed, not reworded.
- One shared vocabulary. Terms come from the project's glossary
(
CONTEXT.mdwhere one exists). The same term never wears two names.
Branches
| Task | Read |
|---|---|
| In-code comments in any language | references/comments.md |
| API docs: JSDoc, rustdoc, README API sections | references/api-docs.md |
| Docs-framework pages: tutorials, guides, reference, explanation | references/pages.md |
| Why behind a rule, with source links | references/sources.md |
Done when
npm run validatepasses for this skill.- Every touched doc has one job, one reader mode, and runnable proof where it shows behavior.
- Slop checks ran: no restated subjects, no filler openers, no unmeasured praise, no dead links.
04 同仓库更多 Skills
windows-mcp
Driving the Windows desktop on `workstation` through the windows MCP server. Use before any `mcp__windows__` tool, when a desktop call blocks or returns "Desktop busy", when Snapshot or Screenshot come back empty, or when this agent has no desktop tools and the task needs them.
typst-author
Author idiomatic, compilable Typst documents. Use when creating or editing Typst (.typ) files, when a task involves Typst syntax, packages, templates, or bibliographies, or when a Typst build fails and the error needs a fix.
setup-hadronomy
暂无简介
rust-craft
Craft production Rust the way the top toolchain teams do. Use when writing, reviewing, or restructuring Rust — workspace layout, Cargo manifests, lints, and profiles; type, trait, and error API design; performance, allocation, and profiling work; async and concurrency; CLI construction; test, snapshot, and benchmark suites; crate selection; release, semver, MSRV, and feature flags.
pr-craft
Write pull requests a reviewer can act on. Use when opening, rewriting, or reviewing the body of a pull request — title and description, the problem and approach, call-stack diffs, before-and-after screenshots, verification steps, risks, a review guide, and the tools that produce each part.
effect-craft
Craft Effect TypeScript APIs with the discipline of the Effect and opencode codebases. Use when modeling data with Schema, building services with Context and Layer, naming operations with Effect.fn, exposing modules through barrels, designing hooks or HTTP surfaces, or writing JSDoc with runnable examples — new code, refactors, and API reviews.