Agent skill

Documentation Strategy

by rampstackco in rampstackco/claude-skills

Design and run a documentation system for a team or product.

MITAuto-check passedWriting & Content

Install Documentation Strategy

skills CLI
$ npx skills add rampstackco/claude-skills --skill documentation-strategy -a claude-code

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

GitHub CLI
$ gh skill install rampstackco/claude-skills documentation-strategy --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/rampstackco/claude-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/documentation-strategy .claude/skills/documentation-strategy && 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
documentation-strategy
GitHub stars
940
Token cost
~3.3k tokens
SKILL.md length
1,680 words
Files
3 (incl. references)
Skills in repo
103
Repo updated
First seen
Licence
MIT

At a glance

Design and run a documentation system for a team or product.

  • Works in 10 steps: Audit current state → Categorize and tier → Identify gaps → …
  • Planning what to document
  • SKILL.md covers When to use, When NOT to use, Required inputs and The framework: 4 categories of…, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Documentation Strategy is an agent skill from rampstackco/claude-skills. Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding…

Its SKILL.md is about 3.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including reference files (for example `README.md` and `references/doc-types-guide.md`).

It sits in Writing & Content, covering Runbooks and postmortems, Technical writing and Knowledge bases. The repository describes itself as: Stack-agnostic Claude Skills covering the full website lifecycle: brand, design, content, SEO, dev, ops, growth, and research. Build, ship, audit, optimize. The licence is MIT.

When your agent uses it

  • Planning what to document
  • Choosing a documentation tool
  • Organizing existing docs
  • Fixing stale documentation

Example prompts

  • “/documentation-strategy”

Workflow steps

10 steps, taken from the step headings in SKILL.md.

  1. Audit current state
  2. Categorize and tier
  3. Identify gaps
  4. Identify dead weight
  5. Pick the home(s)
  6. Establish ownership
  7. Establish maintenance cadence
  8. Make doc updates part of work
  9. Make docs discoverable
  10. Measure

What it can do on your machine

Read from SKILL.md and the folder at commit 482c9bf. 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.

    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 Strategy loads about 3.3k tokens when it runs, and up to ~5.9k if it reads all its reference files. Until then it costs about 138 tokens; SKILL.md has 1,680 words of instructions outside code blocks.

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

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 rampstackco/claude-skills at commit 482c9bf, republished under its MIT licence (© rampstackco). 1,680 words, ~3,265 tokens.

Download SKILL.mdSave it as .claude/skills/documentation-strategy/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
documentation-strategy
description
Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding takes too long.
category
process-and-team
catalog_summary
Documentation systems, what to document, maintenance cadence
display_order
2

Documentation Strategy

Decide what gets documented, where, by whom, and how it stays fresh. Stack-agnostic. Applies to internal team docs, product docs, runbooks, READMEs, and knowledge bases.


When to use

  • Setting up documentation for a new team or product
  • Auditing existing documentation
  • Fixing stale or scattered docs
  • Choosing a documentation tool or platform
  • Defining what gets documented and what doesn't
  • Establishing maintenance cadence
  • Scoping technical writing work
  • Designing onboarding documentation (use alongside team-onboarding-playbook)

When NOT to use

  • Writing the actual content of a single document (use content-and-copy)
  • Customer-facing knowledge base copy (use content-strategy)
  • Code comments and inline documentation (covered by code-review-web)
  • One-off blog posts or articles (use content-and-copy)

Required inputs

  • The audience (internal, external, customer, dev, exec)
  • Existing docs and their state (where, what shape, last updated)
  • Team size and growth trajectory
  • The kinds of work that produce documentation (engineering, product, ops, support)
  • Tools currently in use

The framework: 4 categories of documentation

Different categories of doc serve different purposes. Conflating them is how docs get bad.

Category 1: Reference

What things are. Looked up when needed.

Examples: API reference, configuration options, glossary, architecture diagrams, contact lists, decision log entries.

