write-tech-core
Applies shared evidence, audience, structure, style, and verification rules when drafting or revising technical writing with the write-tech skill family.
Synopsis
Shared rules for the write-tech family. Focused write-tech skills read this file first. disable-model-invocation is true.
Source file: skills/write-tech-core/SKILL.md.
Front matter
- name
write-tech-core- description
- Applies shared evidence, audience, structure, style, and verification rules when drafting or revising technical writing with the write-tech skill family.
- disable-model-invocation
true
Full contents
---
name: write-tech-core
description: Applies shared evidence, audience, structure, style, and verification rules when drafting or revising technical writing with the write-tech skill family.
disable-model-invocation: true
---
# Write technical content
Technical writing transfers a verified result to a specific reader. Accuracy
comes before fluency.
## Establish the brief
Before drafting, identify:
- the reader and what they already know;
- the result they need;
- the product version and environment;
- what is in scope;
- the evidence available for commands, behavior, and claims.
Use sources in this order: user instructions, project rules and templates,
current code and tests, current first-party documentation, then cited external
sources. Resolve conflicts in favor of the more specific and current source.
Build a private evidence ledger before drafting. Map every product claim to a
source. Keep only claims with a source. A plausible interpretation of a command
name is not evidence: `sync` does not prove upload direction, incremental
behavior, authentication, or remote storage. Preserve the source's nouns:
`PATH` is a path until a source says it must be a file or directory.
If a required fact is missing, ask one focused question. If the user requests
an immediate draft, omit the unsupported detail or mark the gap plainly. Never
invent commands, URLs, flags, output, test results, issue IDs, compatibility,
or product behavior.
## Keep the document type honest
- A blog post or article argues, explains, or shares a useful discovery.
- A getting-started guide teaches through one successful first experience.
- A how-to guide helps a competent reader complete a real task.
- Reference describes an interface accurately and consistently.
- A README orients a repository visitor and routes them to deeper material.
- Pull request and commit text records change context for collaborators.
Link to another document type when the reader's need changes. Do not turn one
page into a manual.
## Write
- Lead with the result, decision, or reader goal.
- Use concrete nouns, direct verbs, active voice, and stable terminology.
- Use sentence-case headings and descriptive links.
- Put conditions before the actions they control.
- Use numbered lists for sequences and bullets for parallel facts.
- Define necessary acronyms and remove avoidable jargon.
- Avoid idioms, memes, filler, marketing claims, and judgments such as "easy"
or "simple."
- Use realistic names and examples drawn from verified behavior.
- Keep the author's voice in articles. Keep procedural and reference prose
quiet and direct.
Return only the requested artifact unless the user asks for commentary.
## Verify
Run commands and examples when safe. Compare reference facts with code,
schemas, help output, or tests. Check links and expected output. Follow a
procedure from a clean starting state when practical.
Report checks exactly. Separate `passed`, `failed`, and `not run`. Give a
reason for each check not run. Do not convert an inference into a fact.
Finish by applying the installed `unslop` guidance. Preserve technical terms
and intentional voice while removing generic AI phrasing.
## Example
Given only:
```text
Acorn 2.4+ supports `acorn sync PATH`.
Success prints `Synced N files`.
```
Write:
```markdown
## Run your first sync
Install Acorn 2.4 or newer using your project's verified installation
instructions.
Run:
`acorn sync ./site`
A successful sync prints `Synced N files`, where `N` is the reported file
count.
```
Do not add a package name, installer URL, login step, flags, or error messages
without a source.
For the research behind these rules, read [SOURCES.md](SOURCES.md).