Beads Documentation Style Guide
gastownhall/beads
Sets the house style for the beads user docs: the canonical concept model, required terminology, prose and diagram conventions, and checks before docs work is done.
Writing clear, discoverable software documentation following the Eight Rules and Diataxis framework.
Install Documentation Writing
$ npx skills add tmcfarlane/oh-my-cursor --skill documentation-writing -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install tmcfarlane/oh-my-cursor documentation-writing --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/tmcfarlane/oh-my-cursor.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/documentation-writing .claude/skills/documentation-writing && rm -rf skills-srcUse ~/.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/
Install the "documentation-writing" agent skill from https://github.com/tmcfarlane/oh-my-cursor/tree/main/skills/documentation-writing into .claude/skills/documentation-writing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation-writing", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/tmcfarlane/oh-my-cursor/tree/main/skills/documentation-writingType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add tmcfarlane/oh-my-cursor --skill documentation-writing -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install tmcfarlane/oh-my-cursor documentation-writing --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/tmcfarlane/oh-my-cursor.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/documentation-writing .agents/skills/documentation-writing && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "documentation-writing" agent skill from https://github.com/tmcfarlane/oh-my-cursor/tree/main/skills/documentation-writing into .agents/skills/documentation-writing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation-writing", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add tmcfarlane/oh-my-cursor --skill documentation-writing -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install tmcfarlane/oh-my-cursor documentation-writing --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/tmcfarlane/oh-my-cursor.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/documentation-writing .cursor/skills/documentation-writing && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "documentation-writing" agent skill from https://github.com/tmcfarlane/oh-my-cursor/tree/main/skills/documentation-writing into .cursor/skills/documentation-writing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation-writing", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/tmcfarlane/oh-my-cursor.git --path skills/documentation-writing--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add tmcfarlane/oh-my-cursor --skill documentation-writing -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install tmcfarlane/oh-my-cursor documentation-writing --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/tmcfarlane/oh-my-cursor.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/documentation-writing .gemini/skills/documentation-writing && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "documentation-writing" agent skill from https://github.com/tmcfarlane/oh-my-cursor/tree/main/skills/documentation-writing into .gemini/skills/documentation-writing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation-writing", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install tmcfarlane/oh-my-cursor documentation-writingInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add tmcfarlane/oh-my-cursor --skill documentation-writing -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/tmcfarlane/oh-my-cursor.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/documentation-writing .github/skills/documentation-writing && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "documentation-writing" agent skill from https://github.com/tmcfarlane/oh-my-cursor/tree/main/skills/documentation-writing into .github/skills/documentation-writing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation-writing", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add tmcfarlane/oh-my-cursor --skill documentation-writing -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install tmcfarlane/oh-my-cursor documentation-writing --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/tmcfarlane/oh-my-cursor.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/documentation-writing .opencode/skills/documentation-writing && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "documentation-writing" agent skill from https://github.com/tmcfarlane/oh-my-cursor/tree/main/skills/documentation-writing into .opencode/skills/documentation-writing/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "documentation-writing", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
documentation-writing- GitHub stars
- 110
- Token cost
- ~1.4k tokens
- SKILL.md length
- 419 words
- Files
- 3
- Skills in repo
- 14
- Repo updated
- First seen
- Licence
- MIT
At a glance
Writing clear, discoverable software documentation following the Eight Rules and Diataxis framework.
- Works in 5 steps: Determine Document Type → Choose Location → Write with Examples → …
- Creating README files
- SKILL.md covers Purpose, When I Activate, Core Rules (MANDATORY) and Quick Start, plus 4 more sections
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Documentation Writing is an agent skill from tmcfarlane/oh-my-cursor. Writing clear, discoverable software documentation following the Eight Rules and Diataxis framework. Use when creating README files, API docs, tutorials, how-to guides, or any project documentation. Automatically enforces docs/ location, linking requirements, and runnable examples.
Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files (for example `examples.md` and `reference.md`).
It sits in Writing & Content, covering Technical writing and Technical documentation. The repository describes itself as: Like “oh-my-opencode”, but for Cursor IDE. Multi-agent orchestration, natively, using nothing but a few config files. The licence is MIT.
When your agent uses it
- Creating README files
- Any project documentation
Example prompts
- “/documentation-writing”
Requirements
- Python 3
Workflow steps
5 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit 5bad458. 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
No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown and python).
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
Documentation Writing loads about 1.4k tokens when it runs. Until then it costs about 76 tokens; SKILL.md has 419 words of instructions outside code blocks.
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); files beside SKILL.md are not scanned.
SKILL.md
The full file from tmcfarlane/oh-my-cursor at commit 5bad458, republished under its MIT licence (© tmcfarlane). 419 words, ~1,446 tokens.
Download SKILL.mdSave it as
.claude/skills/documentation-writing/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.- name
- documentation-writing
- description
- Writing clear, discoverable software documentation following the Eight Rules and Diataxis framework. Use when creating README files, API docs, tutorials, how-to guides, or any project documentation. Automatically enforces docs/ location, linking requirements, and runnable examples.
- version
- 1.0.0
- source_urls
- https://diataxis.fr/, https://www.writethedocs.org/guide/writing/docs-principles/, https://github.blog/developer-skills/documentation-done-right-a-developers-g…
- auto_activates
- write documentation, create docs, document this feature, create a README, write a tutorial, api docs, how-to guide
- token_budget
- 1800
Documentation Writing Skill
Purpose
Creates high-quality, discoverable documentation following the Eight Rules and Diataxis framework. Ensures all docs are properly located, linked, and contain real runnable examples.
When I Activate
I load automatically when you mention:
- "write documentation" or "create docs"
- "document this feature/module/API"
- "create a README" or "write a tutorial"
- "explain how this works"
- Any request to create markdown documentation
Core Rules (MANDATORY)
The Eight Rules
- Location: All docs in
docs/directory - Linking: Every doc linked from at least one other doc
- Simplicity: Plain language, remove unnecessary words
- Real Examples: Runnable code, not "foo/bar" placeholders
- Diataxis: One doc type per file (tutorial/howto/reference/explanation)
- Scanability: Descriptive headings, table of contents for long docs
- Local Links: Relative paths, context with links
- Currency: Delete outdated docs, include update metadata
What Stays OUT of Docs
Never put in docs/:
- Status reports or progress updates
- Test results or benchmarks
- Meeting notes or decisions
- Plans with dates
- Point-in-time snapshots
Where temporal info belongs:
- Test results → CI logs, GitHub Actions
- Status updates → GitHub Issues
- Progress → Pull Request descriptions
- Decisions → Commit messages
Quick Start
Creating a New Document
# [Feature Name]
Brief one-sentence description of what this is.
## Quick Start
Minimal steps to get started (3-5 steps max).
## Contents
- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)
## Configuration
Step-by-step setup with real examples.
## Usage
Common use cases with runnable code.
## Troubleshooting
Common problems and solutions.Document Types (Diataxis)
| Type | Purpose | Location | User Question |
|---|---|---|---|
| Tutorial | Learning | docs/tutorials/ | "Teach me how" |
| How-To | Doing | docs/howto/ | "Help me do X" |
| Reference | Information | docs/reference/ | "What are the options?" |
| Explanation | Understanding | docs/concepts/ | "Why is it this way?" |
Workflow
Step 1: Determine Document Type
Ask: What is the reader trying to accomplish?
- Learning something new → Tutorial
- Solving a specific problem → How-To
- Looking up details → Reference
- Understanding concepts → Explanation
Show full SKILL.md (165 more words)Show less
Step 2: Choose Location
docs/
├── tutorials/ # Learning-oriented
├── howto/ # Task-oriented
├── reference/ # Information-oriented
├── concepts/ # Understanding-oriented
└── index.md # Links to all docsStep 3: Write with Examples
Every concept needs a runnable example:
# Example: Analyze file complexity
from amplihack import analyze
result = analyze("src/main.py")
print(f"Complexity: {result.score}")
# Output: Complexity: 12.5Step 4: Link from Index
Add entry to docs/index.md:
- [New Feature Guide](./howto/new-feature.md) - How to configure XStep 5: Validate
Checklist before completion:
- File in
docs/directory - Linked from index or parent doc
- No temporal information
- All examples tested
- Follows one Diataxis type
Navigation Guide
When to Read Supporting Files
reference.md - Read when you need:
- Complete frontmatter specification
- Detailed Diataxis type definitions
- Markdown style conventions
- Documentation review checklist
examples.md - Read when you need:
- Full document templates for each type
- Real-world documentation examples
- Before/after improvement examples
- Complex documentation patterns
Anti-Patterns to Avoid
| Anti-Pattern | Why It's Bad | Better Approach |
|---|---|---|
| "Click here" links | No context | "See auth config" |
| foo/bar examples | Not realistic | Use real project code |
| Wall of text | Hard to scan | Use headings and bullets |
| Orphan docs | Never found | Link from index |
| Status in docs | Gets stale | Use Issues/PRs |
Retcon Documentation Exception
When writing documentation BEFORE implementation (document-driven development):
# [PLANNED - Implementation Pending]
This document describes the intended behavior of Feature X.
## Planned Interface
```python
# [PLANNED] - This API will be implemented
def future_function(input: str) -> Result:
"""Process input and return result."""
pass
```Once implemented, remove the [PLANNED] markers and update with real examples.
---
**Full reference**: See [reference.md](./reference.md) for complete specification.
**Templates**: See [examples.md](./examples.md) for copy-paste templates.© tmcfarlane, 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 2 other files in skills/documentation-writing of tmcfarlane/oh-my-cursor.
- SKILL.md
- examples.md
- reference.md
Open the folder on GitHubat commit 5bad458
Compare with similar skills
Documentation Writing 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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Documentation Writing this skilltmcfarlane/oh-my-cursor | 110 | — | ~1.4k | Automated safety check: Pass | MIT | |
| Beads Documentation Style Guidegastownhall/beads | 28k | — | ~3.2k | Automated safety check: Pass | MIT | |
| Technical Writing Standardcursor/plugins | 10k | 10 repos | ~2.4k | Automated safety check: Pass | None | |
| Heym Documentation Articlesheymrun/heym | 1.4k | — | ~780 | Automated safety check: Pass | Custom licence | |
| Developer Docs Technical Writervercel-labs/github-tools | 131 | — | ~3.9k | Automated safety check: Pass | MIT | |
| Aholo Viewer Docsmanycoretech/aholo-viewer | 1.1k | — | ~341 | Automated safety check: Pass | MIT |
Similar skills
- Official
Technical Writing Standard
cursor/plugins
Applies four layers of technical-writing rules to docs, RFCs, readmes, PR descriptions and commit messages so a tired engineer follows them on the first read.
Heym Documentation Articles
heymrun/heym
Creates and updates documentation articles for the Heym platform: category choice, manifest entry, markdown file and cross-links from existing pages.
- Official
Developer Docs Technical Writer
vercel-labs/github-tools
Writes, reviews and edits developer documentation for SDKs, libraries and frameworks, from getting-started guides and API references to migration guides.
Aholo Viewer Docs
manycoretech/aholo-viewer
Guides writing and maintaining Aholo Viewer documentation: README, AGENTS.md, architecture notes, bilingual manual pages and AI collaboration guides.
Diataxis
WebMCP-org/npm-packages
Write technical documentation following the Diataxis framework by Daniele Procida.
More from tmcfarlane/oh-my-cursor
All 14 skills in this repoDocs Write
tmcfarlane/oh-my-cursor
Write documentation following Metabase's conversational, clear, and user-focused style.
Debugging
tmcfarlane/oh-my-cursor
Systematic 4-phase debugging with root cause investigation. An agent skill from tmcfarlane/oh-my-cursor.
Documentation Engineer
tmcfarlane/oh-my-cursor
Technical documentation expert for creating clear, comprehensive documentation.
Planning
tmcfarlane/oh-my-cursor
Technical implementation planning and architecture design. An agent skill from tmcfarlane/oh-my-cursor.
Codebase Search
tmcfarlane/oh-my-cursor
Search and navigate large codebases efficiently. An agent skill from tmcfarlane/oh-my-cursor.
Cursor Image Generation
tmcfarlane/oh-my-cursor
Generate and iterate images in Cursor using the built-in image model and strong prompts.
Related
Categories
Questions about Documentation Writing
What does Documentation Writing do?
Writing clear, discoverable software documentation following the Eight Rules and Diataxis framework. Documentation Writing is an agent skill from tmcfarlane/oh-my-cursor. Writing clear, discoverable software documentation following the Eight Rules and Diataxis framework.
When should I use Documentation Writing?
Documentation Writing fits situations like: creating README files; any project documentation.
How do I install Documentation Writing in Claude Code?
Run `npx skills add tmcfarlane/oh-my-cursor --skill documentation-writing -a claude-code`. Or copy the skill folder (skills/documentation-writing in tmcfarlane/oh-my-cursor) into .claude/skills/documentation-writing in your project. Claude Code loads it when a task matches its description.
How do I install Documentation Writing in Codex?
Run `npx skills add tmcfarlane/oh-my-cursor --skill documentation-writing -a codex`. Or copy the skill folder (skills/documentation-writing in tmcfarlane/oh-my-cursor) into .agents/skills/documentation-writing in your project. Codex loads it when a task matches its description.
Can I use Documentation Writing 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 tmcfarlane/oh-my-cursor --skill documentation-writing -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/documentation-writing, .gemini/skills/documentation-writing, .github/skills/documentation-writing and .opencode/skills/documentation-writing in your project.
What does Documentation Writing need to run?
SKILL.md names no scripts, command-line tools or credentials: Documentation Writing is instructions for the agent only. Our summary lists: Python 3.
Does Documentation Writing 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 Documentation Writing 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. Review the folder before installing.
What licence does Documentation Writing use?
Documentation Writing 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 Documentation Writing use?
About 1.4k tokens (SKILL.md is roughly 5.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Documentation Writing?
Skills that share tags, products or a category with Documentation Writing: Beads Documentation Style Guide (gastownhall/beads, 28k stars), Technical Writing Standard (cursor/plugins, 10k stars), Heym Documentation Articles (heymrun/heym, 1.4k stars) and Developer Docs Technical Writer (vercel-labs/github-tools, 131 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Documentation Writing?
tmcfarlane (a GitHub user) maintains it in tmcfarlane/oh-my-cursor, which has 110 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on July 2, 2026.
Source: tmcfarlane/oh-my-cursor on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.