---

name: "confluence" description: "Read and search Confluence documentation. Use when the user asks about Confluence pages, wants to search documentation, read wiki content, or browse spaces."

Confluence Skill

You are a specialized assistant for reading and searching documentation in Confluence. This skill enables querying spaces, pages, and searching content across the wiki.

When to Use This Skill

Activate this skill when the user:

• Asks about Confluence pages or documentation
• Wants to read a wiki page
• Needs to search for documentation
• Asks about Confluence spaces
• Wants to find specific content in the wiki
• Mentions "Confluence", "wiki", or "documentation"

Prerequisites

Before using this skill, ensure:

1. The ~/.claude/.env file exists with JIRA_API_TOKEN and EMAIL
   • Note: Uses the SAME credentials as Jira (Atlassian Cloud)
2. Python 3.x is installed
3. Network access to Confluence instance

Skill Structure

Copy.claude/skills/confluence/
├── SKILL.md                    # This file
├── requirements.txt            # Python dependencies
└── scripts/
    ├── confluence_client.py    # Core Confluence REST API client
    └── confluence_helper.py    # High-level documentation operations

Project root contains:

• ~/.claude/.env - API credentials (JIRA_API_TOKEN, EMAIL) - shared with Jira
• output/ - Exported documents directory

Quick Start

Using ConfluenceHelper (Recommended)

Copyimport sys
sys.path.insert(0, '.claude/skills/confluence/scripts')

from confluence_helper import ConfluenceHelper

helper = ConfluenceHelper()
helper.connect()

# List spaces
spaces = helper.list_spaces()

# Get a specific space
space = helper.get_space("DOCS")

# Get a page by title
page = helper.get_page(space_key="DOCS", title="Getting Started")

# Get page content as text
content = helper.get_page_content(space_key="DOCS", title="Getting Started", format="text")

# Search for pages
results = helper.search_pages("API documentation", space_key="DOCS")

# List pages in a space
pages = helper.list_pages(space_key="DOCS", limit=50)

# Get child pages
children = helper.get_child_pages(space_key="DOCS", title="Parent Page")

# Get page hierarchy
tree = helper.get_page_tree(space_key="DOCS")

# Export page to markdown
filepath = helper.export_page_to_markdown(space_key="DOCS", title="Getting Started")

Using ConfluenceClient Directly

Copyimport sys
sys.path.insert(0, '.claude/skills/confluence/scripts')

from confluence_client import ConfluenceClient

client = ConfluenceClient()
client.authenticate()

# Get all spaces
spaces = client.get_spaces(limit=25)

# Get space by key
space = client.get_space_by_key("DOCS")

# Get page by ID
page = client.get_page("123456", body_format="storage")

# Search pages with CQL
results = client.search_pages("API", space_key="DOCS")

# Get page content
content = client.get_page_content("123456", body_format="view")

# Get child pages
children = client.get_page_children("123456")

# Get page labels
labels = client.get_page_labels("123456")

Available Operations

ConfluenceHelper Methods

ConfluenceClient Methods

CQL Query Examples

Copy# Search by text
'type=page AND text ~ "API documentation"'

# Search in specific space
'type=page AND space.key="DOCS" AND text ~ "getting started"'

# Search by title
'type=page AND title ~ "Installation"'

# Search by label
'type=page AND label = "howto"'

# Search recently modified
'type=page AND lastModified > now("-7d")'

# Search by creator
'type=page AND creator = currentUser()'

# Combine conditions
'type=page AND space.key="DOCS" AND label = "api" AND text ~ "authentication"'

Common Tasks

1. Read Documentation Page

Copy# Get page content as plain text
content = helper.get_page_content(
    space_key="DOCS",
    title="API Reference",
    format="text"
)
print(content)

2. Search Documentation

Copy# Search across all spaces
results = helper.search_pages("authentication flow")

# Search in specific space
results = helper.search_pages("deployment", space_key="DEVOPS")

for result in results:
    print(f"{result['title']} - {result['space_key']}")
    print(f"  Excerpt: {result['excerpt'][:100]}...")

3. Browse Space Structure

Copy# Get page tree
tree = helper.get_page_tree(space_key="DOCS", max_depth=2)

def print_tree(node, indent=0):
    print("  " * indent + f"- {node['title']}")
    for child in node.get('children', []):
        print_tree(child, indent + 1)

print_tree(tree['root'])

4. List All Documentation

Copy# List spaces
spaces = helper.list_spaces()
for space in spaces:
    print(f"[{space.key}] {space.name}")

    # List pages in each space
    pages = helper.list_pages(space.key, limit=10)
    for page in pages:
        print(f"  - {page.title}")

5. Export Documentation

Copy# Export single page to markdown
helper.export_page_to_markdown(
    space_key="DOCS",
    title="Installation Guide",
    output_dir="docs"
)

# Export multiple pages
pages = helper.list_pages("DOCS")
for page in pages:
    helper.export_page_to_markdown(page_id=page.id, output_dir="docs")

Error Handling

Common errors and solutions:

Running Scripts

Copy# Run the helper example
python .claude/skills/confluence/scripts/confluence_helper.py

# Run client directly with search
python .claude/skills/confluence/scripts/confluence_client.py --search "documentation"

Configuration

The client reads settings from environment:

• JIRA_API_TOKEN - API token (shared with Jira) required
• EMAIL - User email for Basic auth required
• CONFLUENCE_BASE_URL - Confluence instance URL (default: https://hpe.atlassian.net)

Note: Both Jira and Confluence use the same Atlassian Cloud credentials.

API Limits

• Maximum 100 results per page request
• Rate limits apply per Atlassian instance
• Large exports should be batched

Uploading Markdown Content to Confluence

Important: Confluence does not accept raw Markdown. Content must be converted to Confluence Storage Format (XHTML-based) before creating or updating pages.

Use the markdown_to_confluence() function from confluence_client.py:

Copyfrom confluence_client import ConfluenceClient, markdown_to_confluence

client = ConfluenceClient()
client.authenticate()

# Read markdown file
with open('document.md', 'r') as f:
    md_content = f.read()

# Convert to Confluence format
html_content = markdown_to_confluence(md_content)

# Create page
client.create_page(space_id="123456", title="My Document", content=html_content)

Supported Markdown Conversions

Converting Obsidian Links

Obsidian-style links ([[Page Name]]) can be converted to Confluence links by providing a mapping:

Copy# Map Obsidian note names to (confluence_page_id, display_title)
link_map = {
    "My Note": ("123456", "My Note Title"),
    "Another Note": ("789012", "Another Note Title"),
}

html_content = markdown_to_confluence(
    md_content,
    obsidian_link_map=link_map,
    space_key="~71202056eac634a14d4700b754441b784f3d81"
)

Without a link map, Obsidian links are converted to plain text (the link syntax is removed but the text is kept).