agentsclimarketplace

Docs author

Skill Paldom/github-skills/skills/docs-author

Agent Skills for professional GitHub repos - brief, structured, SEO-friendly READMEs that convert visitors into users, plus complete OSS scaffolding: community health files, templates, and discoverability best practices.

Install
npx -y skills add Paldom/github-skills --skill docs-author

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Plans, writes, or restructures project documentation - Diátaxis structure (tutorials, how-to guides, reference, explanation), minimal doc set, runnable examples, README-to-docs graduation, drift prevention. Use when the user asks to write, improve, or reorganize docs, guides, or tutorials. Not for the README itself, deploying a docs site, or community files.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

5.7 KB, as published. Nobody here has run it

docs-author

Produces a documentation set users can actually learn from. Default model output fails at this in predictable ways — blended tutorial-reference hybrid pages, navigation shaped like the module tree instead of user tasks, invented code examples, and four empty "Tutorials/How-to/Reference/Explanation" folders scaffolded as if structure were progress. This skill exists to prevent exactly those failures.

When NOT to use

  • The README file itself → readme-author. Boundary: README = the front door; everything past it = this skill. "Turn our 800-line README into docs" uses this skill for the content and hands the README slimming to readme-author.
  • Standing up, deploying, or fixing the docs site (generator, GitHub Pages, CI pipeline) → docs-site. The two compose: content here, pipeline there.
  • CONTRIBUTING, SECURITY, CODE_OF_CONDUCT and other community files → community-health.
  • Docstrings or inline code comments in source files → ordinary editing.

Workflow

  1. Inspect before writing. Read the repo: public API surface, existing README/docs/wiki, open issues and support questions (they reveal the missing how-tos). Classify every existing docs chunk by mode — tutorial / how-to / reference / explanation — before writing anything new. The framework's own author's rule: improve one page at a time and publish each step; never scaffold four empty sections.
  2. Scope the minimal viable set (see references/docs-playbook.md): getting-started tutorial, how-tos for the top real tasks, generated reference, 1–3 concept pages, troubleshooting by symptom. Scale down for small projects — no empty or "coming soon" pages, ever. Below the navigational-need threshold, a good README is the whole answer.
  3. Structure task-first. Navigation named by user tasks and topics (authentication.md), never by code modules; at most two levels deep; every page reachable from the index. Move content out of the README, don't copy it — duplicated content always forks. (README.md itself stays at the repo root for registry display.)
  4. Write each page in exactly one mode, using the per-mode recipes and style rules in the playbook: second person, imperative, present tense, conditions before instructions, scannable structure, short sentences (~25-word check), no "simply/just/please", emphasis under ~10%. A sentence of inline explanation is fine; sustained explanation gets its own page and a link. After drafting, a /slop-lint + /deslop pass (paldom/noslop, when installed) strips AI-writing tells from docs prose.
  5. Make every example runnable. Complete as pasted (imports, setup, expected output), verified against the actual source in this repo — never written from memory. Label anything partial. Apply the clean-machine test to install/quickstart steps; wire doctest/CI example tests where the ecosystem supports them.
  6. Never hand-write what a tool can generate. API reference comes from docstrings/types/OpenAPI (generation wiring belongs to docs-site); hand-write only what has no source of truth to generate from.
  7. Drift pass. When syncing docs after code changes: search the whole docs tree for renamed/removed identifiers, not just the obvious page; mark deprecated-but-working features with their replacement instead of deleting; keep phrasing version-agnostic. Recommend the process fix — docs updated in the same PR as user-facing changes, enforced by a PR checkbox.
  8. Lint. Run and fix errors, triage warnings: 
    python3 "${CLAUDE_SKILL_DIR}/scripts/docs_lint.py" docs
  9. Present the result: the doc tree, what each page is (its mode), what was deliberately left out, and the signal that should trigger adding it.

Output spec

Every page classified in exactly one Diátaxis mode; navigation task-shaped, ≤2 levels, no orphans; examples complete, runnable, and verified against the repo; reference generated, not hand-written; README depth moved (not copied) into docs; docs_lint.py exits 0.

Gotchas

  • The default LLM genre is the blended "guide" — classify the page's mode before writing it, not after.
  • Docs are anti-DRY where repetition saves the reader a hunt between pages — but README↔docs duplication always drifts; link or include instead.
  • An auto-generated API dump is not documentation — reference feeds the set; tutorials and how-tos are what drive adoption.
  • FAQs fragment and rot; fold answers into findable pages and keep troubleshooting organized by symptom/error string.
  • Coding agents are now a large, silent docs audience (they never file issues) — self-contained sections and text-over-screenshots serve them and human skimmers alike (playbook has the rules).
  • Wrong docs are worse than no docs: when a fact can't be verified against the code, cut it or mark it unverified — never guess.

Files

  • references/docs-playbook.md — Diátaxis application, minimal doc set, per-mode page recipes, style rules, examples policy, drift prevention, contested points.
  • scripts/docs_lint.py — deterministic tree lint: broken relative links, missing index, orphans, nesting depth, filename style, heading structure, emphasis budget; non-zero exit on errors.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.