confluence

Confluence

Confluence を使用して、コンテンツの検索、ページの表示、スペースの管理を行います。

コンテンツを作成／更新しますか？ Markdown を使ったページの作成と更新については、references/creating-content.md を参照してください。

ネットワークアクセス

Confluence API コマンドを実行するには、設定済みの Confluence ホストへのアウトバウンド HTTPS 接続が必要です。リモート操作にはアウトバウンドネットワークアクセスが必要です。エージェント環境で制限されている場合は、最初のリモートコマンドを実行する前に、その環境の承認またはネットワーク制御を通じてアクセスを取得し、すでに付与された認可を再利用してください。ローカルのヘルプ参照やファイル処理にはネットワークアクセスは不要です。スキルの指示によってネットワークアクセスが許可されるわけではありません。DNS、接続、タイムアウトの失敗はネットワークエラーとして報告し、解決のために認証情報をリセットしないでください。承認済みのアクセスでも失敗する場合は、処理を停止してその旨を報告してください。認証エラーや権限エラーにはユーザーの対応が必要です。

スクリプトパスの解決

例にある SKILL_DIR は、読み込まれた SKILL.md を含むディレクトリです。 コマンドを実行する前に、この値をその絶対パスに設定してください。エージェントがこのシェル変数を設定するとは限りません。 スクリプトパスにスペースが含まれる場合は、パスを引用符で囲んでください。

インストール

依存関係：pip install --user requests keyring pyyaml

セットアップの確認

インストール後、次を実行してスキルの設定を確認してください。

$SKILL_DIR/scripts/confluence.py check

次の項目が確認されます。

• Python の依存関係（requests、keyring、pyyaml）
• 認証設定
• Confluence への接続

不足している項目がある場合、確認コマンドにセットアップ手順が表示されます。

認証

次のいずれかの方法で Confluence 認証を設定してください。

オプション 1：環境変数（推奨）

export CONFLUENCE_URL="https://yourcompany.atlassian.net/wiki"
export CONFLUENCE_EMAIL="[email protected]"
export CONFLUENCE_API_TOKEN="your-token"

永続化するには、これらを ~/.bashrc または ~/.zshrc に追加してください。

オプション 2：設定ファイル

~/.config/agent-skills/confluence.yaml を作成します。

url: https://yourcompany.atlassian.net/wiki
email: [email protected]
token: your-token

必要な認証情報

• URL：Confluence Cloud の URL（例：https://yourcompany.atlassian.net/wiki）
• メールアドレス：Atlassian アカウントのメールアドレス
• API トークン：https://id.atlassian.com/manage-profile/security/api-tokens で作成します

設定のデフォルト値

任意で、~/.config/agent-skills/confluence.yaml にデフォルト値を設定できます。

url: https://yourcompany.atlassian.net/wiki
email: [email protected]
token: your-token
defaults:
  cql_scope: "space = DEMO"
  max_results: 25
  default_space: "DEMO"

設定を表示するには、$SKILL_DIR/scripts/confluence.py config show を実行します。

コマンド

各コマンドの読み取り／書き込みの分類については、permissions.md を参照してください。

check

依存関係、認証、接続の確認については、セットアップの確認を参照してください。

search

CQL（Confluence Query Language）を使用してコンテンツを検索します。

# Basic search
$SKILL_DIR/scripts/confluence.py search "type=page AND space = DEMO"
$SKILL_DIR/scripts/confluence.py search "title~login" --space DEMO

# Filter by type
$SKILL_DIR/scripts/confluence.py search "space = DEMO" --type page

# Limit results
$SKILL_DIR/scripts/confluence.py search "type=page" --max-results 10

引数：

• cql：CQL クエリ文字列（必須）
• --max-results：結果の最大数（デフォルト：50）
• --type：コンテンツ種別のフィルター（page、blogpost、comment）
• --space：特定のスペースに限定

関連項目：クエリ構文については、CQL リファレンスを参照してください。

page get

ID またはタイトルを指定してページのコンテンツを取得します。

# Get by title (returns Markdown by default)
$SKILL_DIR/scripts/confluence.py page get "My Page Title"

# Get by ID
$SKILL_DIR/scripts/confluence.py page get 123456

# Get without body content
$SKILL_DIR/scripts/confluence.py page get "My Page" --no-body

# Get in original format (not Markdown)
$SKILL_DIR/scripts/confluence.py page get "My Page" --raw

# Save to file with images downloaded to sibling directory
$SKILL_DIR/scripts/confluence.py page get "My Page" -o my-page.md

# Export with YAML frontmatter (for round-tripping)
$SKILL_DIR/scripts/confluence.py page get 123456 --frontmatter -o page.md

