confluence-page-writer

name	confluence-page-writer
description	Confluenceページを新規作成・更新する際に使用する。Atlassian MCP経由でHTML形式の本文を組み立てる際の書式ルールと記法を定める。
user-invocable	false

Confluenceページ作成・更新スキル

使うタイミング

• 「Confluenceのこのページを更新して」「Confluenceに記事を書いて」等の 指示を受けたとき
• Atlassian MCP (updateConfluencePage / createConfluencePage) で ページ本文を書き込むとき

絶対に守ること

• 指定されたページ以外を勝手に更新するのは厳禁
  • 更新対象はユーザーが明示したページIDまたはURLのものだけとする
  • 関連ページに書いた方が良さそうに見えても、勝手に手を出さない。 必要だと考える場合は提案だけしてユーザーの判断を待つ
• 書き込みは他者から見える操作なので、実行前に必ずドラフトを チャット上に提示して確認を得る
• ユーザーが手動で編集した箇所を勝手に元に戻さない(後述)

共通の書式ルール

どんな記事を書く場合にも以下を守る。

1. 目次を記事冒頭に付ける
   • 本文の一番先頭に目次マクロを置く
2. 最上位の見出し(h1)には下線を付ける
   • h2以下の見出しには下線を付けない
3. 本文の直後にセクション見出しが来る場合は一行空行を開ける
   • 見た目がギチギチになるのを避けるため
   • 最上位(h1)に限らず、h2・h3などのサブセクション見出しの前も同様に 空行を入れる
   • 見出しが連続する場合(h1の直後にh2が来る場合など)は空行を入れない。 空けたいのはあくまで本文の下であるため
   • 記事冒頭の最初の見出しの前も不要(手前に本文が無いため)
4. 箇条書き以外の文章は1文ごとに別段落にする
   • 同一行に複数の文を書かない
   • 段落内改行(<br />)ではなく段落(<p>)を分ける
5. 記事の「幅を調整」は「広い」を選択する
   • MCPには幅を指定するパラメータが無いため、新規作成した場合は ユーザーに手動で「広い」に変更してもらうよう依頼する
   • 既に「広い」になっているページはMCPで更新しても幅設定が 保持されるので、更新時は何もしなくて良い
6. ユーザーの手動編集を尊重する
   • フィードバックを受けて再更新する場合、ユーザー側で手動編集された 部分は元に戻さない

MCPでの記法

contentFormat は "html" を使う。 "markdown" では下線や目次マクロを表現できない。 "adf" でも書けるが、HTMLの方が記述量が少なく round-trip 安全である。

目次マクロ

<div
    data-type="extension"
    data-extension-key="toc"
    data-extension-type="com.atlassian.confluence.macro.core"
    data-layout="default"
></div>

macroId は指定しない(Confluence側で自動採番される)。

下線付きの最上位見出し

<h1><u>セクション名</u></h1>

<u> はADFの underline mark に変換される。 h2以下は <h2>サブセクション名</h2> のように下線なしで書く。

空行

<p></p>

空の段落として保持され、見た目の空行になる。

本文サンプル

上記ルールをすべて満たす最小構成。

<div
    data-type="extension"
    data-extension-key="toc"
    data-extension-type="com.atlassian.confluence.macro.core"
    data-layout="default"
></div>
<h1><u>1. 概要</u></h1>
<p>1文目はこのように独立した段落にする。</p>
<p>2文目も別の段落にする。</p>
<p></p>
<h1><u>2. 詳細</u></h1>
<h2>2.1 サブセクション</h2>
<p>見出しが連続する場合(直前がh1)は空行を入れない。</p>
<p>箇条書き以外の文章は文ごとに改行する。</p>
<ul>
    <li>箇条書き項目1</li>
    <li>箇条書き項目2</li>
</ul>

2.2 別のサブセクション
本文の直後なのでサブセクション見出しの前にも空行を入れる。

3. まとめ
末尾の段落である。

更新時の手順

1. getConfluencePage を contentFormat: "html" で呼び、現在の本文を 取得する
2. 取得したHTMLを土台にして差分を組み立てる。全文を書き直すのではなく、 必要な箇所だけ書き換える
3. ドラフトをユーザーに提示し、確認を得る
4. updateConfluencePage を実行する。versionMessage に変更内容を書く

既存の属性を落とさない

• 既存ノードの data-local-id はそのまま維持する
  • 新規に追加するノードには data-local-id を付けない
  • inline comment の紐付けが壊れるのを防ぐため
• 既存マクロの data-parameters はそのまま引き継ぐ
  • 例: 目次マクロに macroParams.style.value = "none" が 設定されているページで、この属性を落として更新すると 目次の見た目が変わってしまう
  • ユーザーがエディタ上で設定した内容が消えるため、 取得したHTMLの属性をそのまま貼り直すこと

手動編集への配慮

• 前回自分が書いた内容と現在のページ内容を比較し、差異があれば ユーザーによる手動編集と判断する
• 手動編集された表現・装飾・追記は残したまま、依頼された箇所だけを 変更する
• 自分の書式ルールに合わない書き方がユーザーの手で入っている場合も、 勝手に直さない。気になる場合は指摘だけする