Skip to main content
skill CX Codex

technical-writing · blockmatic-icebox — Claude Code skill: docs and installation

technical-writing — a skill for Claude Code that edits and checks technical docs in Basilic-based repositories. It applies to Docu MDX, READMEs, and product Markdown files at the repository root.

MIT 108 installs ★ 1 updated 2026-10-02

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add blockmatic-icebox/basilic-skills --skill technical-writing -a claude-code
Open on GitHub

What technical-writing does

The skill drafts and edits documentation, checking claims against repository code, public types, and tests. It covers Docu MDX, READMEs, and root files such as PRODUCT.md, ARCHITECTURE.md, or DESIGN.md when AGENTS.md assigns them to the docs workflow.

Read AGENTS.md before making changes; rules in .cursor/rules/ take precedence. The skill sends layer-selection questions to /w-docs and runs pnpm --filter @repo/docu checktypes when preparing Docu changes to ship. It excludes claims that cannot be verified and does not invent flags, endpoints, or defaults.

What it helps with

  • verify documentation claims against code and tests
  • revise a README to match repository rules
  • edit Docu MDX without duplicating an existing topic
  • align root product Markdown with the repository's architecture sources

Example prompts for the agent

  • Revise the README to follow the repository rules and check its claims against the source.
  • Edit the Docu MDX page and validate it with pnpm --filter @repo/docu checktypes.
  • Check ARCHITECTURE.md against AGENTS.md and the architecture sources.

How to install technical-writing

1Skills CLI (Vercel)

npx skills add blockmatic-icebox/basilic-skills --skill technical-writing -a claude-code

2Manually: put the files in place

~/.claude/skills/technical-writing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/technical-writing/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about technical-writing

How do I install technical-writing in Claude Code?

Run npx skills add blockmatic-icebox/basilic-skills --skill technical-writing -a claude-code. The skill file is at ~/.claude/skills/technical-writing/SKILL.md.

What does technical-writing do?

It helps create, revise, and review technical docs in Basilic-based repositories. Claims are checked against source code, public types, and tests.

What does technical-writing need to work?

It needs a Basilic-based repository and its AGENTS.md documentation rules. Docu MDX changes can be checked with pnpm --filter @repo/docu checktypes.

Source text

SKILL.md · MIT
---
name: technical-writing
description: Write, edit, and review technical docs in Basilic-based repos—Docu MDX, READMEs, and root product markdown—verifying every claim against source and keeping prose direct, accurate, and free of AI patterns.
---

# Technical writing

Write accurate, task-focused documentation for developers and coding agents. Each section should be easy to scan, retrieve, and act on without unstated context.

## Consuming repo

Read the repo's `AGENTS.md` before you write: doc layers, public one-liner, capability names, banned copy, and where `DESIGN.md` lives. Glob rules in `.cursor/rules/` override this skill. For which layer to update (MDX vs README vs rules), use `/w-docs`—do not duplicate its routing table here.

## Voice

- Address the reader as `you`; use imperative verbs for steps. Active voice, present tense, concrete nouns.
- American English, Oxford comma. Write `eve` lowercase when naming the runtime.
- Lead each page and section with the answer or outcome. One primary job per page.
- Preserve the author's supported meaning, nuance, and uncertainty. Make the minimum effective edit; leave strong prose alone.
- Use `we` only when describing a deliberate team action documented in the repo.

Ban filler and hype: `easy`, `simple`, `quick`, `just`, `obviously`, `utilize`, `facilitate`, `leverage`, `robust`, `seamless`, promotional adjectives, rhetorical questions, engagement bait.

Ban AI tells: summary transitions (`With this setup complete…`), stop-start fragments, datasheet verbs (`provides`, `is configurable`), cold opens with no antecedent, template closers and closing proverbs, manufactured specificity to sound human.

Cadence. Bad: "The API is flexible. It supports many use cases. That is the value. You will like it." Good: "Register the route in `apps/api`, expose it in OpenAPI, then run the client generator so the web app picks up typed calls."

## Sources of truth

Do not rely on training data for behavior. Verify in this order:

1. Owning source, public types, and tests in the repo
2. CLI help and package scripts named in the nearest README
3. Existing MDX or markdown in the doc layer `AGENTS.md` names
4. ADRs and architecture pages—proposed intent until merged behavior matches
5. Issues and user reports—to learn the reader's problem, not to establish product truth

If a claim cannot be verified, omit it or name the missing owner. Never leave `[VERIFY]` in finished copy. Do not document proposed behavior as shipped.

