| name | opinionated-tech-writing |
| description | Thariq（@trq212）流の主張駆動型・実体験ベースのテクニカルライティングで技術記事を書くためのスキル。「Hill I will die on（譲れない原則）」を冒頭に置き、Whyを徹底的に深掘りし、自分の実例とNext Stepで読者を即行動させる構造を生成する。Use this skill whenever the user wants to write a technical article, blog post, Zenn記事, X/Twitterスレッド, または「強い主張で読者を引き込みたい」「Whyを深く伝えたい」「Thariqみたいに書きたい」「主張駆動」「Hill I will die on」「opinionated」というニュアンスを含むとき。既存のzenn-article-writerが課題解決ナラティブ型なのに対し、このスキルは『譲れない原則を主張する』スタイルに特化する。記事テーマが固まっていない段階の壁打ちにも使える（タイトル案・冒頭文案・構成案を出す）。 |
Opinionated Tech Writing — 主張駆動型テクニカルライティング
このスキルは、Thariq Shihipar（@trq212）氏のテクニカルライティング・スタイルを再現するためのものです。
このスキルが目指すもの
「技術を伝える」のではなく、読者が自分で再現できる「思考の型」を渡す。
抽象論を避け、自分の失敗・実例・Whyの深掘り・即行動可能なNext Stepを組み合わせて、読後すぐに「試してみよう」と思わせる記事を書く。
いつ使うか
- 技術記事を新規に書くとき（特にZenn / X / 個人ブログ）
- 既存記事の冒頭・構成が「弱い」と感じたとき
- 「ただの紹介記事」になっていて熱量が出ないとき
- まだテーマだけあって、どう書くか迷っているとき（壁打ち）
いつ使わないか
- 公式ドキュメント・APIリファレンスのように主観を排した中立記述が必要なとき
- チュートリアル系で「個人の主張」が邪魔になるとき
- 既存の
zenn-article-writer の方が合うとき（純粋な課題解決ナラティブで、主張要素が不要なとき）
核心の7原則（最重要）
詳細は references/principles.md を参照。ここでは要点だけ：
1. Hill I will die on（譲れない原則）から始める
- 冒頭1文に強い主張を置く。例：「RAGはもう死んだ。File Systemを使え」
- 抽象論ではなく、「私が実際に死ぬほど信じている」という個人の熱量を最初に出す
- 「○○について解説します」のような中立タイトルは避ける
2. Why を徹底的に深掘りする
- 読者が一番欲しいのは How ではなく 「なぜこのアプローチが優れているのか」
- 自分の失敗体験、他手法との比較、実数値（「コンテキスト使用量が40%減った」）で裏付ける
- How だけの記事は流し読みされる。Why が刺さる記事は保存される
3. 自分の実例から書く（再現性の源）
- 「私の◯◯では実際にこうやった」を必ず入れる
- スクリーンショット・コード実行結果の画像を多用
- 実例がまだ少ないなら「今試している最中」と正直に書く方が信頼される
4. 1セクション1アイデアの構造
- スレッド・記事問わず、1ポスト＝1主張
- 箇条書き・番号・太字・画像を多用
- 用途別にラベリングする（例：「Chaining API Calls」「Video Editing」）
5. 読者の Next Step を明示する
- 記事末に必ず「今すぐ試せる行動」を1つ書く
- 「Claude Agent SDKでこう実装できる」「このリポジトリをcloneして」など
- 読後の沈黙ではなく、行動を促す
6. 人間味と専門性の両立
- 「I put a lot of heart into...」のように感情を入れる
- でも内容は低レベル詳細まで踏み込む
- 「この人は実際に作ってる」と感じさせる信頼感が決め手
7. メタ技法も惜しまず公開する
- 自分のワークフロー（Spec駆動執筆、AskUserQuestion 40問インタビューなど）を出す
- 記事を書くプロセスそのものが、再現可能なフレームワークになる
推奨する記事の構造テンプレート
1. タイトル（強い主張を含む）
2. 冒頭1文（Hill I will die on）
3. 問題提起（多くの人が抱える課題への共感）
4. Why の深掘り（失敗談 + 比較 + 数値）
5. How（具体的なやり方）
6. 実例・画像・コード（自分のプロダクト or 学習中のもの）
7. 注意点・落とし穴（正直に）
8. Next Step（読者が今すぐ試せる行動）
詳細なテンプレートは assets/article-template.md にあります。
執筆プロセス（Specベース）
Thariq氏自身が公開している執筆ワークフローを応用：
- Spec を先に書く — 「この記事で伝えたいこと」を箇条書きで20〜40個出す（読者像も明確に）
- 下書きは話すように書く — 推敲は後で。熱量を逃さない
- 「これ本当に死ぬほど信じてるか？」と自問 — 信じきれない主張は削る
- 専門用語は最小限 — 使うなら必ず1行で説明
- 長くなりすぎたら分割 — スレッドや連載にする勇気
詳細なワークフローと Spec テンプレートは:
references/spec-workflow.mdassets/spec-template.md
執筆スタイル（細部）
文体
- 能動態を基本にする（「〜される」ではなく「〜する」）
- 一文一義：1つの文に複数のアイデアを詰めない
- 丁寧語と口語の混在：日本語では「です・ます」で書きつつ、要所で口語を混ぜると親しみが出る（例：「これマジで効きます」「正直、最初は半信半疑だった」）
主張の出し方
-
❌ 「〜が便利だと言われています」（伝聞・弱い）
-
✅ 「〜は3ヶ月使ってみて、もう手放せない」（一人称・実体験）
-
❌ 「〜は良い選択肢の一つです」（中立・印象に残らない）
-
✅ 「〜以外を選ぶ理由が、もう思いつかない」（強い主張・記憶に残る）
数値と固有名詞
- 「だいぶ速くなる」ではなく「3.2倍速くなった（手元計測）」
- 「他のツールより」ではなく「LangGraph と比べて」と固有名詞を出す
- 数値が無ければ正直に「体感では明らかに速い」と書く方がマシ
既存スキルとの使い分け
| スキル | 軸 | こんな記事に使う |
|---|
zenn-article-writer | 課題解決ナラティブ | 「困った→解決した」を整理して伝えたい |
opinionated-tech-writing（このスキル） | 譲れない主張 | 「これだけは伝えたい」という熱量がある |
両方を組み合わせるのもアリ。例：構造は zenn-article-writer の課題解決型、冒頭の主張と Why の深掘りは本スキルから。
出力の質を担保するチェックリスト
記事を書き終えたら、以下を全て確認：
アウトプット形式
ユーザーから「Xについて記事を書きたい」と相談されたら、まず以下を提示する：
- タイトル案（3つ程度、それぞれ違うトーン：強硬・中庸・謙虚）
- 冒頭1文の案（Hill I will die on 形式で）
- 記事構成のドラフト（上記7段構造に当てはめる）
- Spec の最初の10項目（伝えたいことの箇条書き）
ここでユーザーから承認・修正を受けてから本文執筆に入る。
補足リソース
references/principles.md — 7原則の詳細と、悪い例 vs 良い例の対比集references/spec-workflow.md — Specベース執筆の進め方assets/article-template.md — Zenn frontmatter込みの記事スタートテンプレートassets/spec-template.md — 執筆前に埋める Spec テンプレート
最後に
Thariq氏の言葉を借りれば — 「心を込めて」書くことが一番大事。
完璧を目指さず、「これを困っている誰かに届けたい」という気持ちで書き始めれば、自然に良い記事になる。このスキルは、その気持ちを 構造として再現可能にする ための補助輪です。
