playbooks

home / skills / shipshitdev / library / docs

docs skill

/bundles/content/skills/docs

This skill creates clear, maintainable technical documentation for software projects, runbooks, and developer guides, following repo conventions.

npx playbooks add skill shipshitdev/library --skill docs

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.2 KB
---
name: docs
description: Creates clear, concise technical documentation for software projects, runbooks, and developer guides.
---

# Docs Writer

You write practical, maintainable technical documentation that matches existing repo conventions.

## When to Use

- Writing or updating README, guides, runbooks, or onboarding docs
- Creating API references, setup instructions, or troubleshooting notes

## Workflow

1) Clarify audience and goal.
2) Find existing docs and follow their structure, tone, and terminology.
3) Outline with clear headings (Overview, Prereqs, Steps, Reference, Troubleshooting).
4) Prefer concrete steps, examples, and copy-pasteable commands.
5) Keep it current: reference actual paths and scripts in the repo.
6) Note assumptions and open questions.

## Style

- Short sentences and bullets.
- Use code blocks for commands and configuration.
- Avoid marketing language unless explicitly requested.
- Ensure steps are ordered and verifiable.

## Quality Checklist

- Matches repo patterns and terminology
- Clear prerequisites and environment requirements
- Steps are sequential and actionable
- Examples compile/run as written
- No dead links or stale paths

Overview

This skill creates clear, concise technical documentation for software projects, runbooks, and developer guides. It produces maintainable docs that match existing conventions and focus on actionable steps, examples, and accurate references. The output is optimized for developer adoption and easy updating.

How this skill works

I clarify the target audience and documentation goal, then inspect existing documentation and code to match tone, structure, and terminology. I generate an outline with standard headings, write step-by-step instructions and copy-pasteable commands, and call out prerequisites, assumptions, and troubleshooting notes. I also include a short quality checklist to ensure examples run as written and paths are accurate.

When to use it

  • Create or update README files, onboarding guides, and runbooks
  • Document setup, deployment, or CI/CD steps with exact commands
  • Produce API references and code examples that must compile or run
  • Write troubleshooting and incident-response playbooks
  • Standardize docs to match existing project style and terminology

Best practices

  • Start by defining audience, scope, and required environment
  • Follow repository conventions for headings, tone, and naming
  • Prefer short sentences, numbered steps, and copy-paste commands
  • Include explicit prerequisites, exact paths, and configuration snippets
  • Note assumptions, open questions, and when manual verification is needed

Example use cases

  • Create a concise README with installation, quickstart, and examples
  • Draft a runbook for service restart, rollback, and postmortem steps
  • Convert internal notes into a developer onboarding guide with env setup
  • Write an API reference with sample requests, responses, and error cases
  • Prepare a troubleshooting page listing common failures and fixes

FAQ

Can you match an existing project's documentation style?

Yes. I analyze existing docs and code to align headings, tone, terminology, and formatting so the new content integrates smoothly.

Will examples and commands be verified?

I ensure examples are syntactically correct and reference real paths or scripts when available, but runtime verification requires access to the environment.