出力：ページのメタデータとコンテンツを Markdown 形式で出力します。--output／-o を使用すると、画像は同じ階層のディレクトリにダウンロードされます。

引数：

• page_identifier：ページ ID またはタイトル（必須）
• --markdown：本文を Markdown 形式で出力（デフォルト）
• --raw：元の形式で出力
• --no-body：本文の内容を含めない
• --frontmatter：page create／page update との往復に使用できるよう、YAML フロントマター（タイトル、スペース、ラベル、親ページ）付きの Markdown として出力
• --output／-o：出力をファイルに書き込みます。画像は、ファイル名の拡張子を除いた名前を付けた同じ階層のディレクトリにダウンロードされます

page history

ページのバージョン履歴を表示します。

# By title
$SKILL_DIR/scripts/confluence.py page history "My Page Title"

# By ID, limit results
$SKILL_DIR/scripts/confluence.py page history 123456 --max-results 10

引数：

• page_identifier：ページ ID またはタイトル（必須）
• --max-results：返すバージョンの最大数（デフォルト：25）

page create / update

ページを作成または更新する際は、Markdown、画像、フロントマター、目次、内部リンクについて、references/creating-content.md を参照してください。

$SKILL_DIR/scripts/confluence.py page create --space DEMO --title "Documentation" \
  --body-file README.md
$SKILL_DIR/scripts/confluence.py page update 123456 --body-file updated.md

page move

ページを新しい親ページの下、またはスペースのルートに移動します。

# Move under a new parent
$SKILL_DIR/scripts/confluence.py page move 123456 --parent 789012

# Move to space root (no parent)
$SKILL_DIR/scripts/confluence.py page move 123456

ページの削除

ID でページを削除します（Cloud ではゴミ箱に移動します）。

$SKILL_DIR/scripts/confluence.py page delete 123456

スペース

スペースを管理します。

# List all spaces
$SKILL_DIR/scripts/confluence.py space list

# List with limit
$SKILL_DIR/scripts/confluence.py space list --max-results 10

# Filter by type
$SKILL_DIR/scripts/confluence.py space list --type global

# Get space details
$SKILL_DIR/scripts/confluence.py space get DEMO

引数：

• list：スペースを一覧表示します
  • --type：タイプで絞り込みます（global、personal）
  • --max-results：最大件数
• get <space-key>：スペースの詳細を取得します

スペースの作成については、references/creating-content.md を参照してください。

スペースの権限

スペースの権限を表示、追加、削除します。

# List all permissions for a space
$SKILL_DIR/scripts/confluence.py space permissions list DEMO

# Filter by subject type
$SKILL_DIR/scripts/confluence.py space permissions list DEMO --subject-type group

# Add a permission
$SKILL_DIR/scripts/confluence.py space permissions add DEMO \
  --subject-type user --subject "5a1234abc" --operation read --target space

# Remove a permission by ID
$SKILL_DIR/scripts/confluence.py space permissions remove DEMO --id 2154

引数：

• list <space-key>：権限を一覧表示します
  • --subject-type：ユーザーまたはグループで絞り込みます
• add <space-key>：権限を追加します
  • --subject-type：user または group（必須）
  • --subject：ユーザーアカウント ID またはグループ名／ID（必須）
  • --operation：read、create、delete、export、administer、archive、restrict_content（必須）
  • --target：space、page、blogpost、comment、attachment（必須）
• remove <space-key>：権限を削除します
  • --id：権限 ID（必須）

config

設定とデフォルト値を表示します。

# Show all configuration
$SKILL_DIR/scripts/confluence.py config show

# Show space-specific defaults
$SKILL_DIR/scripts/confluence.py config show --space DEMO

次の情報が表示されます：

• 認証設定（トークンはマスクされます）
• デフォルトの CQL スコープ、最大件数、デフォルトのスペース
• 親ページとラベルに関するスペース固有のデフォルト値

CQL リファレンス

CQL の構文全般については、Confluence CQL のドキュメントを参照してください。

よく使われるパターン：type=page、space=KEY、title~text、text~keyword、created >= now("-7d")、label=name。

AND、OR、ORDER BY と組み合わせます：

$SKILL_DIR/scripts/confluence.py search "type=page AND space=DEMO ORDER BY created DESC"

例

一般的な読み取り操作については、search、page get、space の例を参照してください。ページの作成、更新、バッチワークフローについては、コンテンツの作成を参照してください。

モデルに関するガイダンス

このスキルは、構造化された入出力を必要とする API 呼び出しを行います。標準的な能力を備えたモデルを推奨します。