---
name: doc-style
description: Use when writing, reviewing or auditing a README, skill, specification, project page or launch material that must stay concise and evidence-backed, including "audit docs" and "prune AI self-talk".
title: doc-style
canonical_url: https://skilld.dev/gh/masihmoafi/skills/doc-style
last_updated: 2026-11-03T09:01:25.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install masihmoafi/skills/doc-style`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/doc-style`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/masihmoafi/skills/doc-style) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/doc-style`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/doc-style --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/doc-style --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Documentation style

Part 1 applies to every document. Parts 2 and 3 apply to public READMEs and project pages. A file with a required schema (a `SKILL.md`, a spec) keeps its schema. Agent docs (`AGENTS.md`, `ES.md`) follow `project-docs`; sentences follow `writing-style`.

## 1. Every document

- Keep the author's voice. Use facts and short, direct sentences; no marketing words.
- Claim nothing the repository cannot prove: no feature, result, benchmark, release, user count or stability level without evidence.
- Name the true state: "planned", "under acceptance" or "experimental".
- Put the evidence beside the claim it supports.
- Prefer a pointer (`file:line`, a link) to a copy; copies go stale.

## 2. Public README or project page

The first screen answers four questions: what is it, who is it for, what painful problem does it remove, what proof can the reader inspect now (a demo, screenshot, passing workflow, benchmark, release or command). Do not open with history, philosophy or a feature list.

Sections, in this order:

1. **Intro**: two or three sentences: what it is, who it serves, why it exists. A good hook is a falsifiable claim ("A coding agent should not forget why it is changing your code."), and the next sentence says how the project acts on it.
2. **Quick start**: install (one command), run (one command), expected result. Long walkthroughs go below.
3. **The problem**: the concrete failure in today's workflow, shown as "without this" against "with this".
4. **How it works**: a one-page manual of mechanics and limits; a small diagram if it helps. Deep references go to the project's docs home (GitHub Pages is one option) and are linked by topic.
5. **Current state**: four separate lists: verified, under acceptance, planned, unsupported. Link the source of truth.
6. **What sets it apart**: design choices and tradeoffs checked against the repository and real alternatives. Invent no novelty.
7. **Evidence**: what the tests, workflows and benchmarks cover, and what a passing badge does and does not prove. If there is none, say so and name the smallest useful test.
8. **Next**: near-term work backed by the task tracker only.

Before you finish, check: the opening states the real product and its maturity; Quick start comes before deep detail; every major claim can be verified; the reader knows what to do next; one sentence could serve as the public description.

## 3. Distribution

Derive every channel from the README; change the opening, never the facts.

- GitHub description: one factual sentence.
- Launch post: problem, result, proof, link.
- Technical post: one design decision, its tradeoff, its evidence.
- Community post: ask for feedback on one open problem; no bare link.
- Demo script: the failure, the project in use, the visible improvement.

## 4. Audit

To audit docs or prune AI self-talk, search the `*.md` and `*.html` files for `TODO`, `not done`, `AI note` and `no cost`, and group findings by file.

Remove:

- notes the agent left for itself, including notes on abandoned attempts;
- progress logs, `TODO`s and status tables for work that is finished, dropped or refactored;
- run IDs, hashes and verification prose outside `reports/` or commit messages;
- price or free-tier claims without a source and a date.

Keep current limitations, skipped checks, known risks and useful handoffs. A review request produces findings; a cleanup request produces the edits, with no second ask. When a plain diff cannot show a visual change, write a side-by-side HTML diff to `/tmp`.
