| name | confluence-page-writer |
| description | Confluenceページを新規作成・更新する際に使用する。Atlassian MCP経由でHTML形式の本文を組み立てる際の書式ルールと記法を定める。 |
| user-invocable | false |
Confluenceページ作成・更新スキル
使うタイミング
- 「Confluenceのこのページを更新して」「Confluenceに記事を書いて」等の
指示を受けたとき
- Atlassian MCP (
updateConfluencePage / createConfluencePage) で
ページ本文を書き込むとき
絶対に守ること
- 指定されたページ以外を勝手に更新するのは厳禁
- 更新対象はユーザーが明示したページIDまたはURLのものだけとする
- 関連ページに書いた方が良さそうに見えても、勝手に手を出さない。
必要だと考える場合は提案だけしてユーザーの判断を待つ
- 書き込みは他者から見える操作なので、実行前に必ずドラフトを
チャット上に提示して確認を得る
- ユーザーが手動で編集した箇所を勝手に元に戻さない(後述)
共通の書式ルール
どんな記事を書く場合にも以下を守る。
- 目次を記事冒頭に付ける
- 最上位の見出し(h1)には下線を付ける
- 本文の直後にセクション見出しが来る場合は一行空行を開ける
- 見た目がギチギチになるのを避けるため
- 最上位(h1)に限らず、h2・h3などのサブセクション見出しの前も同様に
空行を入れる
- 見出しが連続する場合(h1の直後にh2が来る場合など)は空行を入れない。
空けたいのはあくまで本文の下であるため
- 記事冒頭の最初の見出しの前も不要(手前に本文が無いため)
- 箇条書き以外の文章は1文ごとに別段落にする
- 同一行に複数の文を書かない
- 段落内改行(
<br />)ではなく段落(<p>)を分ける
- 記事の「幅を調整」は「広い」を選択する
- MCPには幅を指定するパラメータが無いため、新規作成した場合は
ユーザーに手動で「広い」に変更してもらうよう依頼する
- 既に「広い」になっているページはMCPで更新しても幅設定が
保持されるので、更新時は何もしなくて良い
- ユーザーの手動編集を尊重する
- フィードバックを受けて再更新する場合、ユーザー側で手動編集された
部分は元に戻さない
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. まとめ
末尾の段落である。
更新時の手順
getConfluencePage を contentFormat: "html" で呼び、現在の本文を
取得する- 取得したHTMLを土台にして差分を組み立てる。全文を書き直すのではなく、
必要な箇所だけ書き換える
- ドラフトをユーザーに提示し、確認を得る
updateConfluencePage を実行する。versionMessage に変更内容を書く
既存の属性を落とさない
- 既存ノードの
data-local-id はそのまま維持する
- 新規に追加するノードには
data-local-id を付けない
- inline comment の紐付けが壊れるのを防ぐため
- 既存マクロの
data-parameters はそのまま引き継ぐ
- 例: 目次マクロに
macroParams.style.value = "none" が
設定されているページで、この属性を落として更新すると
目次の見た目が変わってしまう
- ユーザーがエディタ上で設定した内容が消えるため、
取得したHTMLの属性をそのまま貼り直すこと
手動編集への配慮
- 前回自分が書いた内容と現在のページ内容を比較し、差異があれば
ユーザーによる手動編集と判断する
- 手動編集された表現・装飾・追記は残したまま、依頼された箇所だけを
変更する
- 自分の書式ルールに合わない書き方がユーザーの手で入っている場合も、
勝手に直さない。気になる場合は指摘だけする
