Docs writer

Skill pbans-agent/skillpack/skills/docs-writer

Git-backed source of truth for reusable AI Agent Skills

Install

npx -y skills add pbans-agent/skillpack --skill docs-writer

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Writes clear, structured technical documentation including READMEs, API docs, architecture guides, inline code comments, and user guides. Use when the user asks to write documentation, create a README, document an API, explain code, write a tutorial, or improve existing docs.

SKILL.md

3.9 KB, as published. Nobody here has run it

Docs Writer

Purpose

Create high-quality technical documentation that is clear, accurate, well-structured, and genuinely useful to its audience.

When to Use

Writing or updating a README
Documenting APIs and endpoints
Creating architecture or design docs
Writing user guides and tutorials
Improving inline code comments
Creating changelog entries
Writing onboarding documentation

Documentation Types

README

Every project needs one. Structure:

What it is — one-sentence description
Why use it — key benefits
Quick Start — get running in < 5 minutes
Installation — all methods
Usage — common scenarios with examples
Configuration — all options
Contributing — how to help
License — what others can do

API Documentation

For each endpoint/function:

What it does — one sentence
Parameters — name, type, required/default, description
Returns — type and structure
Throws — error types and when
Example — realistic usage
Notes — edge cases, gotchas

Architecture Documentation

Overview — system diagram and data flow
Components — what each part does
Decisions — why, not what (what is in code)
Trade-offs — what was considered and rejected
Growth areas — where the architecture may need to change

Tutorial / Guide

Goal — what the reader will achieve
Prerequisites — what they need first
Steps — numbered, testable, one action each
Verification — how to confirm each step worked
Next steps — where to go from here

Writing Principles

Clarity

Short sentences. One idea per sentence.
Active voice: "The function returns..." not "It is returned by..."
Concrete examples over abstract descriptions
Define jargon on first use

Structure

Lead with the answer, then explain
Use headers liberally — scannable is readable
Tables for parameters and options
Code blocks for examples — always runnable
Numbered lists for sequences, bullets for options

Audience Awareness

Know who is reading and what they already know
Beginner docs: explain WHY, not just HOW
Expert docs: be precise and complete
Internal docs: can assume context
External docs: must be self-contained

Code Examples

# BAD: incomplete, won't run
# Just call the function with some data
result = process(data)

# GOOD: complete, runnable, shows real usage
from mylib import process

data = {"users": [{"name": "Alice", "age": 30}]}
result = process(data, format="json", validate=True)
print(result)
# Output: {"processed": 1, "errors": []}

Rules for code examples:

Always runnable (include imports)
Use realistic data (not "foo", "bar")
Show expected output
Keep minimal — one concept per example
Test your examples actually work

Anti-Patterns

Dead documentation — docs that describe code that no longer exists
Vague documentation — "configures the system" (what system? how?)
Duplicate documentation — same info in 3 places, all different
Over-documentation — restating what the code clearly shows
Documentation debt — docs that were never updated after a change

Maintenance

Documentation is code. It should be:

Version-controlled alongside the code it describes
Updated in the same commit as code changes
Reviewed like code
Tested (do the examples still work?)