| name | article-polish |
| description | hira.page リポジトリのブログ記事 (src/blog/ja/{slug}/index.mdx) の本文を、ユーザーの文体・SEO 観点で清書する。Web 調査による出典補強・引用カードの挿入・仮画像パスの提案も行う。「記事を整えて」「記事を仕上げて」「記事清書」などと言われたとき、または対象 mdx を開いた状態で清書依頼をしたときに起動する。frontmatter はdescriptionのみ、あとは本文のみを対象に、チャット内で全文提示 → レビュー → OK 検知で自動反映する。 |
記事清書スキル
hira.page の 日本語ブログ記事 (src/blog/ja/{slug}/index.mdx) の本文を、雑な下書きや音声入力から、ユーザーの文体・SEO 観点で清書する。
frontmatter はdescriptionのみ編集。あとは本文のみが対象。
起動条件
以下のいずれかで起動する:
- ユーザーが「記事を整えて」「記事を仕上げて」「記事清書」「記事をしあげて」「清書して」などと発言
- 対象 mdx を VS Code で開いた状態で、清書系の依頼があったとき
- 「この記事を読みやすく」「文体に合わせて整えて」など、明確に清書を意図した依頼
- 「リファレンス足して」「出典つけて」「ソースを補強して」など、引用・出典補強の依頼があったとき (清書フルではなく出典補強だけのモードもサポート)
ただし「文章を翻訳して」「英訳して」のような翻訳依頼は translation-check スキルの担当。混同しないこと。
対象ファイルの特定
清書はファイル単位。対象ファイルが確定するまで清書作業に入らない。
判定順:
<ide_opened_file> タグで src/blog/{ja|en|zh-cn}/{slug}/index.mdx のような MDX が開かれている → それを対象- ユーザーが
blog/{slug} の形式でパス指定してきた → src/blog/ja/{slug}/index.mdx を対象
- 上記いずれも該当しない → ユーザーに「どの記事を清書しますか?
blog/{slug} の形式で指定してください」と聞く
注意: 現状このスキルは ja のみ対応。en / zh-cn の MDX が開かれている場合は「このスキルは ja 版のみ対応です。en / zh-cn は translation-check スキルで翻訳してください」と案内する。
入力ソース
清書のもとになる下書きは、以下のいずれか:
- 対象ファイルの本文 (2つめの
--- 以降) に書かれている
- ユーザーがチャットに下書きを貼り付けている
- 両方ある場合は両方を統合する (ファイル本文を骨格に、チャットの追加内容を反映)
ファイルが空 (テンプレートのまま) で、チャットにも下書きが無い場合は「下書きをチャットに貼るか、対象ファイルに書いてから再度依頼してください」と案内する。
清書のルール (必ず守る制約)
1. frontmatter は descriptionのみ変更
- 先頭
--- から 2 つめの --- まで はほぼそのまま保持
description だけ生成- もしユーザーから明示的に「title も提案して」と言われた場合のみ、別の作業として扱う (このスキルの責任範囲外)
2. import 文・コード・URL・パスは保持
import EmbedCard from '@/components/Blog/EmbedCard.astro'; などの import 文 → そのまま- コードブロック (
``` で囲まれた範囲) → 中身を変更しない
- インラインコード
`...` → 中身を変更しない
- URL・ファイルパス・画像参照 (
./cover.png 等) → 変更しない
3. MDX コンポーネントの構造は保持
<EmbedCard ... /> <details> <small> <iframe> 等はタグ構造を保持- 可視テキスト属性 (
title= の中身など) は、原文を尊重しつつ自然な日本語に整える程度
- コンポーネントを勝手に増やしたり、別の表現に書き換えたりしない (ただし下書きに「ここにカードを入れて」のような指示があれば追加 OK)
4. 既存構造の保持
- 脚注・table・定義リスト等は構造保持
- 内部リンク (
/blog/...) は変えない
Web 調査と引用の反映
清書の目的の半分は「リファレンス・出典・引用の整備」。雑な下書きにある主張・固有名詞・製品名・技術用語に対して、適切に Web を調べて出典を補強する。
いつ調べるか
以下の場合に WebSearch / WebFetch を使う:
- 下書きに 具体的な製品名・サービス名・技術名・人名 が出てきて、公式リンクや関連記事カードを添えると親切なとき (例: 「Switchbot 空気清浄機」「Material Design 3」「Tailwind CSS」)
- 下書きの主張に 裏付けが必要 なとき (統計・歴史・仕様など)
- ユーザーが「最新情報を踏まえて」「ソース付けて」「リファレンス補強して」と明示したとき
- 古い情報の可能性があるとき (バージョン番号・リリース年など) → 最新版を確認
いつ調べないか
- 個人的な感想・体験談・主観的な記述 (検証しようがないし不要)
- ユーザーが「調査不要」「Web 検索しないで」と明示したとき
どう反映するか
調査結果は以下のいずれかで本文に組み込む:
- インラインリンク:
[テキスト](URL) — 文中の固有名詞や軽い参照
<EmbedCard>: 重要な参照記事・公式ページ・商品ページ。直前・直後に短い説明文を添える- 引用ブロック + 出典: 外部の主張・データを短く引用する場合
- 脚注: 補足的なリファレンス
- 章末の参考リスト: その章に関わる関連記事をまとめる場合
詳細な書式は style-guide.md の「リンク・引用・出典」章を参照。
調査の質を担保するルール
- 事実をでっち上げない: 検索で確信が持てなければリンクを足さず、本文だけ整える
- URL は実在を確認する: WebFetch でアクセスできることを確認したものだけ採用 (404 リンクは絶対に書かない)
- 古い情報源は避ける: 技術記事は特に、可能なら直近 2 年以内の情報を優先
- 公式 > 一次情報 > 二次情報の優先順位: 公式ドキュメント・公式サイトを最優先。次に開発者ブログや一次取材記事。最後に解説記事
- EmbedCard の
img は OGP 画像を使う: WebFetch で取得したページの <meta property="og:image"> 値を使うのが理想。確実な URL が取れないときは EmbedCard を使わずインラインリンクに留める
- 引用は短く: 著作権配慮として原文の長い段落をそのまま引用しない
出典補強だけのモード
ユーザーが「出典だけ足して」「リファレンス整備だけして」と言った場合は、本文を大きく書き換えず、リンク・カード・脚注を追加するだけに留める。
画像・メディアのプレースホルダ
下書きに画像指定がなくても、清書時に 「ここに画像があるとよい」箇所を見つけて仮の画像パスを提案 する。src/blog/ja/sample/index.mdx の記法を踏襲する。
仮画像パスのルール
- ファイル名は kebab-case で内容を示す:
./dynamic-color.gif, ./switchbot-air-purifier.jpg
- alt テキストには内容説明を必ず書く (
画像 のような無意味な alt は禁止)
- 直前または直後に MDX コメントで どんな画像が必要かを明示:
{/* TODO: ダッシュボードのスクショ。比較表が見える状態で */}
- 既に置かれている画像 (
cover.png, thumbnail.png, 既存記事の画像) は触らない・パスを変えない
- 動画プレースホルダは
<video src="/video/{slug}-{name}.mp4" controls /> と書き、TODO コメントで内容説明
- 仮画像の実ファイル配置は書き込みフェーズ (Step 10) で自動的に行われる。SKILL が
src/_template/cover.png をコピー&リネームして実ファイルを置くので、ビルドエラーは起きない
どこに仮画像を提案するか
- 章タイトル直下 (h2 の直後) で、その章のキー視覚要素になるところ
- 比較・並列の説明があるところ
- UI・画面の説明があるところ (スクショ前提)
- 商品紹介・サービス紹介の各項目
ただし過剰に挿入しない。読み物として図が必要な箇所だけ。1段落おきに画像があるのは多すぎ。
画像をいくつ挿入するか
- 短い記事 (1000 字以下): 0〜2 枚
- 中規模 (1000〜3000 字): 2〜5 枚
- 長文 (3000 字超): 5〜10 枚
既存画像の扱い
下書きに  のような既存パスが書かれている場合は、そのまま保持して中身を変えない。
詳細は style-guide.md の「画像」「動画・アニメーション」章を参照。
清書の方針 (SEO + 読み物としての完成度)
ユーザーの文体は style-guide.md に従う。清書を始める前に必ず style-guide.md を Read する。
SEO 観点
# (h1) は使わない (title が自動 h1)。本文の見出しは ## (h2) と ### (h3) を基本に- 見出しには記事の検索キーワードを自然に含める
- リード文 (冒頭 1 段落) で「誰が・何を・なぜ」を端的に提示
- 段落間に空行を必ず入れる
- 画像の alt を確認 (空なら埋める)
読み物としての完成度
- 結論先出し、または「導入 → 本論 → まとめ」の流れ
- 1 段落 2〜4 文を目安に改行
- 太字 (
**...**) を要所に。打ちすぎない (1 段落 2 つまで)
- リスト・引用・コード・カードで視覚的なリズムを作る
- 冗長な接続詞・語尾の連続を避ける
- AI翻訳調 (受け身の連続、「〜することができます」の多用) を避ける
内容面の補強
- 下書きが薄い箇所は、適切に肉付けして OK (ただし事実をでっち上げない)
- 下書きで省略されている説明・前提・具体例を補う
- 引き込まれる導入・読後感を意識した結び
実行フロー
スキル起動時は以下の順で動く。
Step 1: 対象ファイルの確定
<ide_opened_file> タグを確認 → 該当 MDX を対象に- 該当しなければユーザーに聞く
Step 2: 文体ガイドを読む
.claude/skills/article-polish/style-guide.md を Read。毎回必ず読む (キャッシュに頼らない)。
Step 3: 対象ファイルを読む & 既存仮画像の配置
- 対象
index.mdx を Read
- frontmatter (先頭
--- から 2 つめの --- まで) を保持しておく
- 2 つめの
--- 以降の本文と、ユーザーのチャット下書きを統合して清書のもとにする
- 本文中の相対パス画像 (
./xxx.png 等) を抽出し、実ファイルが存在しないものを src/_template/cover.png からコピー&リネームして即座に配置する (詳細手順は Step 10-1 参照)。これにより、清書中・レビュー中もビルドエラーが起きない状態を保つ。配置したファイル名はメモしておき、最終報告で示す。
Step 4: サンプル記事の参照 (必要時)
下書きのジャンルに応じて、style-guide.md 末尾の「参考記事サンプル」から 1〜2 本を Read してリズムを掴む。
- 技術・主張型 →
tailwind-react-styling-issues
- エッセイ・レビュー型 →
2024-best-buy
- 技術・解説型 →
material-design-3
- MDX記法に迷ったら →
sample
Step 5: Web 調査 (必要時)
下書きに調査価値のある製品名・サービス名・技術名・統計・引用源が含まれていれば WebSearch / WebFetch で調べる。
- 公式サイト・公式ドキュメントの URL を確認 (404 でないこと)
- 関連記事カード (
<EmbedCard>) に使う場合は OGP 画像 URL も取得 (<meta property="og:image">)
- ユーザーが「調査不要」と言っている場合はスキップ
調査結果は本文に組み込む際、何を / どこから引用したかをユーザーが追えるよう、清書版に明示する。
調査が 不要だと判断した場合、あるいは スキップした場合 は、提示時にその旨を 1 行添える (「Web 調査は今回不要と判断しました」など)。
Step 6: 清書版を作成
style-guide.md を踏まえて本文を清書する。frontmatter は含めず、import 文以降の本文全体を作る。Step 5 で調査した出典・カード・引用も自然に組み込む。画像が必要そうな箇所には仮パス + TODO コメントを入れる。
Step 7: チャット内に全文提示
清書版を以下のフォーマットで提示する:
📝 対象: `src/blog/ja/{slug}/index.mdx`
清書版です。
```mdx
import EmbedCard from '@/components/Blog/EmbedCard.astro';
## ...
...本文...
```
この内容で書き込んでよければ「OK」「反映して」などと言ってください。修正したい箇所があれば指示をどうぞ。
- コードブロックは
```mdx で囲む
- frontmatter は提示に含めない (毎回提示すると冗長なため)
- 全文を1つのコードブロックにまとめる (セクション分割しない)
Step 8: レビューループ
ユーザーから修正指示が来たら:
- 指示を反映して 再度全文をコードブロックで提示 (差分だけ示すのではなく、必ず全文)
- 「修正しました。これでどうでしょう?」と添える
- OK が出るまで繰り返す
Step 9: OK 検知と書き込み
ユーザーから以下のいずれかの言葉を検知したら、書き込みフェーズに入る:
- 「OK」「ok」「OK!」
- 「これで OK」「これでいい」「これで良い」「いいよ」「いいね」
- 「反映して」「適用して」「書き込んで」「保存して」「コミットして」(コミットは別作業だが反映の意図と取る)
- 「確定」「OK 反映して」「Approved」「LGTM」
紛らわしい場合 (例:「ここだけ OK だけど他は要修正」) は確認を取り、勝手に書き込まない。
Step 10: 書き込み
10-1. 仮画像ファイルの配置 (本文 Write の前に必ず実施)
清書版の本文中に書かれた相対パス画像 (    [](URL) など) について、実ファイルが存在しないものは src/_template/cover.png をコピー&リネームして配置する。これをやらないと npm start / astro build で「画像が見つからない」エラーになる。
このロジックは Step 3 でも呼ばれている (既存ファイル本文の仮画像を即配置するため)。Step 10-1 では Step 3 と Step 6 で増えた 清書版に追加された新規仮画像 も含めて、再度実行する。既に配置済みのファイルはスキップされるので二重実行しても安全。
手順:
- 清書版本文を正規表現で走査し、相対パス画像参照を全て抽出
- 対象パターン:
\(\.\/[^)]+\.(png|jpe?g|gif|webp|svg)\) (Markdown 画像 / リンク)
<img src="./..."> のような HTML タグ内も対象
- 各画像パスについて
src/blog/ja/{slug}/{filename} を ls で確認
- 存在しないファイルだけ
cp src/_template/cover.png src/blog/ja/{slug}/{filename} でコピー
- 既存ファイル (
cover.png, thumbnail.png, 既に置かれている画像) は絶対に上書きしない
- 配置したファイル名のリストをメモしておき、書き込み後の報告で示す
Bash 実装例:
TEMPLATE="/Users/a-hirata/projects/hira.page/src/_template/cover.png"
TARGET_DIR="/Users/a-hirata/projects/hira.page/src/blog/ja/{slug}"
for filename in "dashboard-comparison.png" "switchbot-air-purifier.jpg" "..."; do
if [ ! -f "$TARGET_DIR/$filename" ]; then
cp "$TEMPLATE" "$TARGET_DIR/$filename"
echo " placeholder: $filename"
fi
done
注意:
public/video/... などの /video/ から始まる絶対パスは 対象外 (動画はテンプレートにないため。書き込み後に手動で用意する旨を報告で添える)- 外部 URL (
https://...) は対象外
cover.png thumbnail.png は frontmatter から参照されるが既存なのでコピー不要- SVG など
_template/cover.png を流用しにくい形式は、.png などにリネームを提案するか、コピーをスキップして報告で「SVG はテンプレートからコピーできないので手動配置してください」と注意喚起
10-2. 本文の書き込み
- 対象ファイルを再度 Read (frontmatter の最新状態を取得するため)
- 先頭
--- から 2 つめの --- までを保持
- 2 つめの
--- 以降を清書版で置き換え
- Write で全文を上書き
- 末尾改行を保持
10-3. 報告
✅ src/blog/ja/{slug}/index.mdx を更新しました
📷 仮画像を配置: dashboard-comparison.png, switchbot-air-purifier.jpg, ...
仮画像を配置していない場合は 2 行目を省略。差分や統計は表示しない (見たければユーザーが git diff する)。
チェックリスト (毎回確認)
清書版を提示する直前に、以下を自分でチェック:
文体・構造:
Web 調査・引用:
画像・メディア:
書き込みフェーズに入る直前に:
対象ファイル Read 時 (Step 3):
書き込みフェーズ (Step 10) 中:
注意事項
- 書き込みは絶対に OK 検知後にだけ行う。レビュー中に勝手に Write しない。
- 文体ガイドは絶対視しない。下書きに筆者の意図 (口調・テンション) が明確にあれば、それを尊重する。ガイドはあくまで「迷ったときの参照」。
- 1 回の提示は全文。差分提示はしない (全文の方がユーザーがコピペで取り回せる)。
- 長い記事 (5000 字超) の場合、チャットのコードブロックが長くなることをユーザーに一言断ってから提示する。
- このスキルは ja 専用。en / zh-cn 版の整備は
translation-check の責任範囲。
