Skip to content
cccskills
FreePublished on GitHub

technical-writing

Use when the work produces a document that must be understood by someone who was not there when the system, procedure or decision was made, and that stays in the repository after the work merges: a README, an architecture or system document, an ADR, a runbook, an onboarding guide, an API guide, a migration note. Not for the working documents of a piece of work (boards, specs, plans and reports belong to the skills that produce them) and not for persuasive prose.

The English summary is being prepared. Showing the original description.

Ovich/swarmstorm13 stars(GitHub 13 + cccskills 0)

Run score Not tested

See how to install

Files included (1)

  • SKILL.md4.8 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Technical writing

The reader arrives with a question; the document reduces the uncertainty around it until the reader can understand the system, make the decision, or perform the action. The structure, the constraints, the decisions, the evidence and the consequences are made visible, without making the engineering look simpler than it is.

Mindset

  • One reader, one question. "How do I run this?", "why does this service depend on this database?" and "what do I do when the deployment fails?" are three documents. Name the reader and the question first, answer first, let background follow.
  • Draw the structure before writing, through the write-diagrams skill, picking from its catalog by the reader's question. A concept with components, ordering, states, ownership or dependencies is drawn, never narrated.
  • State where a responsibility ends. For each significant component: what it owns, consumes, produces, depends on, deliberately does not do, and what can change without affecting it. Never "handles" or "manages".
  • Start decisions from constraints. Problem, constraints, alternatives, decision, consequences. "Data cannot leave the organisation, therefore inference runs inside its infrastructure" is a design; "the system uses Kubernetes and llama.cpp" is inventory.
  • Preserve the reasoning a future engineer would otherwise rediscover, for the decisions whose reversal would need it and only those: the problem, the plausible options, the constraint that mattered, what was chosen and rejected, what it costs, what it makes possible, what remains unresolved.
  • Keep fact, constraint, decision and consequence apart, each stated as what it is.
  • Say what is hard and why, and no more. A named risk gets discussed; an adjective gets nodded past.

Flow

  1. Name the reader and the question, and choose the document type below.
  2. Write it in the repository, never in aiview's data home, and read it rendered. Durable documents live next to what they describe, under stable names (README.md, docs/architecture.md, docs/runbook.md); point-in-time material under dated names.
  3. Verify every actionable claim at writing time: commands, paths, ports, configuration, API behaviour, procedures, versions. What cannot be verified is qualified or removed.
  4. Cut what does not change the reader's understanding, decision or action: repetition, history, technology inventory, unsupported adjectives, prose that duplicates a diagram.

When the system changes in a way that invalidates the document, the document changes in the same commit.

Document types

TypeReader's questionShapeDiagram, from the write-diagrams catalog
README"What is this and how do I run it?"What it is, requirements, run, repository mapUsually none. A README that needs one is an architecture doc wearing a README's name.
Architecture / system doc"How does this work?"Constraints, structural diagram, components, flows, decisions, consequencesContainer or component; sequence for the flows that matter; dependency graph where import direction is a rule.
ADR"Why is it like this?"Context, constraints, alternatives, decision, consequencesOption comparison: the alternatives side by side, the deciding trade-off under them.
Runbook"It's broken. What do I do?"Preconditions, procedure, expected result, failure branches, rollbackUser flow for the operator's path, state machine when the system has modes.
Onboarding"Where do I start?"System map, reading path, first task, deeper referencesSystem context or container as the map; user flow for the first task.
API guide"How do I call this?"Working example, interaction flow, authentication, errors, referenceSequence, for any handshake or multi-step call.
Migration note"What changed and what must I do?"What changes, before and after, migration order, failure and rollbackPhasing: what moves first; before and after as two small diagrams when the contrast is the point.

Core test

Before publishing: can a competent engineer who did not build this system understand its structure, boundaries, constraints, important decisions, consequences and next action without asking anyone? If not, the document is not finished.

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

aiview

Free

Use whenever a document is produced for the user to read and react to while it evolves: a brainstorm board, a plan, a design language, a prototype, a PR analysis, a review report, a live PDF. Also when a document must be registered, opened, listed, moved or retired, or a prototype's bindings checked. Not for code, tests or configuration, or any file nobody opens in a browser.

The English summary is being prepared. Showing the original description.

Ovich/swarmstorm13Updated Oct 29, 2026

Use when a person wants to think an idea through and keep the discussion: a feature, a tool choice, an architecture question, before a plan or without one, with the agent through an interview. Produces a board in aiview holding the decisions, the diagrams and what was investigated. Not for a swarm of seats working it (brainswarm), not for an implementation plan and not for bug fixes.

The English summary is being prepared. Showing the original description.

Ovich/swarmstorm13Updated Oct 29, 2026

Use when a person wants a swarm of role seats to work a topic on the swarm board under a chosen protocol: a brainstorm (ideas before any judgment), a debate (questions argued to decisions, a skeptic endorsing) or an editorial (one text drafted, read by seats standing for its readers, revised), a protocol or template the project keeps as a `protocol-<name>` skill (or an older `brainswarm-<name>` one), or a custom protocol recommended for the person's intent, or a seat's brief names a brainswarm protocol. Produces the run's record in aiview, written by the orchestrator alone. Not for one person thinking aloud with the agent (brainstorm, interview) and not for a plan's slices (execute-plan).

The English summary is being prepared. Showing the original description.

Ovich/swarmstorm13Updated Oct 29, 2026

Use when dispatched to cold-read a plan, as an agent that was not in the conversation that wrote it, to say whether it can be carried out from the document alone. Produces what the reader would build, its questions, and a verdict, ready or not ready, repeated as the writer fixes the plan. Not for judging the design (interview, pr-review), not for the mechanical checks (aiview plan check, tracker check), and not for writing the plan (write-plan).

The English summary is being prepared. Showing the original description.

Ovich/swarmstorm13Updated Oct 29, 2026

Use when code is hard to follow and is to be audited or reworked: long if/else or switch chains, cascades of type checks or parse attempts, kind fields compared to strings, flag parameters, deep nesting, a function hard to read. Also for complexity guardrails, or one long conditional function pasted. Produces a ranked audit of families, one family reworked behind characterization tests, or the guardrails.

The English summary is being prepared. Showing the original description.

Ovich/swarmstorm13Updated Oct 29, 2026

Use when a page is wanted to work on something with the person during development, fed the project's real data (comparing model answers, walking an agent call by call, measuring an output against its template), when such a workbench has to change, be reworked or its feed broke, or mid-session when turns went into aligning with the person on how to do a kind of work that recurs and real project data could show it. Produces the page in aiview, kind `workbench`, and the project's `workbench-<bench>` skill with its feed and operating steps. Not for designing a product screen (design-prototype) or verifying user stories (verification-skill-create).

The English summary is being prepared. Showing the original description.

Ovich/swarmstorm13Updated Oct 29, 2026

See all skills by Ovich

Report a problem with this skill