Properties:

  • Comprehensive
  • Fact-checked, kept accurate
  • Searchable
  • Stable structure (links don't break)
  • Version-aware where relevant
Category 2: How-to

How to do specific tasks. Procedural.

Examples: "Deploy to staging," "Reset a password," "Onboard a new contractor," "Run the backup restore drill."

Properties:

  • Step-by-step
  • Tested by someone who didn't write it
  • Includes the prerequisites
  • Includes troubleshooting
  • Versioned to the system it documents
Category 3: Explanation

Why things are the way they are. Conceptual.

Examples: architecture rationale, design decision records (ADRs), strategy docs, vision documents.

Properties:

  • Narrative
  • Captures context (the why)
  • Often historical (why we built it this way)
  • Links to evidence
Category 4: Tutorial

Learning-oriented. Walks someone from zero to capable.

Examples: "Getting started with our codebase," "Your first deploy," onboarding pathways.

Properties:

  • Sequenced from simple to complex
  • Hands-on
  • Doesn't assume prior knowledge in scope
  • Has clear completion criteria

(This four-way split is the Diátaxis framework, well-known in tech writing. Memorize it.)


The framework: 5 tiers of doc

Different docs serve different audiences with different stakes.

Tier 1: Customer-facing

Public docs, customer KBs, API references. High visibility, slow change.

Standards:

  • Editorial review
  • Version control
  • Clear ownership
  • High freshness bar
  • Tied to release
Tier 2: Cross-team / shared

Docs used across teams: shared APIs, common services, company-wide processes.

Standards:

  • Cross-team ownership clear
  • Update obligations on changes
  • Mid-to-high freshness bar
Tier 3: Team-internal

Docs for the team that owns them: how the team works, runbooks, decisions.

Standards:

  • Team-owned, team-maintained
  • Mid freshness bar
  • Useful for the next person joining
Tier 4: Personal scratchpad

Notes, drafts, work-in-progress. Not for others.

Standards:

  • Low maintenance
  • Don't link from official docs
  • Promote to higher tier when valuable
Tier 5: Auto-generated

Docs derived from code: API references generated from comments, schemas, etc.

Standards:

  • Generation is automated, runs in CI
  • Single source of truth (the code)
  • Reviewed for usability, not freshness (that's automatic)

The tiering matters because the maintenance bar differs. Asking team-internal docs to meet customer-facing standards is wasteful and unsustainable.


Workflow

Step 1: Audit current state
  • What docs exist?
  • Where do they live? (often: scattered)
  • Who owns each?
  • How fresh are they?
  • Are they actually used? (check page views or referrals if measurable)

The audit is often eye-opening. Most teams have more docs than they realize, in more places than they realize.

Step 2: Categorize and tier

For each doc:

  • Category (reference / how-to / explanation / tutorial)
  • Tier (customer / shared / team / scratchpad / generated)

Some docs are mixed. Note the dominant category.

Step 3: Identify gaps

What documentation does the team need that doesn't exist?

Common gaps:

  • "How does X actually work?" no answer
  • Onboarding for the role no one's onboarded recently
  • Runbook for a system that's never broken (yet)
  • Decision rationale for "why are we doing it this way"

Ask people what they wish were documented. They know.

Step 4: Identify dead weight

Docs that are:

  • Out of date and not getting updated
  • Duplicated across places (one is canonical, others should redirect or be deleted)
  • About things that no longer exist
  • Drafts abandoned long ago

Delete or archive. Stale docs are worse than missing docs (people might trust them).

Step 5: Pick the home(s)

Where docs live affects whether they're maintained.

Common locations:

  • Code repo (markdown): for docs tightly coupled to code (READMEs, ADRs, runbooks for the service)
  • Wiki / Notion / Confluence: for cross-team and team-internal
  • Docs site (Docusaurus, Mintlify, custom): for customer-facing
  • Tickets / decision logs: for ephemeral records

Don't aim for one home. Aim for a clear answer to "where does this kind of doc live?"

Step 6: Establish ownership

Every doc has an owner. Without an owner, it goes stale.

Owner can be:

  • A team
  • A role (the on-call rotation, the PM, the EM)
  • A person, with a backup

If an owner isn't obvious, the doc may not deserve to exist.

Step 7: Establish maintenance cadence

Per tier:

TierReview cadence
Customer-facingPer release, plus quarterly
Cross-teamQuarterly
Team-internalQuarterly
Personal scratchpadNone
Auto-generatedOn every change

Maintenance includes:

  • Verify accuracy
  • Update for changed systems
  • Archive what's no longer relevant
  • Address user feedback
Step 8: Make doc updates part of work

Documentation isn't a separate project. It's part of the work that produces it.

  • New feature: docs are part of the feature
  • New process: doc is part of the rollout
  • Decision made: ADR or decision-log entry filed
  • Bug postmortem: runbook updated
  • New hire: onboarding doc updated based on their experience

The team that ships features without docs has less than they think they have.

Step 9: Make docs discoverable

Even great docs are useless if no one finds them.

  • Search that actually works (most platforms; some better than others)
  • Index pages for major topics
  • Cross-links between related docs
  • Search aliases for common alternative phrasings
  • Pinning the most-used docs
Step 10: Measure

What's measurable depends on the platform:

  • Page views
  • Search queries (and zero-result queries)
  • "Was this helpful?" feedback
  • Time on page
  • Referral patterns

For internal docs, the qualitative measure is often more useful: are the same questions getting asked over and over? If yes, the docs aren't doing their job (either they don't exist, aren't found, or aren't clear).


Show full SKILL.md (653 more words)Show less

Specific patterns

README per project

Every code repo has a README that answers:

  • What is this?
  • How do I run it?
  • How do I contribute?
  • Where do I find more info?

Five sentences each, often. Length isn't the goal. The READ-it-ME promise is.

ADR (Architecture Decision Record)

Per significant decision:

# ADR-NNN: [Title]

Status: [Proposed / Accepted / Deprecated / Superseded]
Date: [Date]

## Context
[What's the situation? What forces are at play?]

## Decision
[What was decided?]

## Consequences
[What happens because of this decision? Both good and bad.]

ADRs accumulate. They become the explanation layer for "why are we doing it this way."

Runbook

Per system:

  • What it is
  • How to access it
  • Common operations (with commands)
  • Common failure modes
  • Restore from backup procedure
  • Escalation contacts

See incident-response and backup-and-disaster-recovery for runbook standards.

Onboarding pathway

Per role:

  • Day 1
  • Week 1
  • Month 1
  • 90 days

See team-onboarding-playbook.

Decision log

Lightweight version of ADRs. Date, decision, decider, why. Keeps a record without ceremony.

Glossary

Terms that have specific meaning in the team or product. Reduces confusion. Trains AI tools too (more on that later).


Tooling

The tool is less important than the discipline. That said:

Tool categoryExamplesBest for
WikiNotion, Confluence, GitBookCross-team, internal
Markdown in codeGitHub, GitLab, BitbucketREADMEs, ADRs, technical
Docs sitesDocusaurus, Mintlify, ReadMeCustomer-facing, public docs
Internal sitesMkDocs, customTeam-specific patterns

Considerations:

  • Search quality (a poor search makes everything worse)
  • Editor quality (people won't write in painful editors)
  • Version control (can you see history?)
  • Permissions (right people can read and write)
  • API and integration (for automation)
  • Cost at your scale

For small teams: a single wiki tool is plenty. For larger: tiered tools.


LLMs and AI assistants increasingly read documentation. Some considerations:

  • Clear, consistent structure helps both humans and AI
  • A glossary of terms helps both
  • File-level metadata (front matter) helps tools
  • Public docs may be read by AI crawlers; consider an llms.txt if relevant
  • AI-generated drafts are a starting point, not a final answer; humans review

Failure patterns

Documentation as a "later" task. Always written later. Later means never. Make docs part of the work.

One mega-doc for everything. Wiki page that's 8,000 words. No one reads it. Break by category and topic.

Stale docs that nobody trusts. "Probably out of date" is the thought that kills documentation. Either keep current or archive.

Docs everyone agrees should exist but no one writes. The team agrees onboarding docs would be valuable. Months pass. No one writes them. Make ownership specific.

Wikis that are graveyards. Lots of pages, no one trusts any of them. Audit, archive, restart with a slimmer set.

Docs separated from code. API docs in a wiki, code in a repo. They drift. Co-locate.

Docs without examples. Reference without examples is hard to use. Examples make it concrete.

Examples that don't run. Code examples that worked once, drifted. Test examples in CI where possible.

Long-form when reference would do. A 2,000-word doc explaining what a 30-row table would. Use the right form.

Multiple sources of truth. Same info in three places, all slightly different. Pick canonical, redirect others.

Doc tools no one uses. Adopted because of a feature; team doesn't actually use it. Pick tools the team will use.

Doc style guide that's longer than the docs. Process beats product. Guide should be short.

No way to mark docs as deprecated. Old docs sit alongside current ones with no indication. Add a "deprecated" or "archived" status.

No analytics. No idea what's being used or what's missing. Even basic page views inform priorities.

Docs that read like specifications. Dense, formal, hard to scan. Write for the reader.


Output format

A documentation strategy document includes:

  • Audit: what exists, where, in what state
  • Tiering and categorization: the framework applied to existing docs
  • Gap list: what should exist but doesn't
  • Tool decisions: where each kind of doc lives
  • Ownership map: who owns what
  • Maintenance cadence: what's reviewed when
  • Style guide (brief): consistency standards
  • Roadmap: prioritized work to fill gaps and close out dead weight

Reference files

  • references/doc-types-guide.md: Detailed guide to the four doc types (reference, how-to, explanation, tutorial) with examples and templates for each.

© rampstackco, 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 (references) in skills/documentation-strategy of rampstackco/claude-skills.

  • SKILL.md
  • README.md
  • references/doc-types-guide.md

Open the folder on GitHubat commit 482c9bf

Compare with similar skills

Documentation Strategy 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.

Documentation Strategy compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Documentation Strategy this skillrampstackco/claude-skills940—~3.3kAutomated safety check: PassMIT
Technical Writing Clarityaiming-lab/MetaClaw3.5k—~244Automated safety check: PassMIT
Persuasive Technical Writingmtarcure/claude-vibe-squad163—~1.8kAutomated safety check: PassMIT
Technical Writercuriositech/some_claude_skills243—~1.4kAutomated safety check: PassMIT
Obsidian WriterAtmosphere/atmosphere3.8k—~2.6kAutomated safety check: PassApache-2.0
Technical Writingrsmdt/the-startup551—~1.3kAutomated safety check: PassMIT

Similar skills

  • Technical Writing Clarity

    aiming-lab/MetaClaw

    A skill your agent uses when writing documentation, READMEs, technical specs, runbooks, or any text that explains a system or process to other engineers.

    3.5k GitHub stars~244 tokensUpdated 4 mo ago
    Writing & ContentAuto-check passed
  • Persuasive Technical Writing

    mtarcure/claude-vibe-squad

    A skill your agent uses when drafting or revising long-form persuasive technical prose (an essay, post-mortem, launch narrative, or public technical release for X or the web) where the writing must…

    163 GitHub stars~1.8k tokensUpdated 17 days ago
    Writing & ContentAuto-check passed
  • Technical Writer

    curiositech/some_claude_skills

    Expert technical documentation specialist for developer docs, API references, and runbooks.

    243 GitHub stars~1.4k tokensUpdated 1 mo ago
    Writing & ContentAuto-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
  • Technical Writing

    rsmdt/the-startup

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

    551 GitHub stars~1.3k tokensUpdated 2 mo ago
    DevelopmentAuto-check passed
  • 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.

    28k GitHub stars~3.2k tokensUpdated today
    Writing & ContentAuto-check passed

More from rampstackco/claude-skills

All 103 skills in this repo
  • After Action Report

    rampstackco/claude-skills

    Run a structured after-action review (postmortem, retrospective) on a launch, incident, or completed project to capture timeline, root cause analysis, contributing factors, and actionable lessons.

    940 GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed
  • Analytics Strategy

    rampstackco/claude-skills

    Design measurement frameworks including event taxonomy, KPI hierarchy, dashboard architecture, attribution models, and analytics implementation strategy.

    940 GitHub starsUsed in 1 repo~2.4k tokens
    Auto-check passed
  • Brand Style Guide

    rampstackco/claude-skills

    Build or audit a comprehensive brand style guide that documents the full brand system including story, logo system, color, typography, imagery, voice, applications, and dos/don'ts.

    940 GitHub stars~2.1k tokensUpdated yesterday
    Auto-check passed
  • Brand Voice

    rampstackco/claude-skills

    Develop or document a complete brand voice and tone system covering voice attributes, tone shifts by context, vocabulary preferences, grammar rules, and copy examples.

    940 GitHub stars~2.2k tokensUpdated yesterday
    Auto-check passed
  • Content And Copy

    rampstackco/claude-skills

    Write or edit website copy, blog content, and editorial pieces with attention to voice, structure, and goal.

    940 GitHub stars~2.1k tokensUpdated yesterday
    Auto-check passed
  • Content Strategy

    rampstackco/claude-skills

    Develop a content strategy covering editorial positioning, content pillars, formats, calendar, governance, and topical authority planning.

    940 GitHub stars~2.6k tokensUpdated yesterday
    Auto-check passed

Questions about Documentation Strategy

What does Documentation Strategy do?

Design and run a documentation system for a team or product. Documentation Strategy is an agent skill from rampstackco/claude-skills. Design and run a documentation system for a team or product.

When should I use Documentation Strategy?

Documentation Strategy fits situations like: planning what to document; choosing a documentation tool; organizing existing docs; fixing stale documentation.

How do I install Documentation Strategy in Claude Code?

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

How do I install Documentation Strategy in Codex?

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

Can I use Documentation Strategy 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 rampstackco/claude-skills --skill documentation-strategy -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-strategy, .gemini/skills/documentation-strategy, .github/skills/documentation-strategy and .opencode/skills/documentation-strategy in your project.

What does Documentation Strategy need to run?

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

Does Documentation Strategy 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 Strategy 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 Strategy use?

Documentation Strategy 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 Strategy use?

About 3.3k tokens (SKILL.md is roughly 13k 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 2.6k tokens, read only when the agent opens those files.

What are the alternatives to Documentation Strategy?

Skills that share tags, products or a category with Documentation Strategy: Technical Writing Clarity (aiming-lab/MetaClaw, 3.5k stars), Persuasive Technical Writing (mtarcure/claude-vibe-squad, 163 stars), Technical Writer (curiositech/some_claude_skills, 243 stars) and Obsidian Writer (Atmosphere/atmosphere, 3.8k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Documentation Strategy?

rampstackco (a GitHub organization) maintains it in rampstackco/claude-skills, which has 940 GitHub stars. The repository holds 103 skills in this directory. The repository was last updated on October 7, 2026.

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