Technical writing

Use for repository documentation, including READMEs, guides, references, flow docs, specifications, and technical PR descriptions. Read the applicable AGENTS.md first; it owns documentation destinations, length limits, and repository terminology. This skill needs no global tools or skill installation.

Establish the reader and evidence

1. Identify the reader, intended action or decision, page scope, and source of truth. Read current code, schemas, tests, command output, and the relevant diff.
2. Choose the requested mode: create from evidence, edit while preserving useful facts and the author's intent, or review with findings before proposed fixes.
3. Lead with what the reader can accomplish and one recommended path. Mention implementation first when explaining architecture or internals is the task.
4. Verify claims, examples, defaults, paths, and failure behavior. Label material uncertainty and name the missing evidence; polished prose is not verification.
5. Before handing off any writing, complete the required plain-language pass.

Write precise prose

Apply ASD-STE100 (Simplified Technical English). Before and after a documentation update, complete the terminology and limits pass. Keep official resource names and public identifiers. Check each replacement against its meaning and current source.

• Use present tense, active voice, concrete nouns, and one term per concept. Expand unfamiliar abbreviations at first use; use established product names.
• Define unfamiliar concepts through their owner, action, and observable role. Replace “the controller handles deployment” with what it reads, decides, and starts, when those details matter to the reader.
• Make every sentence help the reader decide, act, or understand a boundary. Delete repeated background, meta-commentary, and generic benefits.
• Treat all, only, and never as literal claims. Name the surface they cover. Use must for requirements and can for options; preserve consequential limits.
• Use sentence-case, action-specific article headings and descriptive links. Explain why when it changes a decision or prevents a failure.
• Give each contract, default, and behavior one owning page. Link its definition from other pages rather than copying it into competing references.
• Make diagrams agree with prose: actors and resources are nodes, containment uses regions, and arrows describe interactions. Do not imply deployment proof from source alone or rely on color alone to convey meaning.

Always deslop the writing

Run this pass whenever you write, edit, or review prose, including small changes, PR descriptions, and review findings. The user does not need to request it. For edits, clean up the prose in scope and read the surrounding text for flow. For a review-only task, clean up your feedback and flag wording in the document when it obscures meaning; do not silently rewrite the source.

• Name who does what and under which conditions. Replace vague verbs and noun piles such as “performs readiness observation” with “checks whether the workload is ready.” Prefer familiar words; define necessary technical terms.
• Delete filler, canned transitions, empty claims, and repeated explanations. Remove contrasts or caveats the reader does not need. Avoid invented labels.
• Put the main point first. Split a sentence when the reader has to untangle several actions, actors, or conditions; give each paragraph one main point.
• Check the edit against the original and the evidence. Preserve scope, required actions, permissions, warnings, failure behavior, and uncertainty. Do not make an unsupported claim sound certain or cut a useful detail merely to shorten it.

Organize and name development docs

When adding, grouping, moving, or renaming documentation, read Organization and naming. Choose one home based on the reader's task. Use short sidebar labels and give the article enough context to make sense when opened directly. Check repository guidance and the current navigation before treating a proposed layout as implemented.

Choose the smallest useful page

Keep quickstarts and main guides focused on the normal supported workflow. Put platform-specific failures, uncommon environment workarounds, and extended diagnostic steps in the owning troubleshooting page or section. Link to that guidance with a short, symptom-based pointer beside the affected step; do not front-load the main guide with edge cases. Keep required prerequisites, security boundaries, destructive effects, and recovery needed for the normal workflow beside the action they affect.

Omit empty or irrelevant sections. Split independently useful topics when a page mixes too many reader tasks. Keep the root documentation map and affected links current, following repository page ownership and length limits.

Frontmatter and tags

Use YAML frontmatter for page metadata. Read Frontmatter and tags for supported fields, values, and their owners before adding or changing metadata. Write tags as a list of strings. The nolimit tag exempts its page from both word-count thresholds while retaining count reporting; apply it only with the human approval required by AGENTS.md. Add human_verified to the tags only when a human has verified the document, for example tags: [human_verified]. Keep verification status in the tag and record the human review date in last_verified (YYYY-MM-DD). Update that date only after another human review. Preserve existing tags and metadata. Change generated frontmatter through its generator. Snippet tags do not exempt pages that include the snippet.

Templates for specific document types

Use the Markdown frontmatter field kind to select a template from the documentation taxonomy. Copy the template for a new page. When updating an existing page, preserve its links and heading anchors.

For a test workflow detail page, use kind: reference/ci and keep the template's six sections in order: Overview, Trigger, Scenarios, Execution, Results and limits, and Files. Follow the CI authoring guidance for scenario descriptions, descriptive names, and exact GitHub job mappings. Keep shared setup in its owning guide and preserve existing heading anchors. Publication-only workflows, preview builds, cache maintenance, and security scanning belong in their owning contributor or release guides, not this template.

For a Driver contract, keep the template's sections in order and use the Driver authoring guidance to check coverage. Keep the template's contents list below the title and update its links with the page. Put implementation-specific setup and settings in the linked implementation page. When adding a template, add its kind, selection criteria, and asset link to this table and the documentation taxonomy in the same change.

Make examples usable

Show realistic, safe inputs and exact identifier types. Mark placeholders clearly, quote YAML values when needed, and specify each code block's language. Include the working directory, prerequisites, invocation, and expected success output when they are necessary to run a command. Verify examples when feasible; report when they have not been executed.

Put permissions, secret handling, destructive effects, concurrency limits, timeouts, ordering, retries, and recovery beside the affected step when mistakes have consequences. Separate development, test, and production behavior. Never include real credentials. Remove explanation before removing information needed for a command to succeed safely. Keep internal orchestration in its owning flow or reference unless the operator needs it to make a decision.

Edit and verify

Correct inaccurate or unsafe claims first, add missing requirements or failure handling, then remove repetition and tighten prose. Update current docs with the behavior they describe; mark a page stale with a source-of-truth link if a full update cannot be completed. Preserve historical specs and user-owned Manual Notes in source. The site omits document Changelogs and empty Manual Notes. Do not rewrite history to match later implementation.

Check commands, examples, terminology, local links, and navigation. For documentation-only changes, use formatting, builds, link checks, and visual inspection; do not add or run tests. Report checks run and gaps.

For a review, cite the conflicting text, explain its consequence, and suggest the smallest correction. Order findings by reader impact, distinguish correctness from optional polish, and state what evidence was checked. Say when no actionable findings remain.

Provenance

Adapted from Docy's core technical-writing and document-lifecycle guidance, developer documentation, concise instructions, and specification references. The repository maintains this self-contained selection; see the developer-skills catalog for source details. Docy's CLI and personal installation are not required.