こんにちは、小林です!
株式会社リンクアンドモチベーションでデータアナリスト兼データスチュワードをしています。普段はデータ分析業務をやりつつ、データ基盤の品質管理も推進しています。最近は Claude Code を自分好みにカスタマイズして開発ワークフローを整備することにハマっていて、めちゃくちゃ楽しいです!
それでは記事に入ります。
はじめに
- Claude Code の Skills 機能で、技術ブログ執筆のナレッジを SKILL.md に集約した（9本の参考記事を読み込ませて 370 行）
- 「AI は 80%、人間の熱量が残り 20%」を設計思想に据え、6 フェーズのワークフロー・12 カテゴリのレビュー観点・スタイルガイドシステムを組み込んだ
- Qiita CLI で投稿環境を構築し、この記事自体がその仕組みで書かれた最初の投稿
Claude Code の Skills とは
Claude Code には Skills という仕組みがある。~/.claude/skills/<name>/SKILL.md にドメイン知識やワークフローを Markdown で書いておくと、スラッシュコマンド（/skill-name）で呼び出せる。
ざっくり言うと「毎回プロンプトに書いていた指示を、再利用可能な形で保存できる」機能。
~/.claude/skills/
├── tech-writing/ # ← 今回作ったスキル
│ └── SKILL.md # 370 行の執筆ナレッジ
└── SKILL-MAP.md # 全スキルの索引
親スキル + 子スキルの構造で関連するスキルをグループ化もできる。今回の tech-writing は単独スキルだが、たとえばデータガバナンス系のスキルを 5 つ作って親ルーターでまとめる、といった使い方もできる。
なぜ tech-writing スキルを作ったのか
AI を使って技術記事を書くとき、一般的にこういう問題が起きる:
- 「構成どうしよう」で 30 分悩む
- AI に下書きさせたら AI 臭い文章が出てくる
- レビュー観点が毎回バラバラで、公開後に表記揺れを見つける
- Zenn / Qiita / note でフォーマットが微妙に違って混乱する
要するに「型がない」。型があれば AI の出力品質は安定するし、自分の判断リソースを本質的な部分に使える。
で、自分の場合はもっと手前の問題があった。そもそも「書こう」という思考にならない。ネタはあるのに、構成を考えて、下書きして、推敲して、フォーマットを整えて...と想像した時点で「まあ今度でいいか」になる。書く労力がデカすぎて、アウトプットの習慣が育たない。
型を作れば書くハードルが下がる。ハードルが下がれば書く頻度が上がる。頻度が上がれば型も育つ。このサイクルを回したかった。
参考記事から何を抽出したか
9 本の参考記事を Claude Code の WebFetch で取得し、既存の SKILL.md と統合してリライトした。
全記事を並列で取得して統合、という流れ:
1. 「この記事のどの知見をスキルに組み込むべきか」を考える
2. URL を渡す（9本まとめて）
3. Claude Code が WebFetch で並列取得・分析
4. 既存 SKILL.md と統合してリライト
5. 差分を確認して微調整
各記事から抽出した知見はこうだ:
| 参考元 | 抽出した知見 | スキルへの反映箇所 |
|---|---|---|
| SIOS | 4 エージェント分業の構想と「AI 80%, 人間 20%」の哲学 | 1. Philosophy |
| ZOZO テックブログ | 3 年分のレビューナレッジを 12 カテゴリに凝縮。表記統一・受動態/能動態・主語述語・助詞・漢字ひらがな・語順の 6 つの言語観点が特に実践的 | 3. 12 Category Review |
| Spacemarket | スタイルガイドを 12 種定義し、記事ごとに参照・自動更新する仕組み | 4. Style Guide System |
| endo-ly | Zenn + Qiita のクロス投稿パイプライン。GitHub Actions で CI/CD 化 | Platform Publishing |
残りの 5 本からは、各フェーズの詳細やプラットフォーム別の記法差分を補強した。
スキルの中身: 4 つの柱
完成した SKILL.md は 370 行。以下の 4 つの柱で構成されている。
1. Philosophy — 「AI は 80%、人間が 20%」
SIOS の記事から得た、スキル全体の設計思想:
- AI は 80%、人間の熱量が残り 20% — 構成・下書き・校正は AI。「なぜ書きたいか」は人間にしか入れられない
- きれいすぎる文章は読まれない — AI の文章は整いすぎる。自分のリズムを注入しないと閉じられる
- 結論を最初に — 読者は最初の 200 文字で読むか決める
- コードは動くことが最低条件 — 動かないスニペットは信用を破壊する
これがスキルの 冒頭に置いてある。Philosophy が最初に来ることで、AI が下書きを生成する段階から「きれいすぎない文章」を意識してくれる。
2. AI-Assisted Writing Workflow — 6 フェーズ
Theme & Interview → Outline → Draft → Human Heat → Review → Publish
ここがミソなのは Phase 4: Human Heat を明示的にフェーズとして定義していること。これは参考記事にあった概念ではなく、SIOS の「AI 80%, 人間 20%」の哲学をワークフローに落とし込むときに自分で作った造語だ。AI の出力に人間の熱量を注入するフェーズを、名前をつけて強制的にプロセスに組み込んだ。
AI が書いた下書きに対して:
- 自分の感想を追加 — 「正直これは驚いた」「最初は全然わからなかった」
- 失敗談を入れる — 完璧な解説より失敗→解決のストーリーが刺さる
- 口語的なリズムを入れる — 「で、何が起きたかというと」「ここがミソなんだけど」
- AI 臭を消す — 「まとめると」「以上のことから」を自分の言葉に置き換え
Phase 1 では Article Brief テンプレートを使って、書く前に「読者の痛み」と「差別化ポイント」を言語化する。これがないと技術列挙型の記事になる。
## Article Brief
- One-line summary: [一文で言うと？]
- Target reader: [誰に？前提知識レベルも]
- Reader's pain: [読者の課題・疑問]
- Key takeaway: [読後に得るもの]
- Unique angle: [既存記事との差別化]
3. 12 Category Review — ZOZO の 3 年分のナレッジ
ZOZO テックブログの記事から抽出した、12 カテゴリのレビュー観点。これが一番実践的で再利用性が高い。
言語・表現（6 カテゴリ）:
| # | カテゴリ | チェック内容 |
|---|---|---|
| 1 | 表記統一 | Web/web、サーバー/サーバ などのブレ |
| 2 | 受動態/能動態 | 不必要な受動態がないか |
| 3 | 主語-述語 | 長文で主述がねじれていないか |
| 4 | 助詞 | 「は/が」「で/に」の使い分け |
| 5 | 漢字/ひらがな | 開く漢字（出来る→できる、事→こと） |
| 6 | 語順/修飾 | 修飾語と被修飾語が離れすぎていないか |
構造・フォーマット（4 カテゴリ）:
| # | カテゴリ | チェック内容 |
|---|---|---|
| 7 | 見出し構造 | h2 > h3 の階層飛び、見出しだけで流れがわかるか |
| 8 | 記号/装飾 | 太字使いすぎ、箇条書き粒度の不統一 |
| 9 | 固有名詞 | GitHub/Github、TypeScript/Typescript の綴り |
| 10 | プラットフォーム記法 | Zenn :::message / Qiita :::note の使い分け |
内容・コンプライアンス（2 カテゴリ）:
| # | カテゴリ | チェック内容 |
|---|---|---|
| 11 | リンク/参照 | リンク切れ、引用元、localhost リンク混入 |
| 12 | 機密/権利 | 社内情報漏洩、著作権、将来予定の断定 |
各指摘には Severity Level（Must Fix / Should Fix / Consider）を付与する。事実誤認やコードエラーは Must Fix、表記不統一は Should Fix、語順の微調整は Consider。
4. Style Guide System — 自分の文体を定義する
spacemarket の記事から着想を得た仕組み。自分の過去記事から文体要素を抽出し、ガイドとして定義する。
| 要素 | 定義内容 | 例 |
|---|---|---|
| Greeting | 冒頭の挨拶 | 「XX チームの○○です。」 |
| Tone | 文体基調 | です・ます基調、技術解説は体言止め可 |
| Endings | 文末パターン | 「〜しました」の偏り回避 |
| Emphasis | 強調の使い方 |
太字 = 重要概念、code = 技術用語 |
| Humor | ユーモアの方向 | 自虐 OK、他者揶揄 NG |
| Closing | 締めくくり | 独自フレーズ or 定番 |
| Phrases | 口癖集 | 「ここがミソ」「で、何が起きたかというと」 |
記事が増えるほどガイドも成熟する。最初は粗くていい。AI に過去記事を読ませてパターン抽出し、ガイドに反映→次の記事で参照→また更新、のサイクルを回す。
Qiita CLI セットアップ
スキルを作ったら、実際に記事を書いて投稿する環境も整える。
インストールと初期設定
mkdir -p ~/qiita && cd ~/qiita
npm init --yes
npm install @qiita/qiita-cli
npx qiita init
トークンは Qiita トークン発行ページ で read_qiita + write_qiita スコープで発行。
npx qiita login はインタラクティブ入力を要求するため、パイプやリダイレクトでトークンを渡せない。~/.config/qiita-cli/credentials.json に直接書き込む方が確実。
{
"default": "default",
"credentials": [
{
"name": "default",
"accessToken": "your-token-here"
}
]
}
最大の注意点: 下書き API は存在しない
ここは声を大にして言いたい。Qiita API v2 には下書き保存の API がない。
draft: true をリクエストボディに入れても無視されて即公開される。つまり npx qiita publish を叩いた瞬間、記事は世に出る。「下書きに入れといて」は CLI からはできない。
実際にやらかした。Claude Code に「一旦これで」と設定の話をしたら、投稿の承認と解釈されてそのまま publish された。レビュー中の未完成記事が公開されてしまい、慌てて API で削除する羽目になった。
対策として決めたルール:
- Claude Code からの publish は「投稿して」「公開して」と明示的に指示した場合のみ
- 曖昧な返答（「OK」「一旦これで」等）では publish しない
- 迷ったら確認を挟む
下書きは Web UI でのみ管理可能。CLI ワークフローに下書きフェーズを組み込みたい場合は、ローカルで書く → プレビューで確認 → 明示的に publish、という運用になる。
基本ワークフロー
npx qiita new my-article # 新規記事作成（public/ に .md 生成）
npx qiita preview # プレビュー（localhost:8888）
npx qiita publish my-article # 公開（即公開、下書きなし）
npx qiita pull # Qiita から最新を取得
まとめ
- Skills は「プロンプトのナレッジ化」 — 参考記事を読み込ませてリライトするプロセスで、370 行の実践的なスキルが 1 セッションで作れた
- 12 Category Review が一番効いている — レビュー観点が固定されたことで、公開後の「あ、ここ表記揺れてる」が激減する
- Human Heat フェーズの明示化 — AI に任せる部分と人間が入れる部分の境界が明確になったことで、「AI 臭い記事」を避けられるようになった
-
Qiita CLI は下書き API がない点だけ注意 — それ以外は
new→ 書く →publishの 3 ステップで投稿できて快適
型と環境が揃ったので、あとは書くだけ。この記事を皮切りに、実装したこと・学んだことをどんどんアウトプットしていく。