claude-engineering-plugin/plugins/compound-engineering/skills/sync-confluence/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
sync-confluence	This skill should be used when syncing local markdown documentation to Confluence Cloud pages. It handles first-time setup (creating mapping files and docs directories), pushing updates to existing pages, and creating new pages with interactive destination prompts. Triggers on "sync to confluence", "push docs to confluence", "update confluence pages", "create a confluence page", or any request to publish markdown content to Confluence.	Read, Bash(find *), Bash(source *), Bash(uv run *)

Sync Confluence

Sync local markdown files to Confluence Cloud pages via REST API. Handles the full lifecycle: first-time project setup, page creation, and bulk updates.

Prerequisites

Two environment variables must be set (typically in ~/.zshrc):

• CONFLUENCE_EMAIL — Atlassian account email
• CONFLUENCE_API_TOKEN_WRITE — Atlassian API token with write scope (falls back to CONFLUENCE_API_TOKEN)

Generate tokens at: https://id.atlassian.com/manage-profile/security/api-tokens

The script requires uv to be installed. Dependencies (markdown, requests, truststore) are declared inline via PEP 723 and resolved automatically by uv run.

Workflow

1. Check for Mapping File

Before running the sync script, check whether a .confluence-mapping.json exists in the project:

find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -name ".confluence-mapping.json" -maxdepth 3 2>/dev/null

• If found — skip to step 3 (Sync).
• If not found — proceed to step 2 (First-Time Setup).

2. First-Time Setup

When no mapping file exists, gather configuration interactively via AskUserQuestion:

1. Confluence base URL — e.g., https://myorg.atlassian.net/wiki
2. Space key — short identifier in Confluence URLs (e.g., ZR, ENG)
3. Parent page ID — the page under which synced pages nest. Tell the user: "Open the parent page in Confluence — the page ID is the number in the URL."
4. Parent page title — prefix for generated page titles (e.g., ATS Platform)
5. Docs directory — where markdown files live relative to repo root (default: docs/)

Then create the docs directory and mapping file:

import json
from pathlib import Path

config = {
    "confluence": {
        "cloudId": "<domain>.atlassian.net",
        "spaceId": "",
        "spaceKey": "<SPACE_KEY>",
        "baseUrl": "<BASE_URL>"
    },
    "parentPage": {
        "id": "<PARENT_PAGE_ID>",
        "title": "<PARENT_TITLE>",
        "url": "<BASE_URL>/spaces/<SPACE_KEY>/pages/<PARENT_PAGE_ID>"
    },
    "pages": {},
    "unmapped": [],
    "lastSynced": ""
}

docs_dir = Path("<REPO_ROOT>") / "<DOCS_DIR>"
docs_dir.mkdir(parents=True, exist_ok=True)
mapping_path = docs_dir / ".confluence-mapping.json"
mapping_path.write_text(json.dumps(config, indent=2) + "\n")

To discover spaceId (required for page creation), run:

source ~/.zshrc && curl -s -u "${CONFLUENCE_EMAIL}:${CONFLUENCE_API_TOKEN_WRITE}" \
  -H "X-Atlassian-Token: no-check" \
  "<BASE_URL>/rest/api/space/<SPACE_KEY>" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])"

Update the mapping file with the discovered spaceId before proceeding.

3. Sync — Running the Script

The sync script is at ${CLAUDE_PLUGIN_ROOT}/skills/sync-confluence/scripts/sync_confluence.py.

Always source shell profile before running to load env vars:

source ~/.zshrc && uv run ${CLAUDE_PLUGIN_ROOT}/skills/sync-confluence/scripts/sync_confluence.py [options]

Common Operations

Command	What it does
(no flags)	Sync all markdown files in docs dir
--dry-run	Preview changes without API calls
--file docs/my-doc.md	Sync a single file
--update-only	Only update existing pages, skip unmapped files
--create-only	Only create new pages, skip existing
--mapping-file path/to/file	Use a specific mapping file
--docs-dir path/to/dir	Override docs directory

4. Creating a New Confluence Page

When the user wants to create a new page:

1. Ask for the page topic/title
2. Create the markdown file in the docs directory with a # Title heading and content
3. Run the sync script with --file pointing to the new file
4. The script detects the unmapped file, creates the page, and updates the mapping

Title resolution order: First # H1 from the markdown → filename-derived title → raw filename. Titles are prefixed with the parent page title (e.g., My Project: New Page).

5. Mapping File Structure

{
  "confluence": {
    "cloudId": "myorg.atlassian.net",
    "spaceId": "1234567890",
    "spaceKey": "ZR",
    "baseUrl": "https://myorg.atlassian.net/wiki"
  },
  "parentPage": {
    "id": "123456789",
    "title": "My Project",
    "url": "https://..."
  },
  "pages": {
    "my-doc.md": {
      "pageId": "987654321",
      "title": "My Project: My Doc",
      "url": "https://..."
    }
  },
  "unmapped": [],
  "lastSynced": "2026-03-03"
}

The script updates this file after each successful sync. Do not manually edit page entries unless correcting a known error.

Technical Notes

• Auth: Confluence REST API v1 with Basic Auth + X-Atlassian-Token: no-check. Some Cloud instances block v2 or require this XSRF bypass.
• Content format: Markdown converted to Confluence storage format (XHTML) via Python markdown library with tables, fenced code, and TOC extensions.
• SSL: truststore delegates cert verification to the OS trust store, handling corporate SSL proxies (Zscaler, etc.).
• Rate limiting: Automatic retry with backoff on 429 and 5xx responses.
• Sync timestamp: > **Last synced to Confluence**: YYYY-MM-DD injected into the Confluence copy only. Local files are untouched.
• Versioning: Page versions auto-increment. The script GETs the current version before PUTting.