Agent skill

Evidence-Backed Documentation Writer

by bgauryy in bgauryy/octocode

Writes, repairs and copyedits project docs against the Google developer documentation style guide, verifying claims in the repository before stating them.

MITAuto-check passedDevelopment

Install Evidence-Backed Documentation Writer

skills CLI
$ npx skills add bgauryy/octocode --skill octocode-documentation -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install bgauryy/octocode octocode-documentation --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/bgauryy/octocode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/octocode-documentation .claude/skills/octocode-documentation && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
octocode-documentation
GitHub stars
949
Token cost
~2k tokens
SKILL.md length
896 words
Files
37 (incl. scripts, references, assets)
Skills in repo
12
Repo updated
First seen
Licence
MIT

At a glance

Writes, repairs and copyedits project docs against the Google developer documentation style guide, verifying claims in the repository before stating them.

  • Rewriting a stale or inaccurate README against the real code
  • SKILL.md covers Flow, Rules, Workflows — the mode fixes the… and Routes — workflow references, plus 3 more sections
  • Copyediting a doc to match the Google developer style guide
  • Writing an ADR, runbook or migration guide from repository evidence

What it does

This skill covers missing, stale, wrong or badly written documentation: READMEs, API references, runbooks, CONTRIBUTING files, changelogs, onboarding guides, AGENTS.md and CLAUDE.md, ADRs, migration guides, docstrings, alt text and prose linting. It follows the flow understand, research, classify, outline gate, write, style and verify. A copyedit request starts at the style step, and a question about a single term is answered straight from a bundled Google word list.

Several rules keep the output honest. Claims are checked in the repository before they are written, and anything unverifiable is omitted or marked as not verified. Creating or overwriting files needs your approval of the targets, and only named files are touched. Each page follows one Diátaxis type, AGENTS.md stays an index of links, and durable pointers such as module paths are preferred over line numbers. An existing project style guide wins over the Google defaults, and conflicts are reported.

It is not meant for writing code, commit messages or marketing copy. Questions that need code investigation are handed to the octocode-research skill, and work on SKILL.md folders goes to octocode-skills.

When your agent uses it

  • Rewriting a stale or inaccurate README against the real code
  • Copyediting a doc to match the Google developer style guide
  • Writing an ADR, runbook or migration guide from repository evidence
  • Restructuring documentation using Diátaxis

Example prompts

  • “Rewrite the README so every command in it actually works in this repo.”
  • “Copyedit docs/setup.md against the Google style guide and name each rule you apply.”
  • “Write an ADR for our move to a queue-based worker design.”

What it can do on your machine

Read from SKILL.md and the folder at commit c265e3f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/, which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Evidence-Backed Documentation Writer loads about 2k tokens when it runs, and up to ~26k if it reads all its reference files. Until then it costs about 110 tokens; SKILL.md has 896 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~110
When it runs · the whole SKILL.md, loaded when a task matches
~2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~26k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from bgauryy/octocode at commit c265e3f, republished under its MIT licence (© bgauryy). 896 words, ~2,023 tokens.

