Index of every page on this site: llms.txt
All skills
masihmoafi avatar

/doc-style

@c0a5d13
by Masih Moafimasihmoafi/skills10 stars
Run it yourself

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".

  • 1 file
  • 3.7 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/masihmoafi/skills/doc-style

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈52 tokens for metadata: the name and description. ≈887 when used: this file.

Description uses 2.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈208 characters, or 2.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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, TODOs 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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at c0a5d13. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 3 weeks ago

README badge

README badge for masihmoafi/skills/doc-style