write-tech-how-to
Writes or revises a goal-oriented how-to guide for a reader who needs to complete one specific technical task.
Synopsis
User-invoked. Name this skill when you want the agent to apply it. disable-model-invocation is true.
Source file: skills/write-tech-how-to/SKILL.md.
Front matter
- name
write-tech-how-to- description
- Writes or revises a goal-oriented how-to guide for a reader who needs to complete one specific technical task.
- disable-model-invocation
true
Full contents
---
name: write-tech-how-to
description: Writes or revises a goal-oriented how-to guide for a reader who needs to complete one specific technical task.
disable-model-invocation: true
---
# Write a how-to guide
Read [write-tech-core](../write-tech-core/SKILL.md) first.
A how-to guide helps a capable reader complete one task. It is not a lesson,
conceptual explanation, or complete reference.
## Define the task
Record privately:
- the reader's goal;
- the required starting state;
- the observable successful end state;
- one verified path between them;
- the environment and versions where that path applies.
If the starting state is missing, ask for it when interaction is allowed.
Otherwise state the narrow prerequisite without inventing setup steps.
## Output contract
Use a verb-led title that names the goal. Then write:
1. A short outcome statement.
2. Prerequisites that the procedure actually uses.
3. Steps in dependency order. Each step gives one action, exact input, and the
result needed to continue.
4. A check that proves the task succeeded.
5. An undo or recovery procedure when the supplied change has consequences.
Keep commands, file paths, names, and working directories consistent. Put
warnings immediately before the risky action. Explain the effect of
destructive commands and provide a verified safer path when one exists. Use
placeholders for secrets.
This contract overrides requests for broad coverage. Before returning the
draft, delete conceptual background, unverified alternatives, generic security
advice, deployment notes, and unrelated troubleshooting. Do not preserve
missing topics as disclaimers or "not verified" sections. Missing evidence is
not content.
## Branches and failures
Choose one supported default. Include an alternative only when it is verified
and helps the same goal under a stated condition.
Include troubleshooting only for a supplied or observed failure on this exact
path. Give the recognizable symptom, verified cause, and tested recovery
together. Never infer a cause from a plausible symptom.
## Verification gate
Run the procedure from the stated starting state when safe. Test the steps in
order and test the undo path when present. Distinguish observed output from
illustrative output. If the procedure was not run, say so outside the guide
when commentary is allowed.
## Example
```markdown
# Add a health endpoint
In `demo/flint.toml`, add:
`[health]`
`path = "/health"`
From `demo`, run `flint run`.
Check the result:
`curl http://localhost:4040/health`
Expected output: `ok`.
To undo the change, remove the added `[health]` block.
```
Return the guide only.