write-tech-getting-started
Writes or revises a getting-started tutorial that takes a new user through one verified path to an early, visible success.
Synopsis
User-invoked. Name this skill when you want the agent to apply it. disable-model-invocation is true.
Source file: skills/write-tech-getting-started/SKILL.md.
Front matter
- name
write-tech-getting-started- description
- Writes or revises a getting-started tutorial that takes a new user through one verified path to an early, visible success.
- disable-model-invocation
true
Full contents
---
name: write-tech-getting-started
description: Writes or revises a getting-started tutorial that takes a new user through one verified path to an early, visible success.
disable-model-invocation: true
---
# Write a getting-started guide
Read [write-tech-core](../write-tech-core/SKILL.md) first. Keep that ledger
private.
A getting-started guide is a lesson. Its product is the learner's first
successful experience, not complete product coverage.
## Define success
Record privately:
- the learner and the knowledge they bring;
- the exact starting state;
- one observable end state;
- the shortest verified path between them;
- the environment where the path was tested.
If several platforms or methods exist, choose one supported default. Put
alternatives in another page or after the first success.
When several products read the same artifact, the default path is the
command that writes that artifact. Confirm that artifact. Do not name a
product from the test machine as a prerequisite.
## Output contract
These are author slots, not headings. Headings name the learner's action.
1. **Outcome.** One or two sentences that say what the learner will be able
to do after this path, such as install the skills so any agent can use
them. Confirm holds the path.
2. **Prerequisites.** Only what the command needs to run. Include a working
directory only if that command requires that directory. A git URL is not a
working-directory requirement.
3. **Install.** The default command, then a code-block sample of its result.
4. **First use.** Numbered steps for the first success after install, each with a
code-block sample. Skip this slot when install is the first success. If first
use is in scope and unverified, ask one question instead of inventing steps.
5. **Confirm.** One code-block sample of the files on disk.
6. **Next steps.** One sentence that says the reader can open the linked page
for skill descriptions and the full skill text. Link only when that page
exists.
The sample is the lines the learner must match.
| Excuse | Reality |
|--------|---------|
| A second verified command shows a product picked it up | Confirm is a sample of the files on disk. |
| A product on the test machine is a prerequisite | Prerequisites are what the writer command needs. |
| Outcome is the path written | Outcome says what they will be able to do. |
| Put the slot name in the heading | Headings name the learner's action. |
| Install cloned a git URL, so start in a project | A remote source is not a working-directory requirement. |
| Next steps: the contracts live on that page | The reader can open that page for descriptions and the full skill text. |
Stop if a heading is `Do`, if a section only repeats Install, if
Prerequisites invent a project directory, or if Next steps calls the linked
pages contracts.
Give the learner a meaningful result early. Explain only enough to make the
next action intelligible. Point out what changed after each important step.
This contract overrides a request for comprehensive product coverage. Before
returning the draft, delete `Architecture`, `Configuration`, and `Deployment`
headings and their contents. Delete `Troubleshooting` unless every entry has a
supplied or observed symptom, verified cause, and tested recovery. Do not turn
missing evidence into content.
## Scope gate
Architecture, full configuration, deployment, alternatives, and exhaustive
troubleshooting are separate reader needs. Omit them from the first-success
path. If the prompt asks for one of these without supplying verified material,
do not create its heading. At most, use one final sentence naming the deeper
docs the reader needs. A caveat-filled section is still out of scope.
Add troubleshooting only for a verified failure the learner may encounter on
this exact path. Include the observed symptom, cause, and tested recovery.
## Verification gate
Run the sequence from the stated starting state when safe. Test commands in
order, not separately. Match expected output exactly enough for recognition.
Check that names, paths, versions, and working directories remain consistent.
If the sequence was not run, state that outside the guide when commentary is
allowed. Never make an untested guide sound tested.
## Example
```markdown
# Get started with Flint
This guide installs Flint and starts a project you can run.
## Install
Run:
`curl -fsSL https://flint.example/install.sh | sh`
Check the install:
`flint --version`
flint 1.2.0
## Create and run a project
1. Run `flint init demo`.
demo/flint.toml
2. Run `cd demo`.
3. Run `flint run`.
Listening on http://localhost:4040
```
This is complete at the first verified result. It does not infer what listens
at the URL, how to stop it, what `flint.toml` means, or how to deploy it.
If first use is in scope and unverified, ask one question. Otherwise return
the guide only.