Atlassian Jira & Confluence Skill

What this skill does: Create, read, update, and delete Jira issues/projects/sprints/boards and Confluence pages/spaces/attachments using the atlassian-python-api SDK.

Requires: Python 3 + pip install atlassian-python-api (run once)

路径约定: 以下所有 scripts/... 路径均相对于本 Skill 目录（.agents/skills/atlassian-jira-confluence/）。

✅ Setup Checklist

Complete these steps once before using the skill.

Step 1 — Install SDK

pip install atlassian-python-api
# or: python -m pip install atlassian-python-api

It's safe to run multiple times.

Step 2 — Configure Credentials

Choose one of the two options below. Config file takes priority over env vars.

Option A — Config file (recommended for persistent setups)

Create $WORKSPACE/.config/atlassian-jira-confluence.json (or ~/.config/atlassian-jira-confluence.json):

{
  "JIRA_URL": "https://your-jira.example.com",
  "JIRA_PAT_TOKEN": "your-pat-token",
  "JIRA_USERNAME": "you@example.com",
  "CONFLUENCE_URL": "https://your-confluence.example.com",
  "CONFLUENCE_PAT_TOKEN": "your-pat-token",
  "CONFLUENCE_USERNAME": "you@example.com"
}

Option B — Environment variables

# Confluence
export CONFLUENCE_URL="https://your-confluence.example.com"
export CONFLUENCE_PAT_TOKEN="your-pat-token"
export CONFLUENCE_USERNAME="you@example.com"   # Cloud only

# Jira
export JIRA_URL="https://your-jira.example.com"
export JIRA_PAT_TOKEN="your-pat-token"
export JIRA_USERNAME="you@example.com"         # Cloud only

Windows CMD / PowerShell:

set JIRA_URL=https://your-jira.example.com
set JIRA_PAT_TOKEN=your-pat-token
set CONFLUENCE_URL=https://your-confluence.example.com
set CONFLUENCE_PAT_TOKEN=your-pat-token

PAT Token: Personal Access Token. On Atlassian Cloud, generate at https://id.atlassian.com/manage-profile/security/api-tokens (use as password).
*_USERNAME is only required for Atlassian Cloud (.atlassian.net).

Step 3 — Test the Connection

# Save as test_connection.py and run: python test_connection.py
import sys, os
from atlassian import Jira

# (paste get_jira() helper below here, or copy from the Initialize Clients section)
jira = get_jira()
print(jira.myself())

⚡ Quick Reference

📋 Task Workflows

Workflow A — Triage / Update a Jira Issue (Step-by-Step Checklist)

• 1. Install SDK if needed: pip install atlassian-python-api
• 3. Copy the Initialize Clients code block below into the script
• 4. Search for issues:

  issues = jira.jql("project = PROJ AND status = 'To Do' ORDER BY priority DESC", limit=20)
  for issue in issues.get("issues", []):
      print(issue["key"], issue["fields"]["summary"])

• 5. Get full details of a specific issue:

  issue = jira.issue("PROJ-123")
  print(issue["fields"]["status"]["name"])

• 6. Update a field:

  jira.update_issue_field("PROJ-123", fields={"priority": {"name": "High"}})

• 7. Transition to new status:

  jira.transition_issue("PROJ-123", "In Progress")

• 8. Add a comment:

  jira.add_comment("PROJ-123", "Investigating root cause.")

Workflow B — Create / Update a Confluence Page (Step-by-Step Checklist)

• 1. Copy the Initialize Clients code block below into the script
• 3. Find the target space key (list all spaces):

  spaces = confluence.get_all_spaces(start=0, limit=50)
  for s in spaces.get("results", []):
      print(s["key"], s["name"])

• 4. Check if the page already exists:

  page = confluence.get_page_by_title("MYSPACE", "My Page Title")

• 5a. If page does NOT exist — create it:

  result = confluence.create_page(
      space="MYSPACE",
      title="My Page Title",
      body="<p>Content in storage format.</p>",
      parent_id=None,   # or a parent page ID
  )
  print(result["id"], result["_links"]["webui"])

• 5b. If page EXISTS — update it:

  page_id = page["id"]
  confluence.update_page(page_id, "My Page Title", "<p>Updated content.</p>")

• 6. (Optional) Add a label:

  confluence.set_page_label(page_id, "my-label")

Initialize Clients (Code Template)

Always use this code block so config-file priority is respected automatically.

import json, os
from pathlib import Path
from atlassian import Jira, Confluence


def _load_skill_config(skill_name: str) -> dict:
    """Load {cwd}/.config/{skill}.json or ~/.config/{skill}.json."""
    for p in [Path.cwd() / ".config" / f"{skill_name}.json",
              Path.home() / ".config" / f"{skill_name}.json"]:
        if p.is_file():
            try:
                d = json.loads(p.read_text(encoding="utf-8"))
                return d if isinstance(d, dict) else {}
            except (json.JSONDecodeError, OSError):
                pass
    return {}


