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. Includes a Japanese prose-quality ruleset for drafting and revising Japanese manuscripts, plus a language-neutral long-form structure ruleset for books and serialized pieces.
version	2.2.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

読者との対話を意識した文体 専門的だが親しみやすい 技術記事: です・ます調、個人ブログ: 柔軟に 過度に硬い表現、主語の省略による曖昧さ 英語の技術用語は適度にカタカナで使用可 Canonical ruleset for drafting and revising Japanese technical prose. Directive text is English; illustrative bad/good examples and Japanese-specific tokens (中黒「・」, dashes「—」「―」「――」, 「」, footnote [^label], phrases) are kept in Japanese verbatim because they demonstrate Japanese-punctuation and particle norms. Write one sentence per line; separate paragraphs with a blank line. Put code, diff, log, and config fragments in code blocks. Demote side notes (term origins, names of formalizations) to footnotes [^ラベル] instead of inlining them. Bullet lists are fine for definitions and classifications; bold the term being defined. Bold a term on its first definition or introduction; for later mentions, quotation, or nicknames use 「」. Do not use dashes (em dash「—」, horizontal bar「―」, double dash「――」) in Japanese body text or headings. For appositive or parenthetical insertion (「A——挿入——B」) use parentheses（）; for restatement (「A——B」) split into two sentences with 。 or join with 、. Exception (not covered): en dash「–」for ranges, English compounds like Curry–Howard, code blocks, and bibliographic info. Do not use 中黒（・）for Japanese parallel or enumeration. It is allowed only inside a single proper noun. Do not cram two elements into a heading or column heading with a rule line (罫線「─」U+2500 or dashes) like「種別──主題」「主題──概念」. A heading is a single natural phrase (narrow to one element, or join with a particle or comma). Column headings must not be bare category names like「基礎」「補足」; specify content, e.g.「同値関係としての分類」「ループ不変条件と帰納法」. A bullet listing a term and its definition uses a fullwidth colon, not a rule line:「**用語**：説明」. Use paragraph writing (パラグラフライティング). A paragraph is one step of argument; the reader must follow the logic paragraph by paragraph. One topic per paragraph. Split long paragraphs that mix multiple scene-progressions (investigation, report, verification, evaluation) into one-step paragraphs. The first sentence of a paragraph should reveal what the paragraph is about. At a paragraph's start, make the logical relation to the previous paragraph explicit with a connective (「であれば」「実際」「しかし」「この例自体からも」). Advance the argument in one direction. Do not use a "conclude then handle objection then restate conclusion" shape. Finish objections and doubts first, then state the conclusion once. Defenses of an example (looks contrived, pre-empting) must not break the flow mid-climax; handle them together at the start of the next section. Explicitly deny a likely wrong reading before stating the real reason (「その理由は『〜だから』ではない。〜だからだ」). When negating with「AではなくB」, add one sentence of grounds for the negation; a counterfactual (「もしAなら、〜だっただろう」) is often usable. In concession (「確かに〜」), stay at fact confirmation. Do not assert, as the author's voice or as causation, something you later correct (self-contradiction). To provisionally grant a surface diagnosis, attribute it to the reader or common view (「〜と要約できてしまうかもしれない」). Do not pre-reveal climax information (figures, specific facts) in the paragraph before the climax. When negating or limiting, quote the exact proposition being negated in 「」 (e.g.「明文化されていればすべてを任せられる」を意味しない); do not settle for vague negation like「何もかもが解決するわけではない」. Place forward references (「後の章で扱う」) where the argument has settled (paragraph or section end), not mid-argument. Do not mechanically convert speculation, possibility, reader-doubt, or counterfactual into assertion.「かもしれない」「だろう」「ようだ」「らしい」are removed only when they weaken a claim without grounds; keep the uncertainty when they express unconfirmed possibility, a character's perception, log-based inference, a doubt the reader might hold, or a counterfactual. Convert to assertion only when the proposition is settled by in-text grounds. 提示し続けているかもしれない → 提示し続けている 提示し続けている可能性がある Do not lump distinct things as "the same". 三つの互いに依存する未決定の決定を「同じ決定を別々に下していた」と書く どれも別々の決定であり、しかも互いに依存している Do not reduce a multi-factor event to a single cause; if an example contains multiple kinds of problems, separate them and map which tool explains which. 契約の欠如と情報隠蔽の失敗が混在した事象を一括して「情報隠蔽の問題」と説明する Keep treatment of the same concept consistent across chapters and sections (do not classify something as「人間が決める」in one section and「チームで合意する」in another). Classification, definition, and term status must be uniform throughout. When asserting causation, state the mechanism in one sentence; do not write「AだとBになる」and omit the reason. 手順で分けると変更が全体に波及する 各工程がデータを受け渡すための表現を共有してしまい、その表現を変えると全体に波及する Do not write detection, guarantee, or resolution as if always achievable; state conditionally and precisely (「〜しやすい」「〜できることが多い」「〜が成り立つときに限り」). Verify the given example actually supports the whole claim; if it supports only part, narrow the claim to match the example. A point deferred forward with「次節で扱う」must actually be paid off there; do not plant foreshadowing you never collect. After a concession or limitation (「ただし」「とはいえ」), always advance the argument; do not end on the adversative and leave it hanging. A section's central term must have its definition or scope stated before use within or before that section; do not start using it undefined. When merging several concepts under one umbrella term, state in one sentence just before naming that they reduce to the same thing; also bridge the reverse (decomposition) operation. Do not introduce proper nouns (file names, function names, identifiers) that are not referenced later; use general phrasing like「仕様書」「金額計算のユーティリティ」. When an abstract phrase's referent is not uniquely determined by context, pin it down in place with a parenthetical apposition so the reader need not look back. When adding a new example or scene increases the context the reader must hold, preface it with what differs from the prior example and why another is needed. In chapter and section intros, do not pack excessive detail unrelated to the example to come. Even within an example section, omit only the detail unrelated to that section's question or consequence; keep concretes needed for the argument. Typical omissions: decorative precision of agent reports (timestamps, HTTP status, coverage %), and proper nouns not referenced later. In examples, write an actor-as-subject chain of actions (「リポジトリを調査して特定し、見つけてくれた」), not a list of results or passive voice (「特定され、判明した」). Do not gratuitously prefix fictional personas like「入社2年目のエンジニアが」. In argument, do not call the reader「あなた」; use a role name (「開発者」「読者」). Reserve second-person address for limited spots (scene setup「〜としよう」, chapter or book closings). Choose concrete referents; do not blur with broad words like「AI」「ツール」. Once you introduce a formalization or term (K, 契約, 不変条件, etc.), keep using that word; do not regress to vague words like「文脈」「ツール」「AI」(using「文脈」as a pre-formalization introductory word is fine). Choose the conventional term in the field for a translation or technical term (push notification is「配信」not「配送」); do not assign a near-synonym Kanji word by general feel. Refer to people themselves in the original spelling (Lehman, Bainbridge). But for historical figures or eponymous concepts introduced by their settled name, use the katakana nickname current in Japanese. Do not repurpose a term-sounding word into a non-term context (calling the chain from system to human a「経路」). Use ordinary phrasing like「届くまでの流れ」「あいだに何があるか」. This is restraint, not a total ban; use rhetoric only where it works. Use suspense (「ここには〜が潜んでいる」) or rhetorical questions to dramatize a derivation only where the tension aids the argument; where explanation suffices, just state it. Do not overuse the device of isolating a short punchline into its own paragraph for tension. A short 体言止め within a paragraph (「ここまでわずか数十秒。」) is allowed only at a climax. Do not overuse bold in body text; limit to logical crux points (misreading-preventing negations, section conclusions), one or two per section, intro allowed. Otherwise let sentence order and structure do the emphasizing. Prefer the worker-judgment form (「〜するわけにはいかない」) over the imperative assertion (「〜してはならない」). Do not over-dramatize turning points; one factual sentence usually suffices. Only at an argument's climax, a short sentence with an exclamation mark is tolerable. Do not stoke fear of accidents or danger by enumerating consequences. Do not pre-announce a claim with「重要なのは〜である」; just state the claim. (A preface declaring the claim's form, like「標語として言い換えれば」, is fine.) Do not overuse the antithetical punchline「AではなくBだった」. Light supplements or evaluations may be added in parentheses. Do not use twisted idioms (「知識を体に入れる」) or metaphors whose referent is not uniquely determined (「報告の外側に世界が広がっている」); say it plainly with simple verbs (「身につく」「気付く機会が減る」). High value; after drafting, self-check against this. Using the book's own terms in argument is fine; the problem is empty decoration. Japanese phrase tokens are kept verbatim. Avoid announcement and summary padding:「重要なのは〜である」「本章では〜を扱う／探求する」「ここでは〜について見ていく」「まとめると」「要するに」(when only restating the prior line),「〜に他ならない」. Avoid the「正面から」family:「正面から扱う」「正面から回収する」「正面から見る／書く／立てる」— they declare stance instead of content. Avoid empty adjectives:「不可欠」「核心的」「鍵となる」「根本的な」(emphasis without explaining the claim),「多角的」「包括的」「総合的」(without saying what was examined how). Avoid empty verbs:「掘り下げる」「深掘りする」「言語化する」(ends without showing what was written how),「触れる」「言及する」(one-paragraph brush-off). Avoid connective templates:「〜において」「〜という側面から」「〜の観点から」(no new info),「さらに」「また」「加えて」in a row. Avoid weak hedges and praise:「〜と言えるだろう」「〜かもしれない」(only when weakening a claim groundlessly; keep for speculation, hypothesis, reader-doubt, or character-perception),「非常に」「極めて」「大いに」(empty intensifiers). Self-check examples: 本章では、〇〇の理論を正面から扱う 本章では、〇〇の理論を扱う 多角的に分析すると、重要なのは〜である 評価の核心は、正しさを誰が知っているかにある Do not restate the same claim in paraphrase; write each claim once. If adjacent sections state the same thing from different angles, their roles overlap; absorb one into the other into a single section. Do not re-summarize a scene right after depicting it; leave only a single interpretive sentence (「このような作業は、ほぼ完全に任せられる」). Combine parallel facts with the same logical role into one sentence; mark their logical status with the lead word (「当然、経理部の月次処理も顧客の支払いも〜」). Do not write intermediate steps the reader can supply. If a multi-sentence argument compresses to one sentence, keep only the one;「要するに」is allowed as a compression signal. Do not add sentences that exist only for connection or evaluation (「それ自体はよいことである」). Do not use imagined reader Q&A as rhetoric (posing a question and answering in one word); state the claim directly. Also avoid acting out the reader's reaction (「〜と感じたかもしれない。そのとおりである」); make concessions plainly in the body (「もちろん、処置そのものは開発者が決める問題ではない」). Do not frame a likely reader idea with meta scaffolding (「ここまでの話には自然な続きがある」「〜という発想である」); write the idea directly. A reader's question may stay as a question (「その保守も任せればよいのではないだろうか」). Do not write author-stance disclaimers (「本書もそれを否定しない」); state only the fact (「〜に書かせる場合が多い」). Make prose share context with the reader in the fewest steps; if it lands without unrolling every step, name the structure and assert it. Do not preemptively bring out concepts or document names not yet introduced in the body. Do not settle for weak hesitant predicates (「有効な対策であり」); state what is settled by in-text grounds strongly and concretely (「活用において必須であり」). Keep weak predicates that express genuine uncertainty, possibility, hypothesis, or reader-doubt; intentional softening for tone (「必須だと言ってもいい」) is allowed. Connectives that set rhythm (「しかし一方で」) are not counted as redundancy. Make headings specific enough to identify content: the question the section answers, or the object it treats. Do not use procedure-only headings (「例に戻す」「〜を読み直す」) or information-free headings. Do not make a heading a "punchline" that states the section's conclusion (avoid spoiling the payoff at the heading). A noun phrase naming the section's object is acceptable. Whether interrogative or declarative does not matter; what matters is that it points to the object or the reader's question. Choose whichever suits the body's tone. If an example may look contrived, do not hide it; pre-empt the reader's doubt and add brief grounds that it is realistically plausible. Ground it not in the author's assertion (「十分あり得る状況だ」) but in a general fact or common view the reader can recognize from experience (「この症状は珍しくないだろう」「〜という言い方もよく耳にする」). Do not smoothly write unconfirmed things as if confirmed. 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>

