AGENT SKILL

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

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

  1. 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.
  2. Match the reader mode. Learning, task, lookup, and understanding each take different shapes. Never mix instruction into reference or background into steps.
  3. 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.
  4. Delete over repair. A doc that restates its subject, opens with filler, or carries praise without measure gets removed, not reworded.
  5. One shared vocabulary. Terms come from the project's glossary (CONTEXT.md where 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 validate passes 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

hadronomy
hadronomy/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.

★ 0
hadronomy
hadronomy/skills

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.

★ 0
hadronomy
hadronomy/skills

setup-hadronomy

暂无简介

★ 0
hadronomy
hadronomy/skills

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.

★ 0
hadronomy
hadronomy/skills

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.

★ 0
hadronomy
hadronomy/skills

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.

★ 0