def _is_cloud(url: str) -> bool:
    return "atlassian.net" in url


def get_jira():
    """Return authenticated Jira client (config file preferred, env vars fallback)."""
    cfg   = _load_skill_config("atlassian-jira-confluence")
    url   = (cfg.get("JIRA_URL") or os.environ.get("JIRA_URL", "")).strip().rstrip("/")
    token = (cfg.get("JIRA_PAT_TOKEN") or os.environ.get("JIRA_PAT_TOKEN", "")).strip()
    user  = (cfg.get("JIRA_USERNAME") or os.environ.get("JIRA_USERNAME", "")).strip()
    if not url or not token:
        raise EnvironmentError(
            "Jira credentials missing.\n"
            "  Option 1: create .config/atlassian-jira-confluence.json with JIRA_URL and JIRA_PAT_TOKEN\n"
            "  Option 2: set JIRA_URL and JIRA_PAT_TOKEN environment variables."
        )
    if _is_cloud(url):
        return Jira(url=url, username=user, password=token, cloud=True)
    return Jira(url=url, token=token)


def get_confluence():
    """Return authenticated Confluence client (config file preferred, env vars fallback)."""
    cfg   = _load_skill_config("atlassian-jira-confluence")
    url   = (cfg.get("CONFLUENCE_URL") or os.environ.get("CONFLUENCE_URL", "")).strip().rstrip("/")
    token = (cfg.get("CONFLUENCE_PAT_TOKEN") or os.environ.get("CONFLUENCE_PAT_TOKEN", "")).strip()
    user  = (cfg.get("CONFLUENCE_USERNAME") or os.environ.get("CONFLUENCE_USERNAME", "")).strip()
    if not url or not token:
        raise EnvironmentError(
            "Confluence credentials missing.\n"
            "  Option 1: create .config/atlassian-jira-confluence.json with CONFLUENCE_URL and CONFLUENCE_PAT_TOKEN\n"
            "  Option 2: set CONFLUENCE_URL and CONFLUENCE_PAT_TOKEN environment variables."
        )
    if _is_cloud(url):
        return Confluence(url=url, username=user, password=token, cloud=True)
    return Confluence(url=url, token=token)

Configuration Reference

Config Reference

Set env vars:

export JIRA_URL="https://your-jira.example.com"
export JIRA_PAT_TOKEN="your-pat-token"
export CONFLUENCE_URL="https://your-confluence.example.com"
export CONFLUENCE_PAT_TOKEN="your-pat-token"

Windows CMD: set VAR=value | PowerShell: $env:VAR = "value"

Execution Rules (Important for All Models)

1. Always call load_config() at the start — it reads from environment variables.
2. Handle errors gracefully:

   from atlassian.errors import ApiError
   try:
       result = jira.issue("PROJ-123")
   except ApiError as e:
       print(f"API error {e.status_code}: {e.reason}")
   except Exception as e:
       print(f"Error: {e}")

Jira Operations Reference

Full reference: references/jira-operations.md

Confluence Operations Reference

Full reference: references/confluence-operations.md

Quick Examples

Create a Jira Issue

fields = {
    "project": {"key": "PROJ"},
    "summary": "Fix login bug",
    "description": "Users cannot log in with SSO.",
    "issuetype": {"name": "Bug"},
    "priority": {"name": "High"},
}
new_issue = jira.issue_create(fields=fields)
print(new_issue["key"])

JQL Search

issues = jira.jql("project = PROJ AND status = 'In Progress' ORDER BY created DESC", limit=50)
for issue in issues.get("issues", []):
    print(issue["key"], issue["fields"]["summary"])

Create a Confluence Page

body = "<p>This is the page content in storage format.</p>"
result = confluence.create_page(
    space="MYSPACE",
    title="My New Page",
    body=body,
    parent_id=None,  # or pass a parent page ID
)
print(result["id"], result["_links"]["webui"])

Search Confluence with CQL

results = confluence.cql('space = "MYSPACE" AND type = page AND text ~ "deployment"', limit=20)
for item in results.get("results", []):
    print(item["title"], item["_links"]["webui"])

⛔ 约束与禁止事项

不支持的场景

明确禁止的操作

• ⛔ 禁止硬编码 url, username, api_token：必须从环境变量读取
• ⛔ 禁止在日志/输出中打印 api_token 或 password：不论任何错误情况
• ⛔ 禁止在没有环境变量时静默使用空凭据运行：必须 exit 1 并提示配置
• ⛔ 禁止 delete 操作不经用户确认：删除 Jira issue、Confluence page、space 前必须在报告中列明将要删除的内容，等待用户确认

边界条件

幂等性声明

For the complete API reference with all method signatures, see:

• references/jira-operations.md
• references/confluence-operations.md
• scripts/setup_check.py — verifies environment and SDK installation