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
npx skills add blockmatic-icebox/basilic-skills --skill technical-writing -a claude-codeWhat 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.mdagainstAGENTS.mdand the architecture sources.
How to install technical-writing
1Skills CLI (Vercel)
npx skills add blockmatic-icebox/basilic-skills --skill technical-writing -a claude-code2Manually: put the files in place
~/.claude/skills/technical-writing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/technical-writing/
1Skills CLI (Vercel)
npx skills add blockmatic-icebox/basilic-skills --skill technical-writing -a codex2Manually: put the files in place
.agents/skills/technical-writing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add blockmatic-icebox/basilic-skills --skill technical-writing -a cursor2Manually: put the files in place
.cursor/skills/technical-writing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install blockmatic-icebox/basilic-skills skills/technical-writing2Manually: put the files in place
.github/skills/technical-writing/SKILL.md1Skills CLI (Vercel)
npx skills add blockmatic-icebox/basilic-skills --skill technical-writing -a gemini-cli2Platform CLI
gemini skills install https://github.com/blockmatic-icebox/basilic-skills --path skills/technical-writingManually: put the files in place
.devin/skills/technical-writing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add blockmatic-icebox/basilic-skills --skill technical-writing -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.