## Method

1. Name the piece's one job and the reader's task.
2. Find the page that already owns the topic; extend it before creating a new page.
3. Outline: outcome → prerequisites → happy path → alternatives → failures → related links.
4. Draft and verify claims together against source.
5. Self-edit for retrieval: repeat full nouns in key statements; put the critical fact locally, not only behind a link.
6. Review passes: purpose and structure, accuracy, completeness, style and retrieval, diff discipline (no drive-by rewrites).

## Modes

**Docu MDX** (when the repo has `apps/docu/content/docs/`): `title` and `description` frontmatter; folder `meta.json` when navigation changes; inbound body link from a related hub (no orphan pages); permanent redirects in doc app config when a route moves; MDX components only where nearby pages already use them. Finish with `pnpm --filter @repo/docu checktypes` when preparing to ship doc changes.

**README** (`**/README.md`): follow `.cursor/rules/base/readme.mdc`—root owns the product story; apps and packages stay lean with links to technical docs.

**Root product markdown** (e.g. `PRODUCT.md`, `ARCHITECTURE.md`, `DESIGN.md` when `AGENTS.md` says so): same voice; capability names match that repo's architecture source; upstream hosted docs win only where `AGENTS.md` says they override local project docs.

## Constraints

- NEVER invent flags, endpoints, defaults, examples, metrics, or user reactions.
- NEVER turn one support thread into a new page without deciding docs vs product scope.
- NEVER duplicate a broad guide when a section or cross-link fixes the gap.
- NEVER contradict the consuming repo's public one-liner, banned copy, or capability names for narrative convenience.
- Support evidence identifies confusion; implementation and tests establish behavior.

## Not this skill

- `/w-docs` — which layer to patch
- `/w-api-docs` — OpenAPI and generated clients
- `/w-deslop` — code slop on branches
- `/w-architecture` — ADR and boundary planning
- Personal or marketing voice catalogs (e.g. gabo)

© blockmatic-icebox · MIT · blockmatic-icebox/basilic-skills

Similar skills

All skills for Writing and docs →

technical-writing by other authors comes first.

technical-writing backnotprop technical-writing is a Claude Code skill for writing and reviewing docs, RFCs, READMEs, PR descriptions, and commit messages. Run it with /technical-writing. CX Codex +1 10,700installs technical-writing riekelt technical-writing — a skill for drafting and reviewing technical documents with source and style rules. Use it for READMEs, specs, design docs, reports, and plans. CX Codex +1 27,800installs technical-writing frappe technical-writing — a skill that makes the agent write in Simplified Technical English: short sentences, active voice, one word per meaning. Meant for docs, READMEs and commits. CX Codex +1 766installs technical-writing Mindrally Enforces strict technical writing rules for developer tutorials and documentation. It eliminates cliches and bullet lists to produce deep, practical implementation guides. CX Codex +1 1,200installs technical-writing proffesor-for-testing Sets rules for technical writing: lead with value, back claims with examples and sourced numbers, cut filler words. Triggers when drafting blog posts, docs, or tutorials. CX Codex +1 209installs technical-blog-writing 101-skills technical-blog-writing sets the skeleton for a dev-facing post: article types, rules for code samples, and depth matched to the reader. Useful when a tutorial or architecture write-up has to ship. CX Codex +1 237installs writing-simplified-technical-english PostHog writing-simplified-technical-english rewrites English prose to the ASD-STE100 controlled-language standard: one meaning per word, active voice, short sentences. Built for reports, PR descriptions and prompts. CX Codex +1 138installs reviewing-technical-prose riekelt reviewing-technical-prose — a skill for reviewing someone else's technical writing: it flags banned constructions, unsupported claims and structural defects, then runs a delivery checklist before a document ships. CX Codex +1 26,900installs technical-video-script Samuel Berthe technical-video-script is a Claude Code skill that writes and reviews scripts for technical videos and screencasts. It can also turn a blog post, changelog, or docs page into a video plan. CX Codex +1 14,000installs create-technical-spike official github create-technical-spike is a GitHub Copilot skill that structures time-boxed research into a technical decision. It activates when a question needs resolution before implementation can move ahead. CX Codex +1 9,000installs technical-article-writer samber technical-article-writer drafts developer-focused tutorials, benchmarks, and postmortems. It guides you through an intake interview and generates 10 headline options. CX Codex +1 5,600installs

From the same set45

The whole set →

Project sponsors

Companies that keep this analytics open