flow-docs skill
✓ VerifiedWrite and audit technical documentation, agent instructions, pull requests, and changelogs using manifest-driven source coverage and anti-bloat rules.
- GitHub stars
- 20
- Files
- 4
- Last commit
- Nov 8, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the flow-docs skill do?
flow-docs writes and audit technical documentation, agent instructions, pull requests, and changelogs using manifest-driven source coverage and anti-bloat rules.
Summary generated from the skill's SKILL.md.
About the flow-docs skill
Writing and auditing technical documentation, agent instructions, and pull requests is the primary function of this skill. It helps engineers and AI developers maintain high-quality prose by enforcing strict anti-bloat rules and manifest-driven source coverage. When an agent loads this skill, it can author READMEs, user guides, and agent-specific files like AGENTS.md or SKILL.md by first reading the source code to ensure every claim is anchored to a specific file and symbol.
Users can interact with the skill through specific operational modes such as write, validate, capture, sync, and pr. The validate mode audits documentation for comprehension and broken links, while the capture mode distills architectural patterns into knowledge bundles. The skill relies on reference files for prose standards, agent context, and pull request conventions to ensure all output remains in the present tense and free of historical sediment or promotional adjectives. It is designed to produce clean, matter-of-fact technical content that passes a cold-reader comprehension test.
What an agent can do with it
- 1Authoring technical documentationGenerate READMEs or user guides by reading implementation files to ensure complete coverage.
- 2Auditing agent instruction filesCheck agent bundles for comprehension and accuracy against the actual source code.
- 3Drafting pull requestsCreate structured pull request bodies and changelogs that follow specific formatting rules.
- 4Distilling architectural patternsConvert completed code flows and patterns into structured knowledge chapters for agents.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the flow-docs skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the flow-docs skill in Plugin
/plugin marketplace add cofin/flow /plugin install flow@flow-marketplace
Install the flow-docs skill in Claude Code
~/.claude/skills/flow-docs/SKILL.md
$ npx degit cofin/flow/skills/flow-docs ~/.claude/skills/flow-docsInstall the flow-docs skill in Claude Code (project)
.claude/skills/flow-docs/SKILL.md
$ npx degit cofin/flow/skills/flow-docs .claude/skills/flow-docsInstall the flow-docs skill in Codex
~/.agents/skills/flow-docs/SKILL.md
$ npx degit cofin/flow/skills/flow-docs ~/.agents/skills/flow-docsInstall the flow-docs skill in Gemini CLI
~/.gemini/skills/flow-docs/SKILL.md
$ npx degit cofin/flow/skills/flow-docs ~/.gemini/skills/flow-docsInstall the flow-docs skill in Claude.ai
npx degit cofin/flow/skills/flow-docs flow-docs && zip -r flow-docs.zip flow-docs # claude.ai → Customize → Skills → + → Create skill → Upload a skill → flow-docs.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablecofin/flow/skills/flow-docs is public and reachablegithub.com/cofin/flow/tree/HEAD/skills/flow-docs ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-08github.com/cofin/flow/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/cofin/flow/blob/HEAD/skills/flow-docs/SKILL.md ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/cofin/flow/blob/HEAD/skills/flow-docs/SKILL.md ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 68 linesgithub.com/cofin/flow/blob/HEAD/skills/flow-docs/SKILL.md ↗Pass
SKILL.md
View on GitHubDocumentation, Prose, Agent Instructions, & Pull Requests (flow-docs)
Write clear, accurate, zero-bloat technical documentation, user guides, agent instruction files (AGENTS.md, SKILL.md, OKF knowledge chapters), commit messages, changelogs, and pull requests.
Operational Modes (/flow:docs [mode])
write— Author or update READMEs, user guides, module documentation, or agent skills using manifest-driven source coverage ([k/N files documented]).validate— Audit documentation and.agents/bundles/for cold-reader comprehension, primary-sourcepath/to/file::Symbolaccuracy, broken links, and prose sediment.capture— Distill validated architectural and operational patterns from code and completed flows into.agents/bundles/knowledge/and user-facingdocs/.sync— Reconcile documentation claims and examples against live repository signatures and configuration.pr— Draft or update pull request titles,## Summary+## Key Changesbodies, signed commits, and release changelogs.
Core Writing & Anti-Bloat Rules
- Pass the Cold-Reader Comprehension Test. Every document must be understandable on the first read by a fresh engineer or isolated zero-context agent with no prior session history. Lead with purpose, public interface, concrete examples, and invariants.
- Read source before writing (
[k/N files documented]). Enumerate the in-scope files first, read every file completely, and anchor claims topath/to/file::Symbol. Never guess behavior from filenames or function names. - State rules plainly with a one-line
Reason:. Write direct, present-tense sentences. When documenting a constraint or design choice, state the rule followed byReason: <why>. - Eliminate AI slop, buzzwords, and chronological sediment.
- Never use promotional adjectives (
seamless,robust,comprehensive,pivotal,delve,leverage,blazingly fast), decorative adverbs (seamlessly,effortlessly,obviously), negative parallelisms ("not just X, but Y"), formulaic transitions ("Moreover","Furthermore"), or superficial participle tails ("...ensuring reliability"). - Never use artificial numbered buzzword labels or inflated metaphors (
"engineering lawbooks","causal waterfall","zero-tolerance"). Name components and headings semantically so counts never break when items change. - Never leave chronological sediment (
"Added in v2","Previously we used X") inside current-state documentation or specs. History belongs inCHANGELOG.mdand.agents/bundles/log.md.
- Never use promotional adjectives (
- Never leak internal workflow ceremony or private paths. Keep PRs, commits, changelogs, tests, and docs free of finding counts, task/finding IDs (
ORA-001,test_task_1_2_*), workflow mechanics (checkpoint.phase, subagent names),## Verificationcommand logs,## Merge Dangerblocks, ASCII file/call trees, or local workstation paths.
Reference Guides
| Area | Reference File | Key Topics |
|---|---|---|
| Technical Prose & Documentation | references/prose-and-documentation.md |
Cold-reader comprehension standard, manifest-driven coverage ([k/N files documented]), component scaling templates, guide structure, diagram rules, validation report |
Agent Context, .agents/, & Harness Config |
references/agent-context.md |
Cross-harness .agents/ discovery (skills, subagents, rules, hooks, MCP configs), context load vs. cognitive load, information hierarchy, context pointers, progressive disclosure, completion criteria, leading words, positive framing, pruning discipline |
| Pull Requests, Commits, & Changelogs | references/prs-commits-and-changelogs.md |
<type>(<scope>): <summary> titles, ## Summary + ## Key Changes PR bodies, signed commits, changelog conventions, inline PR reviews, GitHub issues |
Workflow
- Select Target & Reference:
- For READMEs, user guides, module/API docs, or doc audits, load
references/prose-and-documentation.md. - For
AGENTS.md,SKILL.md, subagents, or.agents/bundles/knowledge/chapters, loadreferences/agent-context.md. - For PRs, commits, changelogs, or code review comments, load
references/prs-commits-and-changelogs.md.
- For READMEs, user guides, module/API docs, or doc audits, load
- Build Manifest & Shard Primary-Source Authoring:
- List every file in scope (
[0/N files documented]) and read each implementation file before drafting prose. - When documenting or syncing
>= 2domains, subsystems, or chapters (/flow:docs write | capture | sync), fan out isolated per-domain or per-chapter documentation subagents so each file receives thorough, runnable, code-verified examples rather than a compressed summary.
- List every file in scope (
- Draft in Present Tense to Match Target Length & Hierarchy:
- Keep user guides focused on a single concept (
<= 200lines), leading with a runnable example and expected output. - Keep living specs (
specs/<flow_id>/spec.md,chapters/index.md,chapters/<ch_id>/spec.md),.agents/bundles/knowledge/**chapters, and userdocs/strictly in present tense—stating current verified reality, remaining chapters, and the full plan with zeroRevision Historysections or historical layering. - Keep
SKILL.mdfiles<= 200lines (< 24,000bytes),<!-- truth: start -->blocks<= 40lines, and bundle bodies free of standalone---horizontal rules, disclosing deep reference material intoreferences/*.md.
- Keep user guides focused on a single concept (
- Verify & Prune:
- Strip puffery, chronological sediment, duplicate cache lines, and workflow ceremony, then verify all links and examples (
make lint).
- Strip puffery, chronological sediment, duplicate cache lines, and workflow ceremony, then verify all links and examples (
Guardrails
- Conceptual Diagrams Only in
docs/: Keep Mermaid diagrams in user-facingdocs/andREADME.mdconceptual (4–6nodes focused on the user mental model). Place detailed module/implementation diagrams in.agents/bundles/knowledge/architecture/. - Single Source of Truth: Link to canonical rules rather than duplicating them across files.
- Calm, Matter-of-Fact Tone: Never use exclamation marks (
!) or dismissive language in documentation, PR bodies, or code reviews.
Validation
- Confirm every manifest item is covered (
[N/N files documented]) and every technical claim cites a verified source (path/to/file::Symbol). - Confirm PR bodies contain only
## Summaryand## Key Changesand every PR#or Issue#in chat is a clickable Markdown link. - Confirm all relative Markdown links resolve on disk and
make lintexits0.
Example
Invoke /flow:docs write to document a module with [4/4 files documented] coverage tracking, /flow:docs validate to audit .agents/bundles/ and docs/ for stale symbols or prose bloat, or /flow:docs pr when preparing a pull request in /flow:finish.
Files in this skill
4flow-docs skill questions
How do I install the flow-docs skill in Claude Code?
Run npx degit cofin/flow/skills/flow-docs ~/.claude/skills/flow-docs. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the flow-docs skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How does the skill ensure documentation accuracy?
It uses manifest-driven source coverage by enumerating in-scope files and reading them completely to anchor claims to specific file symbols.
What kind of language should be avoided in the documentation?
The skill mandates eliminating 'AI slop,' promotional adjectives like 'seamless' or 'robust,' decorative adverbs, and chronological sediment like 'Added in v2'.