technical-writing

Dieser Auszug wurde bei der Prüfung gespeichert. Die externe Quelle enthält die vollständige und aktuelle Version.

---
name: technical-writing
description: Writes technical blog posts about features being built. Triggers when user asks to write about development progress, implementations, or project updates.
---

# Technical Writing Skill

## Overview

Create technical blog posts about features you're building. This skill analyzes your codebase to understand implementations, then structures clear, engaging content that balances technical detail with readability while avoiding AI-sounding language.

## Process

### Phase 1: Research and Planning

**1.1 Load Writing Guides (REQUIRED - Load First)**

Before any other work, load the following:

1. **Writing Rules** (from `WRITING_ANTI_PATTERNS_PATH` env var, or fall back to `references/anti-patterns.md`) - Comprehensive lists of AI-sounding words, phrases, and patterns to avoid. This is the foundation - what NOT to sound like.

2. **Writing Style Guide** (from `WRITING_STYLE_GUIDE_PATH` env var, or fall back to `references/style-guide.md`) - Personal writing voice, tone, structure, and signature moves. This is the voice layer - what TO sound like.

**PRIORITY RULE**: When guides conflict, anti-patterns win. Avoiding AI patterns always takes precedence over stylistic choices.

**1.2 Fetch WordPress Taxonomy (if configured)**

If `WORDPRESS_URL`, `WORDPRESS_USERNAME`, and `WORDPRESS_APP_PASSWORD` env vars are set, fetch available categories and tags before writing so frontmatter uses existing taxonomy:

```bash
curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/categories?per_page=100" | python3 -c "import sys,json; [print(c['name']) for c in json.load(sys.stdin)]"

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/tags?per_page=100" | python3 -c "import sys,json; [print(t['name']) for t in json.load(sys.stdin)]"
```

Use these when choosing `category` and `tags` in frontmatter. Prefer existing values. Skip this step if WordPress env vars are not set.

**1.3 Understand What Was Built**


Investigate the codebase to understand the feature:

- Ask which feature or changes they want to write about
- Use git to check recent commits if relevant (skip if not a git repo): `git log --oneline -10`
- Read relevant code files to understand implementation
- Identify key technical decisions, architecture, and interesting details
- Note any challenges solved or clever solutions

**1.4 Plan the Structure**

Plan what to cover in the post. Use these as a guide, not a rigid template:

- **Opening**: Start with an engaging hook or context for what you built
- **Overview**: Brief explanation of the feature (2-3 sentences)
- **Problem/Value**: Why this matters or what problem it solves
- **Technical Details**: How it works with code snippets
  - Key implementation details
  - Interesting technical decisions
  - Architecture or design patterns used
- **Challenges**: What was tricky and how you solved it (if relevant)
- **Future**: Next steps or related features (if relevant)
- **Tech Stack**: Technologies used (can be woven into the narrative or listed)

The actual headings, structure, and flow should feel natural to the specific post - not formulaic.

### Phase 2: Writing

**2.1 Draft Creation**

Create the blog post applying BOTH guides you loaded in Phase 1. After drafting, re-read the post against the anti-patterns guide and fix any violations before saving.

**Code Snippets:**
- Keep snippets short (5-15 lines)

**Target length**: Match length to complexity. Default short.
- Simple idea, announcement, or single concept: 400-600 words
- Moderate technical walkthrough: 600-900 words
- Deep architectural dive or multi-part explanation: 900-1200 words

Err on the side of shorter. If the post can be said in 500 words, don't stretch it to 800. Cut filler, merge thin sections, and stop when the point is made.

**2.2 Save the Draft**

Save the completed blog post to the drafts directory (create the folder if missing).

**To find the save p