---
name: diataxis:reference
description: Use when the user asks for API docs, CLI command reference, configuration reference, parameter tables, schema documentation, error code lists, or version compatibility matrices. Creates neutral, structured, scannable technical reference — factual description of the machinery for lookup during active work. Do not use for onboarding, task guides, or conceptual justification.
---

# Reference writer

## Purpose

Write technical reference that describes the machinery accurately, neutrally, and in a predictable structure.

Reference is for truth, certainty, and lookup while working.

## When to use

Use this skill when the user asks for:

- API docs
- CLI command docs
- configuration reference
- parameter tables
- schema docs
- error code lists
- version compatibility matrices

Do not use this skill for onboarding, tasks, or conceptual justification.

## Core principles

- describe and only describe
- neutral, factual, and precise
- structured around the thing being documented
- complete enough for lookup
- consistent in format and terminology
- examples may illustrate, but must not turn into tutorials

## Reader need

The reader asks:
- What is this?
- What are the valid inputs?
- What does it return or affect?
- What constraints, defaults, or limits apply?
- What errors or warnings exist?

## Structure patterns

Choose one consistent pattern per item type.

### API endpoint

- Name
- Purpose
- Method / path
- Authentication
- Parameters
- Request body
- Response body
- Errors
- Examples
- Notes / limits

### CLI command

- Name
- Synopsis
- Arguments
- Options
- Defaults
- Exit codes
- Examples
- Related commands

### Config key

- Name
- Type
- Default
- Required or optional
- Allowed values
- Effect
- Constraints
- Example

## Writing rules

- avoid persuasion and opinion
- avoid "best practice" unless clearly marked and linked elsewhere
- avoid long narrative prose
- use standard headings and repeated patterns
- mirror the structure of the product where possible
- make scanning easy

## Examples policy

Examples are allowed when they clarify usage, but they must stay illustrative.

Good:
- one short request example
- one short response example
- one command example showing syntax

Bad:
- long walkthroughs
- conceptual essays attached to every field
- advice-heavy examples disguised as reference

## Inputs to gather

- product surface being documented
- canonical names and terminology
- exact signatures, defaults, constraints, limits
- warnings and error cases
- version and compatibility notes
- examples that reflect reality

## Output contract

Produce reference that:

- is structured consistently
- is easy to scan
- states facts cleanly
- separates facts from advice
- can be trusted during active work

## Anti-patterns to remove

- recommendation language without a clear basis
- tutorial prose
- hidden defaults
- vague types like "object" without schema details
- missing constraints and edge cases
- inconsistent naming across entries

## Final self-check

Before returning, verify:

- the document is neutral
- the structure mirrors the product surface
- repeated items use a repeated template
- warnings and limits are explicit
- examples illustrate rather than teach