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.
version	2.0.0

Provide structured patterns for writing technical blogs and articles that effectively communicate technical concepts to external audiences. Write Read Edit WebSearch mcp__plugin_claude-code-home-manager_context7__resolve-library-id mcp__plugin_claude-code-home-manager_context7__query-docs Five types: tutorial (task-based), concept explanation (deep understanding), comparison (decision help), case study (real-world story), opinion piece (best practices) Capture attention in the first paragraph using problem statement, surprising fact, or relatable story Lead with conclusion, most important information first, details follow Demonstrate with working code, diagrams, and before/after comparisons rather than abstract description Step-by-step guide to accomplish a specific task Are you teaching readers how to accomplish a specific task? Create tutorial with step-by-step instructions and working examples Consider concept explanation for understanding or comparison for decision-making Developers learning a new skill

Problem statement / What you'll learn

Prerequisites

Step-by-step instructions

Complete working example

Troubleshooting common issues

Next steps / Further reading

1500-3000 words Deep dive into a technical concept Are you explaining a complex concept for deeper understanding? Create concept explanation with examples and misconceptions Use tutorial for task-based learning or opinion piece for best practices Developers seeking understanding

Hook / Why this matters

Core concept explanation

Analogies and visualizations

Practical examples

Common misconceptions

When to use / When to avoid

1000-2500 words Compare technologies, approaches, or tools Are you helping readers choose between multiple options? Create comparison with feature analysis and use case recommendations Use tutorial for implementation or concept explanation for understanding Developers making technical decisions

Context and criteria

Overview of each option

Feature-by-feature comparison

Benchmark results (if applicable)

Use case recommendations

Conclusion with clear guidance

1500-2500 words Real-world implementation story Are you sharing a real-world implementation experience? Create case study with challenge, solution, and lessons learned Use tutorial for general how-to or opinion piece for best practices Developers and technical leaders

Background and challenge

Solution approach

Implementation details

Results and metrics

Lessons learned

Recommendations

1500-3000 words Technical opinion or best practices Experienced developers

Thesis statement

Supporting arguments with evidence

Counterarguments addressed

Practical implications

Call to action

800-1500 words

<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

Each section should have a single clear purpose If a section covers multiple ideas, split it Use headings that summarize the key point Demonstrate concepts with examples Include working code snippets Use diagrams for architecture Show before/after comparisons Be concise, get to the point Lead with the conclusion Use bullet points for lists Provide TL;DR for long articles Build trust through accuracy and honesty Cite sources and benchmarks Acknowledge limitations Show your work (methodology)

<language_guidelines> Conversational but professional 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

読者との対話を意識した文体 専門的だが親しみやすい 技術記事: です・ます調、個人ブログ: 柔軟に 過度に硬い表現、主語の省略による曖昧さ 英語の技術用語は適度にカタカナで使用可 Adapt style to each language's conventions (not literal translation) Keep technical terms consistent Adjust examples for cultural relevance when appropriate - Type: [tutorial/concept/comparison/case_study/opinion] - Audience: [beginner/intermediate/advanced developers] - Core message: [one sentence] - Language: [en/ja/both] - Target length: [word count] [Section headings with key points] [Article content] - [ ] Hook is compelling - [ ] Each section has one clear purpose - [ ] Code examples tested and working - [ ] Technical claims verified - [ ] Read aloud for flow - [ ] Trimmed unnecessary words - [ ] Title and headings optimized

<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 [Current Year]? 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>

Test all code examples compile and run before publishing Verify all technical claims with sources or benchmarks Start with a compelling hook, never generic openings like "In this article..." Explain code context before or after each snippet Use inverted pyramid: most important point first Break long code blocks with explanations Ensure title accurately reflects content scope Identify article type, target audience, and core message Research topic using Context7 and WebSearch for accuracy Create outline following the appropriate pattern structure Write the hook and introduction first Draft each section following one-idea-per-section principle Add code examples, diagrams, and supporting evidence Verify all code examples compile and run Check technical claims against sources Review against edit checklist Read aloud for flow and trim unnecessary words

<error_escalation inherits="core-patterns#error_escalation"> Grammar or style issue Technical inaccuracy in example Misleading or incorrect technical claim Content could cause harm if followed </error_escalation>

Verify all technical claims Test all code examples Write for target audience level Jargon without explanation Untested code examples Overly complex explanations

<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>

<related_agents> Primary agent for technical article and blog post generation Review technical writing for clarity, accuracy, and structure </related_agents>