AgentSkillsCN

writing

在撰写、编辑与校对文章时参考。助力作者依照其写作风格与结构模式创作博客文章，同时兼顾 textlint 与 FrontMatter 的规范要求。

SKILL.md
--- frontmatter
name: writing
description: 記事の執筆・編集・校正時に参照。著者の文体や構成パターンに沿ったブログ記事作成を支援する。textlintやフロントマターの規約も含む。
argument-hint: "[タイトルやテーマ]"

文体

  • •である/だ調を使う。です/ます調は使わない
    • •例外: カンファレンスのフィードバックなど特定の個人を対象とした文章はです/ます調
  • •一人称は「私」
  • •絵文字は使わない
  • •短い断定文で要点を強調する: 「歴史は重要だ。」「たったこれだけだ。」
  • •「〜のだ」「〜というわけだ」で説明的な結論を示す
  • •修辞疑問文を使い、自ら答える形で論を進める
  • •括弧書きで補足や個人的な感情を添える: 「（当時ろくな入力ソフトを持っていなかった）」
  • •取り消し線（~テキスト~）でユーモラスな自己訂正を入れることがある
  • •率直に失敗や無知を認める。説教調にならない
  • •*テキスト*（イタリック）で用語や引用的フレーズを強調する
  • •SEO目的の定型的な導入文を書かない

構成パターン

エッセイ記事（tag: essay）

  1. •個人的な体験・きっかけから書き始める
  2. •テーマをナラティブで展開する
  3. •振り返りや気づきで締める

カンファレンス感想記事（tag: phperkaigi 等）

  • •セッションごとに感想を書く。単なる要約ではなく自分の経験や意見と結びつける
  • •スピーカーの発言を引用し、それに対する自分のリアクションを述べる

技術記事

  1. •課題・背景の提示（動機や文脈を必ず含める）
  2. •アプローチの説明
  3. •コード例と解説（TDDスタイルのRed/Green/Refactorを好む）
  4. •注意点・制限事項

浅いHow-toにしない。「なぜそうするのか」を必ず書く。

トーク裏話記事

  • •トークの動機、題材選定の経緯、準備中の苦労や方針転換を語る
  • •話しきれなかった内容や反省点に言及する

タイトル

  • •記事の主題に応じて書き出しを選ぶ。固有名詞で始めるかどうかは内容次第
  • •titleタグ経由の検索流入を意識し、固有名詞（製品名・ライブラリ名）は必要に応じて含める
  • •記事の結論や印象的なフレーズをタイトル前半に転用してよい
  • •「対応記」「実践」などの汎用的な結語より、「確信」「気づき」など著者の主観を含む語を好む
  • •ダッシュ区切り（―）で「概念 ― 具体」の二部構成にすることがある

見出しと構造

  • •本文中にH1（#）は使わない。記事タイトルがH1の役割を果たす
  • •H2（##）で大きな区切り、H3（###）で小区分。H4以下は稀
  • •エッセイ記事では箇条書きよりも散文を優先する
  • •技術記事で手順を示す場合は箇条書きや番号付きリストも使う

分量

  • •エッセイ: 1500〜5000文字程度
  • •技術記事: 長くなってよい（10000文字超もある）
  • •1文は最大150文字（textlintルール）

フロントマター

yaml
---
title: 記事タイトル
subtitle: 補足説明（任意）
description: OGP用の要約（任意）
date: YYYY-MM-DD HH:mm
ogimage: ogimage.webp # 任意
twitter_large_card: true # 任意
tags:
  - タグ名
---
  • •ファイル名: source/_posts/YYYY-MM-DD-slug.md
  • •画像は記事と同名のアセットフォルダに配置（post_asset_folder）

ogimage

  • •無指定の場合、記事タイトルとサブタイトルから自動生成されたデフォルト画像が使われる
  • •自動生成画像使用時は twitter_large_card も自動的に true（summary_large_image）になる
  • •カスタム画像を使いたい場合のみ ogimage を指定し、大きいカードにしたい場合は twitter_large_card: true も明示する

description

  • •OGP用の要約。2〜3文、150文字前後、簡潔な表現
  • •曖昧な表現（「拙作パッケージ」等）ではなく具体的な名前を使う。検索ヒット時のCTR向上が目的

slug

  • •英語のケバブケースで、記事の核心を短く表す
  • •タイトルの直訳ではなく、内容の本質を英語で要約する
    • •例: タイトル「良い設計は読み手を選ばない」→ slug good-design-works-for-ai-too

Hexoテンプレートタグ

タグ用途
{% twitter URL %}Twitter/X埋め込み
{% link_preview URL %}{% endlink_preview %}リンクプレビュー
{% details タイトル %}...{% enddetails %}折りたたみセクション
{% post_link slug テキスト %}内部記事リンク
```plantumlPlantUML図表

コードブロック

  • •言語を必ず指定する: ```php, ```bash 等
  • •ファイルパスを添える場合がある: ```php app/Models/Post.php
  • •コードの前後に散文で文脈や意図を説明する

引用

  • •ブロック引用（>）の用途: 書籍・登壇者の発言・公式ドキュメントの引用
  • •引用元は引用の直後に明記

textlint

  • •npm run lint で校正
  • •句点（。）で文を終える（「、」「…」「:」での終了も許容）
  • •BlockQuote・CodeBlock・Hexoテンプレートタグはlint対象外
  • •一時的なルール無効化: <!-- textlint-disable ルール名 --> / <!-- textlint-enable ルール名 -->