Skip to main content
skill CX Codex

technical-writing · proffesor-for-testing — Claude Code skill: what it does, how to install

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.

MIT 209 installs ★ 533 updated 2026-11-04

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add proffesor-for-testing/agentic-qe --skill technical-writing -a claude-code
Open on GitHub

What technical-writing does

The skill lays out a blog post structure (hook, context, promise, then three to five sections with one idea each, closing with a concrete takeaway) plus an editing checklist: the title has to promise something specific, claims need examples, and every figure traces back to a source. It also splits advice by audience, developers, QA engineers, leadership, since each reads for different details.

The core rule bans invented numbers outright: if a figure isn't known, the skill says to drop in a [number?] placeholder and ask rather than write something plausible. A table lists words to cut (basically, leverage, very) alongside before-and-after rewrites that turn vague corporate phrasing into specifics. The package also ships integration examples with the qe-quality-analyzer and qe-api-contract-validator agents for generating and reviewing docs from code, part of the agentic-qe toolset those Task() and FleetManager calls depend on.

What it helps with

  • rewrite corporate-sounding drafts into concrete sentences
  • structure a blog post around a hook and a clear takeaway
  • run documentation through a pre-publish checklist
  • strip filler words and jargon from a draft
  • generate and review code documentation through qe agents

Example prompts for the agent

  • Rewrite this README paragraph using the technical-writing skill's rules
  • Check this article draft against the technical-writing checklist before I publish it
  • Generate docs for PaymentService.ts and flag any corporate jargon

How to install technical-writing

1Skills CLI (Vercel)

npx skills add proffesor-for-testing/agentic-qe --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 proffesor-for-testing/agentic-qe --skill technical-writing -a claude-code; the skill lands at ~/.claude/skills/technical-writing/SKILL.md.

What does the technical-writing skill do?

It sets structure and rules for technical content, blog posts, docs, tutorials, pushing for concrete examples over vague claims and banning invented figures.

How is this different from a plain draft?

Every number, duration, and date in the output has to trace to a source like a tracker, benchmark, PR, or release note; without one, the skill requires a placeholder instead of a plausible-sounding figure.

Source text

SKILL.md · MIT
---
name: technical-writing
description: "Write clear, engaging technical content from real experience. Use when writing blog posts, documentation, tutorials, or technical articles."
category: communication
priority: medium
tokenEstimate: 800
agents: [qe-quality-analyzer, qe-api-contract-validator]
implementation_status: optimized
optimization_version: 1.0
last_optimized: 2025-12-03
dependencies: []
quick_reference_card: true
tags: [writing, documentation, communication, blogs, tutorials]
trust_tier: 1
validation:
  schema_path: schemas/output.json
  eval_path: evals/technical-writing.yaml
---

# Technical Writing

<default_to_action>
When writing technical content:
1. LEAD with value (what will reader learn/gain?)
2. SHOW, don't tell (specific examples, code, and numbers you measured or can source)
3. STRUCTURE for scanning (headers, bold, short paragraphs)
4. CUT ruthlessly (every sentence must earn its place)
5. BE honest about trade-offs
6. NEVER invent figures: every number, duration, and date traces to a source (tracker, benchmark, PR, release note). Missing a number? Write `[number?]` and ask, or describe what changed without one.

**Blog Post Structure:**
```markdown
# Title (specific promise)

## Opening (2-3 paragraphs)
- Hook: The problem or insight
- Context: Why this matters
- Promise: What they'll learn

## Body (3-5 sections)
- One clear idea per section
- Support with examples/code/data

## Closing
- Key takeaway (1-2 sentences)
- Action reader can take
```

**Before/After:**
❌ "We implemented a comprehensive testing strategy..."
✅ "We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement."
</default_to_action>

## Quick Reference Card

### Core Principles

| Principle | Bad | Good |
|-----------|-----|------|
| **Lead with value** | "In today's landscape..." | "Here's what changed when we moved testing into refinement" |
| **Show, don't tell** | "We improved testing" | "Bugs found per sprint, before and after, from our tracker: [before]→[after]" |
| **Be specific** | "Performance improved" | "p95 response time before and after, with how and where it was measured" |
| **Honest trade-offs** | "This approach is best" | "TDD slowed our first features; here is what we got back, with the numbers we measured" |
| **Source every figure** | "Coverage jumped 40%" (from memory) | The figure plus where it came from, or no figure at all |

Bracketed values are placeholders for your own measured data. Never fill them with plausible-sounding numbers.

### Words to Cut

| Kill | Reason |
|------|--------|
| basically, actually, probably | Hedge words |
| leverage, synergy, paradigm | Corporate speak |
| very, really, quite | Unnecessary qualifiers |
| it should be noted that | Just note it |

---

## Audience-Specific Writing

### For Developers
- Lead with code or concrete problem
- Show implementation details
- Discuss trade-offs and alternatives
- Link to repos or examples

### For QA/QE
- Start with testing challenge
- Show strategy, not just tools
- Include risk assessment
- Provide adaptable heuristics

