technical-writing-density

An auto-invoked agent skill that sharpens how coding agents apply concision to technical documentation — API references, design specs, RFCs, runbooks, schema docs, configuration references, and issue-tracker tickets (Jira, Linear, GitHub/GitLab issues).

It is a companion to writing-clearly-and-concisely, the general prose skill that carries William Strunk Jr.'s rules. That skill supplies the rules; this one governs how to apply the "omit needless words" rule when the reader needs precision.

Why it exists

Agents over-apply "omit needless words." On ordinary prose, cutting words almost always helps. On technical prose it can delete the reason a default was chosen, a precondition, or a clause that rules out a wrong reading — trading a moment of brevity for an hour of a reader's confusion.

This skill reframes the rule: "omit needless words" governs information density, not length. Cut empty words ruthlessly; keep every reason, constraint, and disambiguation, even when keeping them makes a sentence longer.

What it does

When an agent writes or edits technical documentation, or creates or updates an issue-tracker ticket, the skill:

• restates "omit needless words" as a density test — does removing this lose a reason, a constraint, or a disambiguation?
• lists what to cut without hesitation (filler, hedges, throat-clearing) and what to keep at the cost of length (reasons, constraints, disambiguations),
• names the Strunk rules that pay off unconditionally in technical docs because they remove ambiguity rather than detail: active voice, concrete language, one idea per sentence, and parallel structure for parallel requirements, and
• pushes back on over-condensing: break distinct items (parameters, options, error codes, steps) into bulleted or numbered lists so the reader can scan, rather than folding them into a dense paragraph in the name of brevity.

It is deliberately small. It refines one rule, reinforces four, and guards scannability; the general writing skill does the rest.

How it works

The SKILL.md frontmatter carries a description that names its triggers: writing or editing technical documentation, and creating or updating issue-tracker tickets, alongside writing-clearly-and-concisely. Agents match a task against installed skill descriptions and load the matching skill before acting.

---
name: technical-writing-density
description: Use when writing or editing technical prose a reader relies on for precision, and when creating or updating issue-tracker tickets (Jira, Linear, GitHub/GitLab issues, PR descriptions) ...
---

• Claude Code auto-discovers any SKILL.md in its skills directory and reads the description to decide when to invoke.
• opencode, Zed, Codex, and Cursor — and any tool that reads an AGENTS.md skills table — load it through openskills read technical-writing-density.

What's inside

skills/technical-writing-density/
└── SKILL.md

One file. The skill is pure judgment guidance, so it needs no references, templates, or scripts.

The companion skill (required for full effect)

This skill refines writing-clearly-and-concisely; it does not replace it. Use both together: the general skill supplies Strunk's rules, and this skill governs the concision rule under precision constraints. Install the companion too, or the density guidance has no rule set to attach to.

The companion lives in a separate, third-party repository — softaworks/agent-toolkit — and bundles its own source texts under its own license. This repository therefore references it rather than copying it, so you always install the maintained upstream version. The install steps below install both.

If you use Claude Code with the elements-of-style plugin, you already have writing-clearly-and-concisely from that marketplace. In that case install only this skill and skip the companion step.

Installation

Prerequisites

openskills is a universal skills loader for AI coding agents (Claude Code, opencode, Zed, Codex, Cursor, and anything that reads AGENTS.md). It needs Node.js 20.6+ and Git.

npm install -g openskills   # or call any command below as: npx openskills ...

Option 1 — openskills (recommended)

Install the companion first, then this skill. The owner/repo/subpath form installs exactly one skill from a multi-skill repo:

# companion: writing-clearly-and-concisely, pinned to its upstream subpath
openskills install --global softaworks/agent-toolkit/skills/writing-clearly-and-concisely

# this skill
openskills install --global mlwelles/technical-writing-density

# register both in AGENTS.md (needed for opencode / Zed / Codex / Cursor; not for Claude Code)
openskills sync

Drop --global to install into the current project (./.claude/skills) instead of ~/.claude/skills. Add --universal to install into .agent/skills/ for a shared multi-agent AGENTS.md setup.

Codex and Cursor read skills from an AGENTS.md in the project root. Run openskills sync in the repo where you want the skills available — or openskills sync -o <path> to target a specific AGENTS.md — and both tools then load a skill on demand with npx openskills read <skill-name>.

Option 2 — convenience script

The repository ships an optional install.sh that runs the two installs above. It is a convenience, not a requirement — Option 1 and Option 3 do the same work by hand.

git clone https://github.com/mlwelles/technical-writing-density
cd technical-writing-density
./install.sh             # both skills globally
./install.sh --project   # both skills into the current project

Option 3 — manual install (no openskills)

Skills are just folders with a SKILL.md. Copy each into your skills directory.

# this skill
git clone https://github.com/mlwelles/technical-writing-density
cp -r technical-writing-density/skills/technical-writing-density ~/.claude/skills/

# companion skill, from its upstream repo
git clone https://github.com/softaworks/agent-toolkit
cp -r agent-toolkit/skills/writing-clearly-and-concisely ~/.claude/skills/

For opencode, Zed, Codex, or Cursor, add both skills to your project's AGENTS.md <available_skills> block — by hand, or with openskills sync. Claude Code auto-discovers anything under ~/.claude/skills.

Using it with writing-clearly-and-concisely

The two skills are designed to fire together on technical prose:

1. Invoke writing-clearly-and-concisely whenever you write or edit prose a human will read.
2. When that prose is technical — an API reference, design spec, RFC, runbook, schema doc, configuration reference, or an issue-tracker ticket (Jira, Linear, GitHub/GitLab issue) — load technical-writing-density alongside it.

The general skill applies Strunk's rules. This skill changes one outcome: it stops the agent from cutting a clause that carries a reason, a constraint, or a disambiguation, and it leans hardest on the rules that remove ambiguity — active voice, concrete nouns, one-idea sentences, and parallel structure.

To make this automatic, add a line to your agent instructions (CLAUDE.md, AGENTS.md, or equivalent):

When editing technical documentation or creating/updating an issue-tracker ticket, invoke writing-clearly-and-concisely and load technical-writing-density alongside it.

Credit

The rules this skill refines are William Strunk Jr.'s, from The Elements of Style (1918). They reach your agent through the companion skill, writing-clearly-and-concisely, maintained in softaworks/agent-toolkit. This repository contains original guidance about applying one of those rules to technical prose; it reproduces none of Strunk's text.

License

MIT — see LICENSE. The license covers this repository's original text. The companion skill and its source texts are governed by their own repository's license.