<long_form_structure> Patterns for book chapters, multi-part series, and other long-form pieces where the reader progresses across many sections. These operate above the single-article patterns and are language-neutral; when writing Japanese, also apply the japanese/prose_norms ruleset. They govern how a chapter opens, how examples grow, and how a chapter or a whole work closes.

Shape each chapter or installment as problem-then-solution

Introduction: make the conventional approach's failure concrete before naming the new approach. Show the scenario where the old method breaks (a realistic "works on my machine" or "the build fails on the new OS" situation) so the solution is felt as relief rather than asserted as superior.

Foundation: the core structure or theory of the new approach.

Migration: how to move from the old approach to the new one, shown as a side-by-side change of one concrete example.

Practice: a worked, realistic example.

Deep dive: the mechanism behind why it works.

Outlook: a bridge to the next chapter's higher demand.

Introduce the solution in three graded moves: what visibly changes ("it becomes this"), why it changes (the mechanism), then the essential value ("so, in effect"). Build credibility with one concrete, checkable fact (adoption status, a count of supported items, who authored it) rather than adjectives. Keep the introduction's problem framing tight (roughly 300-400 words); a longer intro delays the payoff and front-loads detail unrelated to the example to come. Grow code examples in stages rather than presenting one large block Minimal example: the smallest version that runs. Incremental complexity: add one axis at a time (an environment variable, then a hook, then a service), each as its own step. Integrated example: combine the pieces into one realistic configuration. Cap a single code block at what a reader can absorb in a few minutes (on the order of 50-70 lines); split anything longer. Frame each block: one or two sentences of lead-in before it, a two- or three-sentence takeaway after it, and defer the deeper "why" to the following subsection. Watch the prose-to-code balance. A section that is mostly code with thin narration is under-explained; when code exceeds roughly two-thirds of a section, add explanation or move some code to a later stage. Trim decorative shell or log output to the few lines that carry the point (a 40-line status dump where 5-10 lines matter is noise). Do not let example difficulty regress: the last example in a chapter should not be the simplest one. Evaluate and write closing sections (chapter endings and the final chapter) Name the specific technical elements the chapter taught, not a vague gesture at "what we covered". State what was achieved and which problem it solved. Point to concrete next actions and, at most, the single most important learning resource. Ends by handing off to the next chapter's demand ("the environment built here now faces a higher requirement"). The default for interior chapters. Ends a series by integrating all prior chapters. It must still name the individual results, not only assert a "culmination". A closing section is short (about half a page, ~600 words across 3-4 paragraphs). Under-length is as much a defect as over-length: a final chapter that claims to integrate everything but omits the individual results is incomplete. Does it reference the chapter's actual sections and results, not just its title? Is there a single message focus rather than several competing ones? Is the ending type (bridging vs terminal) consistent with sibling chapters' endings? Reduce the bloat that accumulates across a long piece Merge duplicated messages: the same claim restated in three places (a feature's "everything is automated" line appearing across three consecutive subsections) collapses to one. Prune URL enumeration: cite the single most important link, not a list. Cut encouragement padding ("surely", "you should be able to ...") and re-summaries that immediately follow the thing they summarize. Define a central term before or at its first use within a section, and keep its meaning stable across chapters instead of reintroducing it with a shifted sense.

<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 For long-form pieces, frame the conventional approach's failure before introducing the solution, and escalate code examples from minimal to integrated See long_form_structure: chapter_arc and code_example_escalation </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>