Technical Writing

---

name: Technical Writing description: This skill should be used when the user asks to "write blog post", "technical article", "tutorial", "explain concept", or needs guidance on technical writing for external audiences. Provides patterns for technical blogs and articles in both English and Japanese.

<writing_principles> Capture attention in the first paragraph Start with a problem the reader faces Use a surprising fact or statistic Tell a brief relatable story

<language_guidelines>

Confident, helpful, peer-to-peer First person ("I found that...") or second person ("You can...") <sentence_length>Vary between short and medium</sentence_length> Overly formal academic language, buzzwords without substance

<title_patterns> How to [achieve result] with [tool/technique] How to Implement Rate Limiting with Redis [N] [Things] Every Developer Should Know About [Topic] 5 Things Every Developer Should Know About TypeScript Generics [A] vs [B]: Which Should You Choose in [Year]? REST vs GraphQL: Which Should You Choose in 2025? Solving [Problem] with [Solution] Solving N+1 Queries with DataLoader Understanding [Concept]: A Deep Dive Understanding React Reconciliation: A Deep Dive What I Learned [Building/Using] [Thing] What I Learned Building a Real-Time Collaboration System </title_patterns>

<best_practices> Start with a compelling hook in the first paragraph Use a problem the reader faces, a surprising fact, or a brief relatable story Put the most important point first using inverted pyramid structure Lead with the conclusion, provide TL;DR for long articles Test all code examples before publishing Verify code compiles, runs, and produces expected output Explain code context before or after each snippet Describe what the code does and why it's written that way Support claims with evidence Include benchmarks, examples, or reasoned arguments for technical claims Each section should have one clear purpose Split sections covering multiple ideas, use headings that summarize the key point Use diagrams for architectural concepts Include visual representations to complement text explanations Vary sentence length for readability Mix short and medium sentences to maintain reader engagement Adapt style to language conventions Use conversational but professional tone in English, です・ます調 in Japanese technical articles </best_practices>

<anti_patterns> Hiding the main point deep in the article Put the most important point first, use inverted pyramid structure Not explaining why the topic matters Explain why the reader should care early in the article Showing code without explaining its purpose Explain what code does and why before or after the snippet Making claims like "X is the best" without evidence Support claims with benchmarks, examples, or reasoned arguments Title promises more than content delivers Ensure title accurately reflects content and scope Long code blocks without explanation Break up code with explanations, highlight key lines, add comments Starting with "In this article..." or similar phrases Start with a hook that captures attention immediately </anti_patterns>

<error_escalation> Grammar or style issue Fix issue, follow style guide Technical inaccuracy in example Verify and correct example Misleading or incorrect technical claim Stop, verify claim before publishing Content could cause harm if followed Block publication, require expert review </error_escalation>

<related_agents> Article structure and outline planning Code example extraction and technical accuracy verification Publishing workflow and platform-specific formatting Fixing broken examples, outdated information, and technical errors </related_agents>

<related_skills> Symbol operations for extracting code examples from projects Library documentation lookup for accurate technical references Researching technical topics and verifying claims Creating reference documentation from blog content </related_skills>