わたしっぽいブログ記事執筆 Skill

わたしっぽいブログ記事執筆

技術情報を正確に伝えながら、読者と共感し、親しみやすさを保ち、明確な価値観を持つ独特のスタイルで技術ブログ記事を執筆する。

基本方針

AI生成文章特有の「臭さ」を排除し、筆者の個性と価値観が宿る人間味のある文章を実現する。

詳細なガイドラインは、以下のリファレンスを必要に応じて読み込む。

voice-and-tone.md: 文体とトーン(話し言葉、一人称、問いかけ、接続詞、避けるべき表現)
writing-guidelines.md: 構造と表現(見出し、導入部、結論部、対比、メタファー、一次ソース、MECE と文末表現)
markdown-conventions.md: Markdown 記法(コードブロック、画像 alt、>[!CAUTION] と textlint 回避、サンプルコードの品質)
ai-police-checklist.md: AI臭さ排除の詳細チェック項目

frontmatter の生成範囲

このスキルが生成する frontmatter は、以下のフィールドのみに限定する。

---
title: 記事タイトル
slug: url-slug-in-kebab-case
date: YYYY-MM-DD
modified_time: YYYY-MM-DD
description: 記事の説明文(1〜2文)
icon:
icon_url:
tags:
  - タグ1
  - タグ2
---

selfAssessment(クイズ)と diagram は生成しない。これらは別途追加してもらう方針のため、含めないこと。

執筆ワークフロー

Step 1: 記事構成を決定する

すべての記事を、以下の4段階構成に従って組み立てる。

1. 導入(背景説明)
   ↓ 自分自身の経験や現実の課題から始まる
2. 問題提起
   ↓ 解決すべき技術的課題を明確化
3. 解決策の詳細
   ↓ 実装コード例付きで具体的に説明
4. まとめ
   ↓ 学習ポイントをリストアップ

Step 2: 導入部を執筆する

「## はじめに」のような導入専用の見出しは設けない。冒頭は見出しなしの本文から始め、以下のいずれかのパターンを選択して導入する。

パターンA: 自分の経験から始まる

私は過去プロジェクトのコードを流用していました。
Playwrightを使う際、動いていたテストコードをコピーして、今回のプロジェクト用に少し修正して使用します。

パターンB: 具体例から始まる

皆さんは、Google 製の IDE である「Antigravity」を使っていますか？
これは VS Code をフォークした AI エディタの 1 つです。

パターンC: 時代背景→一般課題→自分の経験の3段構成(推奨)

いきなり自分の話に入らず、読者が「わかる」と思える文脈を先に置く。技術の時代的な背景(読者の共通認識)→ そこにある一般的な課題 → 自分も同じだった、という順番で共感の土台を作ってから本題に入る。導入部の最後で記事全体の結論(何をどう解決したか)を先出しし、読者が「この記事を読む価値があるか」を冒頭で判断できるようにする。

GitHub Actions は 2018 年に発表されて以来、ビルド・テスト・デプロイの自動化を担ってきました。
YAMLで決定論的なステップを定義するしくみは強力ですが、「ログを解析して原因を推論し、判断して対処する」というタスクは苦手です。

(中略：一般的な課題を述べる)

私が運用するリポジトリでも同じ問題を抱えていました。

Cloudflare は従来の Pages ではなく Workers を推奨する方針を打ち出しています。(時代背景)

しかし、Workers のプレビューバージョンには構造的な課題があります。(一般課題)

このブログも Cloudflare Workers でホスティングしており、同じ課題に直面しました。(自分の経験)
調査の結果 Beta API に DELETE エンドポイントがあることが分かり、GitHub Actions で自動クリーンアップするしくみを実装しました。(結論の先出し)

パターンAやBで始める場合でも、導入部の最後に「この記事で何を解決するか」の1文を入れる。

Step 3: 本文を執筆する

以下の技法を適用する。

段階的な説明

locatorは「要素を特定するだけのしくみ」ではなく、要素が操作可能になるまで待つしくみを備えています。
これらのチェックがすべてパスしない限り、指定されたタイムアウト時間内で自動的にリトライを繰り返します。

対比による説明(NG例とOK例)

// NG
const navigationPromise = page.waitForNavigation();
await page.click('button');
await navigationPromise;

// OK
await page.click('button');
await page.waitForURL('**/next-page');

メタファーの活用(無理に入れない)

読者が「なるほど」と思える身近な例えがあれば使う。ただし、無理にひねり出したメタファーは意味不明になるので入れない方がよい。自然に思いつかなければ省略する。

まず概要を把握し、メンタルモデルを作ってから本を読む。
そうすることで、「どんな内容が書かれているのか」が分かった状態で読み進めることができ、結果としてスムーズに理解できます。

読者の疑問を先回りする問いかけ

技術的な事実を述べた直後に、読者が抱くであろう疑問を地の文で直接拾い、即座に回答する。「説明文」ではなく「対話」のリズムを作る技法。ただし「読者がここで何を疑問に思うか」のようなメタ的な説明を地の文に書かないこと。疑問→回答をそのまま書く。

`permissions` はすべて `read` のみです。エージェントに write 権限を与えません。
「read しかないのにどうやって PR を作るのか」という疑問が浮かびますが、
エージェントは「PR を作りたい」というリクエストを記録するだけです。

脚注による知識レベル差の吸収