Download SKILL.mdSave it as .claude/skills/octocode-documentation/SKILL.md (or your agent's skills folder). This skill also uses 36 other files; get the full folder from GitHub.
name
octocode-documentation
description
Use when docs are missing, wrong, stale, or badly written, or need a copyedit against the Google style guide: README, API reference, runbook, CONTRIBUTING, changelog, onboarding, AGENTS.md/CLAUDE.md, ADR, migration guide, Diátaxis or whole-codebase restructure, docstrings, alt text, prose linting. Not for code, commits, or marketing copy. Code investigation → octocode-research; SKILL.md folders → octocode-skills.

Octocode Documentation

Evidence-backed docs for humans and agents, written to the Google developer documentation style guide. Classify first. Gate writes. Prefer durable cross-refs over code dumps.

Flow

UNDERSTAND → RESEARCH → CLASSIFY → OUTLINE GATE → WRITE → STYLE → VERIFY

UNDERSTAND names the deliverable, audience, and target paths. Compress when the request already names targets and type. Expand when claims need verification. A copyedit request starts at STYLE. Answer a single-term question ("is allows you to okay?") straight from assets/google-word-list.tsv — quote the guidance and stop.

Rules

  • Verify claims in the repository before asserting them. Invented commands, paths, APIs, and env vars are the one unrecoverable failure — omit or mark "Not verified in repository" instead.
  • Pick one mode and load its routes before writing.
  • Gate creates and overwrites unless the requester approved the targets this turn; a copyedit of a named file carries its own approval. Touch only the files they named — propose the rest.
  • Apply the style defaults in references/style-index.md to every line you write or edit, and name the rule when you change someone else's wording.
  • The style references are a snapshot of Google's guide, and every one links the pages it restates. IF someone disputes a rule, the pack doesn't carry it, or the wording carries risk (trademark, product name, legal claim, security claim) → THEN open the live page with a web tool, quote it with its URL, and fix the reference when it disagrees; say so when no fetch was possible.
  • A style pass changes wording, not claims; a fact change goes back to RESEARCH.
  • AGENTS.md is an index of links and non-obvious rules, not a content dump.
  • Prefer durable pointers (module path, contract name, doc link) over line numbers and pasted code.
  • One Diátaxis type per page; link siblings instead of mixing.
  • IF the project documents its own style guide, or the repository already applies a convention consistently → THEN follow it and report the conflict instead of adding a second scheme.

Stop when: outline gate awaits answer; write+style+verify finishes; a word-list lookup answered the question; a missing fact makes the doc dishonest to write (otherwise mark "Not verified in repository" and continue); conventions conflict; user cancels.

Workflows — the mode fixes the route order

ModeDeliverableRoute order
agent-docsAGENTS.md, nested agent instructions, CLAUDE.md symlinkmodes.md → evidence-research.md → agents-md.md → agent-readable.md → write-verify.md → style-lint.mjs
human-docsREADME, tutorial, how-to, reference, explanation, runbookmodes.md → evidence-research.md → diataxis.md → agent-readable.md → write-verify.md → style-lint.mjs
adrArchitecture decision recordmodes.md → evidence-research.md → adr.md → write-verify.md → style-lint.mjs
codebase-packMulti-file docs setmodes.md → plan the file set → gate once → per file: diataxis.md → write-verify.md → style-lint.mjs
style-passEdited text, or a style review reportstyle-index.md → the owning style-*.md → style-lint.mjs → style-review.md for a report someone else acts on

Routes — workflow references

PhaseWhenRead
CLASSIFYChoosing mode or audiencereferences/modes.md
RESEARCHGathering or verifying repository factsreferences/evidence-research.md
CLASSIFYChoosing the Diátaxis type for human-docs, or reviewing onereferences/diataxis.md
WRITEWriting or updating agent instruction filesreferences/agents-md.md
WRITERecording a decisionreferences/adr.md
WRITECross-refs, density, durability — read before the first linereferences/agent-readable.md
OUTLINE GATE, WRITE, VERIFYOutline gate, write steps, style pass, verify checklistreferences/write-verify.md
STYLEAny wording, formatting, or terminology question — maps every guide topic to its ownerreferences/style-index.md
Show full SKILL.md (382 more words)Show less

Routes — style pack, grouped; references/style-index.md owns the per-topic map

AskRead
Which reference owns this topic — every guide topic, one row eachreferences/style-index.md
Prose: tone, person, voice, tense, grammar, one specific word, abbreviations, jargon, translation, inclusive termsreferences/style-voice.md, references/style-grammar.md, references/style-words.md, references/style-abbreviations.md, references/style-global.md, references/style-inclusive.md
Page shape: headings, lists, numbered steps, notices, tables, footnotes, figures, alt textreferences/style-structure.md, references/style-procedures.md, references/style-blocks.md, references/style-images.md
Mechanics: bold/italic/code choice, capitalization, filenames, markup, punctuation, numbers, dates, unitsreferences/style-format.md, references/style-punctuation.md, references/style-numbers.md
Technical text: code font, samples, command syntax, placeholders, example values, UI wording, link textreferences/style-code.md, references/style-cli.md, references/style-examples.md, references/style-ui.md, references/style-links.md
Claims and reference text: time words, superlatives, product names, trademarks, third-party text, docstringsreferences/style-claims.md, references/style-api.md
Producing a review someone else acts on, or checking a rule against the live guidereferences/style-review.md, references/style-sources.md

Scripts and assets — what to run, when, and how

RunWhenHow it behaves
scripts/style-lint.mjs <paths>At STYLE, before hand-reading proseMarkdown only. ERROR gates, WARN is mechanical, INFO needs judgment. One finding per rule per line; --max-per-rule caps per file (default 20); --only/--skip select rules; --json for machine output. Exit 1 on ERROR, or on WARN with --strict; 2 on bad usage
scripts/style-lint.mjs --self-testAfter editing any ruleLints built-in good/bad fixtures so a gate cannot go inert
scripts/refresh-word-list.mjs --dry-runWhen the word list looks staleRebuilds assets/google-word-list.tsv from developers.google.com; it fetches even with --dry-run, and refuses to write a short parse
assets/google-word-list.tsvAnswering a single-term question597 guide entries with verdict and guidance; quote it and stop
assets/google-style-pages.tsvFinding which reference owns a guide page, or its URLAll 69 pages as slug, title, owner, url; grep -P "^tables\t" answers ownership, and the URL is what you fetch to verify

Suppression: <!-- style-lint: ignore-file --> skips a file found by recursion, <!-- style-lint: ignore-line rule-id --> mutes named rules on one line. Both are inert inside a code span, so a page can document them. Docstrings, HTML, and UI strings stay hand-checked.

  • Pure code or repository evidence with no docs deliverable → octocode-research; authoring a SKILL.md → octocode-skills.
  • Full multi-file pack → plan the file set, gate it once, then work file by file.
  • Unclear mode → ask once: agent-docs / human-docs / adr / codebase-pack / style-pass. No Octocode → host search tools.
  • Measuring whether this skill triggers and holds its routes → octocode-graph-eval; the runnable sensors here are scripts/style-lint.mjs --self-test (rules still fire) and scripts/refresh-word-list.mjs --dry-run (word-list drift).

© bgauryy, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 36 other files (scripts, references, assets) in skills/octocode-documentation of bgauryy/octocode.

  • SKILL.md
  • README.md
  • assets/google-style-pages.tsv
  • assets/google-word-list.tsv
  • references/adr.md
  • references/agent-readable.md
  • references/agents-md.md
  • references/diataxis.md
  • references/evidence-research.md
  • references/modes.md
  • references/style-abbreviations.md
  • references/style-api.md
  • references/style-blocks.md
  • references/style-claims.md
  • references/style-cli.md
  • references/style-code.md
  • references/style-examples.md
  • references/style-format.md
  • references/style-global.md
  • … and 18 more

Open the folder on GitHubat commit c265e3f

Compare with similar skills

Evidence-Backed Documentation Writer next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Evidence-Backed Documentation Writer compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Evidence-Backed Documentation Writer this skillbgauryy/octocode949—~2kAutomated safety check: PassMIT
Technical Writingrsmdt/the-startup560—~1.3kAutomated safety check: PassMIT
Technical Documentation Templatesbybren-llc/safe-agentic-workflow423—~1.2kAutomated safety check: PassMIT
Technical Documentationkid-sid/claude-spellbook190—~3.4kAutomated safety check: NotesMIT
Simplified Technical Englishathola/claude-night-market341—~2kAutomated safety check: PassMIT
Obsidian WriterAtmosphere/atmosphere3.8k—~2.6kAutomated safety check: PassApache-2.0

Similar skills

  • Technical Writing

    rsmdt/the-startup

    Create architectural decision records (ADRs), system documentation, API documentation, and operational runbooks.

    560 GitHub stars~1.3k tokensUpdated 2 mo ago
    DevelopmentAuto-check passed
  • Technical Documentation Templates

    bybren-llc/safe-agentic-workflow

    Documentation templates for ADRs, runbooks, architecture docs, and knowledge transfer documents. Use when creating Architecture Decision Records, writing…

    423 GitHub stars~1.2k tokensUpdated 2 mo ago
    DevelopmentAuto-check passed
  • Technical Documentation

    kid-sid/claude-spellbook

    A skill your agent uses when writing a README, documenting an API with OpenAPI, drafting a runbook for on-call engineers, authoring a technical spec or ADR, or setting up docs-as-code with…

    190 GitHub stars~3.4k tokensUpdated 2 mo ago
    DevelopmentAuto-check: notes
  • Simplified Technical English

    athola/claude-night-market

    Applies an ASD-STE100-derived register to operator and procedural text.

    341 GitHub stars~2k tokensUpdated today
    DevelopmentAuto-check passed
  • Obsidian Writer

    Atmosphere/atmosphere

    Write well-formatted notes to the atmosphere-vault Obsidian knowledge base.

    3.8k GitHub stars~2.6k tokensUpdated yesterday
    DevOps & CloudAuto-check passed
  • Agent Style

    pchalasani/claude-code-tools

    Literature-backed English technical-prose writing rules (agent-style, 21 rules).

    2k GitHub stars~1.4k tokensUpdated yesterday
    DevelopmentAuto-check passed

More from bgauryy/octocode

All 12 skills in this repo
  • Runs blind pairwise comparisons of Octocode against a gh-based baseline over markdown research questions, scored by total characters through the model rather than self-report.

    949 GitHub stars~2.1k tokensUpdated yesterday
    Auto-check passed
  • Octocode Code Research

    bgauryy/octocode

    Researches code with evidence: traces callers, imports and cross-repo links, diagnoses failures and reports findings with exact file and line references and a confidence label.

    949 GitHub stars~1.5k tokensUpdated yesterday
    Auto-check passed
  • Octocode Mannequin

    bgauryy/octocode

    Poses and animates a 22-bone anatomical humanoid rig with joint range-of-motion limits, using a Node CLI, a Three.js viewer and WebMCP tools an agent can drive live.

    949 GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed
  • Octocode Skills Manager

    bgauryy/octocode

    Finds, rates, reviews, creates, improves, installs and syncs Agent Skill folders from local workspaces, registries or remote sources, with a user gate before any write.

    949 GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed
  • Octocode Brainstorming

    bgauryy/octocode

    Walks an idea through framing, diverging into options, researching evidence and stress-testing before converging on a build, prototype, narrow or park decision.

    949 GitHub stars~1.3k tokensUpdated yesterday
    Auto-check passed
  • Octocode Chrome Devtools

    bgauryy/octocode

    A skill your agent uses when a live page needs Chrome DevTools/CDP evidence: network failures, console errors, performance, DOM/CSS actionability, screenshots/PDF, cookies/storage…

    949 GitHub stars~1.6k tokensUpdated yesterday
    Auto-check passed

Questions about Evidence-Backed Documentation Writer

What does Evidence-Backed Documentation Writer do?

Writes, repairs and copyedits project docs against the Google developer documentation style guide, verifying claims in the repository before stating them. md, ADRs, migration guides, docstrings, alt text and prose linting. It follows the flow understand, research, classify, outline gate, write, style and verify.

When should I use Evidence-Backed Documentation Writer?

Evidence-Backed Documentation Writer fits situations like: rewriting a stale or inaccurate README against the real code; copyediting a doc to match the Google developer style guide; writing an ADR, runbook or migration guide from repository evidence; restructuring documentation using Diátaxis.

How do I install Evidence-Backed Documentation Writer in Claude Code?

Run `npx skills add bgauryy/octocode --skill octocode-documentation -a claude-code`. Or copy the skill folder (skills/octocode-documentation in bgauryy/octocode) into .claude/skills/octocode-documentation in your project. Claude Code loads it when a task matches its description.

How do I install Evidence-Backed Documentation Writer in Codex?

Run `npx skills add bgauryy/octocode --skill octocode-documentation -a codex`. Or copy the skill folder (skills/octocode-documentation in bgauryy/octocode) into .agents/skills/octocode-documentation in your project. Codex loads it when a task matches its description.

Can I use Evidence-Backed Documentation Writer in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add bgauryy/octocode --skill octocode-documentation -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/octocode-documentation, .gemini/skills/octocode-documentation, .github/skills/octocode-documentation and .opencode/skills/octocode-documentation in your project.

What does Evidence-Backed Documentation Writer need to run?

SKILL.md names no scripts, command-line tools or credentials: Evidence-Backed Documentation Writer is instructions for the agent only.

Does Evidence-Backed Documentation Writer access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Evidence-Backed Documentation Writer safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Evidence-Backed Documentation Writer use?

Evidence-Backed Documentation Writer is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Evidence-Backed Documentation Writer use?

About 2k tokens (SKILL.md is roughly 8.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 24k tokens, read only when the agent opens those files.

What are the alternatives to Evidence-Backed Documentation Writer?

Skills that share tags, products or a category with Evidence-Backed Documentation Writer: Technical Writing (rsmdt/the-startup, 560 stars), Technical Documentation Templates (bybren-llc/safe-agentic-workflow, 423 stars), Technical Documentation (kid-sid/claude-spellbook, 190 stars) and Simplified Technical English (athola/claude-night-market, 341 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Evidence-Backed Documentation Writer?

bgauryy (a GitHub user) maintains it in bgauryy/octocode, which has 949 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on October 9, 2026.

Source: bgauryy/octocode on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.