`write-tech-reference`

Writes or revises a precise, scannable reference page for a command, API, configuration surface, schema, or other technical interface.

Synopsis

User-invoked. Name this skill when you want the agent to apply it. disable-model-invocation is true.

Source file: skills/write-tech-reference/SKILL.md.

Front matter

name: write-tech-reference
description: Writes or revises a precise, scannable reference page for a command, API, configuration surface, schema, or other technical interface.
disable-model-invocation: true

Full contents

---
name: write-tech-reference
description: Writes or revises a precise, scannable reference page for a command, API, configuration surface, schema, or other technical interface.
disable-model-invocation: true
---

# Write a reference page

Read [write-tech-core](../write-tech-core/SKILL.md) first.

Reference describes technical machinery so readers can look up exact behavior.
It does not teach a first experience or lead readers through a task.

## Establish the contract

Record privately:

- the exact interface and version or source revision;
- its canonical name and signature;
- every supplied argument, field, option, type, unit, default, constraint,
  return value, output, error, and side effect;
- which examples were verified.

Treat source code, generated schemas, tests, and observed output as stronger
evidence than nearby prose. Resolve conflicts or state a narrow version
boundary. Never merge behavior from different versions.

## Output contract

Use this order when the evidence supports each part:

1. Exact interface name and a one-sentence factual summary.
2. Canonical synopsis, signature, or schema.
3. Arguments, fields, and options in the interface's natural order.
4. Output, return values, exit status, errors, and side effects.
5. Minimal verified examples.
6. Related reference entries that actually exist.

For each entry, preserve the difference between required and optional, unset
and false, default and example, bytes and characters, and input and output.
State types, units, defaults, ranges, and constraints only when sourced. Use
the same terms and notation throughout.

This contract overrides a request to fill a standard template. Before
returning the page, delete headings with no verified content. Do not inventory
unknown aliases, environment variables, precedence rules, errors, internals,
edge cases, or related commands. Do not replace missing facts with "not
verified" sections. Absence of evidence is not an interface guarantee.

## Examples and prose

Examples are executable claims. Include only inputs and outputs established by
tests, observation, or supplied substitution rules. Keep placeholders visibly
distinct from literal values.

Write for lookup: short paragraphs, parallel entry descriptions, and stable
heading names. Put shared semantics once before the entries they govern. Link
to a tutorial, how-to, or explanation instead of embedding it.

## Verification gate

Compare every identifier and literal with the source. Check copied signatures,
defaults, types, units, output streams, exit codes, and example results. Run
examples when safe. Mark version-specific behavior at the smallest useful
scope.

## Example

```markdown
# `flint cache`

## Synopsis

`flint cache [--ttl SECONDS] PATH`

## Arguments

`PATH`
: Required project directory.

## Options

`--ttl SECONDS`
: Optional integer number of seconds. Default: `60`.

## Exit status

`0` on success. `2` when `--ttl` is invalid.
```

Return the reference page only.