初出の専門用語・略語には脚注 ([^用語]) を検討する。本文の流れは壊さず、知らない読者は脚注で補える二層構造にする。「この単語を知らない読者が読んだらどう感じるか」を基準にする。

脚注の定義([^用語]: 説明)は本文中に書かず、記事の一番下(「## 参考」の下)にまとめて配置する。

本文中:
GitHub はこれを「Continuous AI」と呼んでいます。CI/CD[^cicd] が「ものを作る作業」を自動化するように、
Continuous AI は「問題を調べて対応する作業」を AI で自動化します。

記事末尾にまとめて:
[^cicd]: Continuous Integration / Continuous Delivery の略。コードをプッシュするたびに自動でビルド・テスト・デプロイを実行する開発手法。

Step 4: まとめ部を執筆する

箇条書きによる学習ポイント

## まとめ

- 過去のコードを流用することは効率的で合理的な判断だが、「動く」と「正しく動く」の間には設計思想の違いがある
- `page.evaluate()` は動作するが、要素の操作可能性を確認しないため不安定なテストにつながる可能性がある
- 公式ドキュメントには「なぜこの方法が推奨されるのか」という設計思想が書かれており、単なるAPIリファレンス以上の価値がある

反省や今後の展望

スマートフォンからやるよりも、結局PCからやったほうがよいってことになった時点で、最初から設計や概念的な部分をちゃんと実装できていなかったことは反省です。

Step 5: 参考資料を追加する

すべての記事の最後に「参考」セクションを設置する。本文中のインラインリンクは [テキスト](URL) 形式で書き、参考セクションのURLは裸貼りで記載する。

## 参考

https://playwright.dev/docs/evaluating

https://playwright.dev/docs/locators

[^cicd]: Continuous Integration / Continuous Delivery の略。

Step 6: AI臭さ排除チェックを実行する

最終チェックリストを以下の手順で実行する(詳細は ai-police-checklist.md を読み込んで確認する)。

文体・表記

[ ] Markdown記法の残留なし
[ ] 日本語文末の「:」(コロン)なし
[ ] 機械的な誘導(「詳しくはこちら👉」)なし
[ ] 適切な型定義(TypeScriptの場合)
[ ] 箇条書きで「xxx ... 説明」「項目: 説明」「項目 → 説明」のような区切り形式を使っていないか(AI臭い)
[ ] 二重否定で読みづらくなっていないか
[ ] 話し言葉(「〜ですよね」「〜でしょう」等)を無条件に入れていないか。前後の文脈に合う場合のみ使用する
[ ] ——(全角ダッシュ2つ)を使っていないか。読点・句点・接続詞で代替する

導入部の情報設計

[ ] 導入部が「自分の話」だけで始まっていないか。時代背景や一般的な事実 → 一般課題 → 自分の経験の順になっているか(パターンC推奨)
[ ] 導入部の最後に記事全体の結論(何をどう解決したか)が先出しされているか

脚注と用語説明

[ ] 記事テーマに固有の専門用語に脚注([^用語])が付いているか。「この単語を知らない読者が読んだらどう感じるか」の視点で全体を1周チェック
[ ] 略語(API名、ツール名など)で読者層によっては馴染みがないものに脚注を検討したか

一次情報とエビデンス

[ ] 人の発言を引用している場合、発言元(X、ブログ記事など)の直接URLが貼られているか
[ ] 「〜できる」「〜がある」という事実主張に、裏付けとなる公式ドキュメントへのリンクが本文中にinlineで貼られているか(参考セクションだけでは不足)
[ ] 公式ドキュメントへのリンク
[ ] 個人的な経験・動機の記述
[ ] 自分の価値観の表明

Step 7: 検証と修正を反復する

Step 6 のチェックリストで問題が見つかった場合、以下のループを実行する。

該当箇所を特定する
references/voice-and-tone.md または references/ai-police-checklist.md を参照する
修正を適用する
再度チェックリストを実行する

このフィードバックループを、すべての項目がパスするまで繰り返す。

Error Handling

導入部が「自分の話」だけで始まってしまった場合: references/writing-guidelines.md の「導入部の書き方」を読み、パターンCの3段構成(時代背景 → 一般課題 → 自分の経験)に書き直す。
AI臭さチェックリストで違反が見つかった場合: 該当する違反種別ごとに references/ai-police-checklist.md の対応セクション(Markdown記法の残留 / 不自然な文末記号 / 機械的な誘導 / 箇条書きの区切り形式 / 型定義がない)を読み、NG例とOK例の対比に従って修正する。
「## はじめに」のような導入専用見出しを書いてしまった場合: 見出しを削除し、本文から直接始める形に直す。
frontmatter に selfAssessment や diagram を含めてしまった場合: 該当フィールドを削除する。これらは別途追加される設計のため、このスキルの責務外。
箇条書きで「項目 ... 説明」「項目: 説明」「項目 → 説明」の区切り形式を使ってしまった場合: 項目と説明を自然な日本語の文として接続し直す。
倒置法・体言止めが残っている場合: references/voice-and-tone.md の「避けるべき表現」を読み、通常の語順(順序法)と述語(動詞・形容詞)+「です/ます」の閉じに直す。
事実主張に裏付けリンクが無い場合: 該当箇所に公式ドキュメントへの inline リンク([テキスト](URL) 形式)を追加する。参考セクションへの集約だけで済ませない。

Agent Skills: わたしっぽいブログ記事執筆

Install this agent skill to your local

Skill Files