### For Leadership
- Open with business impact
- Use metrics that matter
- Connect technical to outcomes
- Keep technical details concise

---

## Editing Checklist

Before publishing:
- [ ] Title promises something specific
- [ ] Opening hooks in 30 seconds
- [ ] Claims backed by examples
- [ ] Every number, duration, and date traced to a source (or removed)
- [ ] All unnecessary words cut
- [ ] Code examples tested and correct
- [ ] Takeaway crystal clear
- [ ] Would send to respected colleague

---

## Example Transformations

**Before:**
"We decided to implement a more comprehensive testing strategy that would allow us to catch bugs earlier in the development lifecycle."

**After:**
"We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement, identifying risks before code is written."

---

**Before:**
"The benefits of this approach are numerous and include improved quality, faster feedback loops, and better team collaboration."

**After:**
"Three outcomes: bugs now surface during refinement instead of after merge, the regression suite stopped growing with every release, and developers ask QE for input during design." (Add figures only if you measured them, and say where they came from.)

---

## Agent Integration

```typescript
// Generate documentation from code
const docs = await Task("Generate Docs", {
  source: 'src/services/PaymentService.ts',
  format: 'markdown',
  includeExamples: true
}, "qe-quality-analyzer");

// Review documentation quality
const review = await Task("Review Docs", {
  files: ['README.md', 'docs/api.md'],
  checkClarity: true,
  checkCodeExamples: true
}, "qe-quality-analyzer");
```

---

## Agent Coordination Hints

### Memory Namespace
```
aqe/technical-writing/
├── generated-docs/*   - Auto-generated documentation
├── reviews/*          - Documentation review findings
└── templates/*        - Reusable doc templates
```

### Fleet Coordination
```typescript
const docsFleet = await FleetManager.coordinate({
  strategy: 'documentation',
  agents: [
    'qe-quality-analyzer',         // Generate and review
    'qe-api-contract-validator'    // API doc accuracy
  ],
  topology: 'sequential'
});
```

---

## Related Skills
- [bug-reporting-excellence](../bug-reporting-excellence/) - Technical bug writing
- [code-review-quality](../code-review-quality/) - Review documentation

---

## Remember

**You're not writing to impress.** You're writing to help people solve problems you've already solved. Be the colleague you wish you'd had.

**Write from experience.** Only write about what you've done in production. If exploring, say so.

© proffesor-for-testing · MIT · proffesor-for-testing/agentic-qe

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 akillness technical-writing is a Claude Code skill for drafting technical documents for engineers and operators. It handles requests for ADRs, runbooks, migration plans, and internal guides. CX Codex +1 546installs 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 writing-clearly-and-concisely softaworks writing-clearly-and-concisely — a Claude Code plugin that improves prose quality in documentation, commit messages, error messages, and UI text. Runs whenever you write text that people will read. ★ 2,707repo stars technical-tutorials jonathimer technical-tutorials configures the coding agent to generate step-by-step technical guides, quickstarts, and code walkthroughs. Useful for drafting developer docs that work out of the box. CX Codex +1 ★ 88repo stars technical-writer SuperClaude-Org technical-writer — a subagent that writes technical documentation: API references, guides, specs, and installation instructions with code examples and accessibility checks. CX Codex ★ 23,950repo stars written-communication RefoundAI written-communication — a skill that restructures business writing around the conclusion instead of the search that led to it. CX Codex +1 2,300installs

From the same set73

The whole set →
compatibility-testing compatibility-testing organizes cross-browser and responsive layout testing across devices and screen sizes. Useful before major releases and right after layout rewrites. CX Codex +1 659installs api-testing-patterns api-testing-patterns — a skill with ready-made patterns for testing REST and GraphQL APIs: contracts, auth, idempotency, race conditions. Useful when writing tests or picking a strategy. CX Codex +1 618installs regression-testing regression-testing selects affected tests using git diff and impact analysis instead of running the whole suite. Cuts commit test execution down to 5–10 minutes. CX Codex +1 339installs test-automation-strategy The test-automation-strategy skill shapes a test automation plan, fixes test-pyramid imbalance, and connects checks to CI/CD workflows. CX Codex +1 261installs test-design-techniques test-design-techniques applies systematic test design: boundary value analysis, equivalence partitioning, decision tables, state transition testing, and combinatorial coverage. CX Codex +1 208installs brutal-honesty-review The brutal-honesty-review skill guides an agent through blunt reviews of code, tests, and technical decisions. It asks what is broken, why it matters, and how to fix it. CX Codex +1 186installs mobile-testing mobile-testing — a skill for testing iOS and Android apps: gestures, sensors, permissions, device fragmentation, and performance. CX Codex +1 177installs n8n-workflow-testing-fundamentals n8n-workflow-testing-fundamentals — a skill for testing n8n workflows: validates structure, nodes, data flows, error handling, and execution performance of automation workflows. CX Codex +1 176installs

Project sponsors

Companies that keep this analytics open