ai-coding-skills/docs/ATLASSIAN.md

ATLASSIAN

Purpose

Provide a portable Atlassian Cloud skill for Codex, Claude Code, Cursor Agent, OpenCode, and Pi using one shared CLI surface for common Jira and Confluence workflows.

Why This Skill Exists

The repo targets multiple agent environments with uneven MCP availability. This skill packages a consistent CLI contract so the same task-oriented workflows can be used across all supported agents without depending on MCP-specific integrations.

The canonical runtime lives in skills/atlassian/shared/scripts/. Installable per-agent scripts/ bundles are generated from that source with:

pnpm --dir skills/atlassian/shared/scripts sync:agents

Requirements

• Node.js 20+
• pnpm
• Atlassian Cloud access
• ATLASSIAN_BASE_URL
• ATLASSIAN_EMAIL
• ATLASSIAN_API_TOKEN

The ATLASSIAN_* values may come from the shell environment or a .env file in the installed agent-specific scripts/ folder.

Optional:

• ATLASSIAN_JIRA_BASE_URL
• ATLASSIAN_CONFLUENCE_BASE_URL
• ATLASSIAN_DEFAULT_PROJECT
• ATLASSIAN_DEFAULT_SPACE

Supported Commands

• health
• jira-search
• jira-get
• jira-create
• jira-update
• jira-comment
• jira-transitions
• jira-transition
• conf-search
• conf-get
• conf-create
• conf-update
• conf-comment
• conf-children
• raw

Command Notes

• health validates local configuration, probes Jira and Confluence separately, and reports one product as unavailable without masking the other.
• jira-create requires --type, --summary, and either --project or ATLASSIAN_DEFAULT_PROJECT.
• jira-update requires --issue and at least one of --summary or --description-file.
• conf-create requires --title, --body-file, and either --space or ATLASSIAN_DEFAULT_SPACE.
• conf-update requires --page, --title, and --body-file; it fetches the current page version before building the update payload.
• raw --body-file expects a workspace-scoped JSON file and is limited to validated Atlassian API prefixes.

Safety Model

• Default output is JSON.
• Mutating commands support --dry-run.
• Jira long-text fields are converted to ADF locally.
• Confluence page writes are storage-first in v1.
• raw is restricted to GET|POST|PUT.
• --body-file must stay within the active workspace.

Install

Codex

mkdir -p ~/.codex/skills/atlassian
cp -R skills/atlassian/codex/* ~/.codex/skills/atlassian/
cd ~/.codex/skills/atlassian/scripts
pnpm install

Claude Code

mkdir -p ~/.claude/skills/atlassian
cp -R skills/atlassian/claude-code/* ~/.claude/skills/atlassian/
cd ~/.claude/skills/atlassian/scripts
pnpm install

OpenCode

mkdir -p ~/.config/opencode/skills/atlassian
cp -R skills/atlassian/opencode/* ~/.config/opencode/skills/atlassian/
cd ~/.config/opencode/skills/atlassian/scripts
pnpm install

Cursor

Repo-local install:

mkdir -p .cursor/skills/atlassian
cp -R skills/atlassian/cursor/* .cursor/skills/atlassian/
cd .cursor/skills/atlassian/scripts
pnpm install

Global install:

mkdir -p ~/.cursor/skills/atlassian
cp -R skills/atlassian/cursor/* ~/.cursor/skills/atlassian/
cd ~/.cursor/skills/atlassian/scripts
pnpm install

Pi

Recommended full Pi package install:

./scripts/install-pi-package.sh --global
# or, for project-local Pi package install
./scripts/install-pi-package.sh --local

Manual single-skill Pi install from the package mirror:

pnpm run sync:pi
mkdir -p .pi/skills/atlassian
cp -R pi-package/skills/atlassian/* .pi/skills/atlassian/
cd .pi/skills/atlassian/scripts
pnpm install --frozen-lockfile

Global manual installs use ~/.pi/agent/skills/atlassian/ instead of .pi/skills/atlassian/.

Verify Installation

Run in the installed scripts/ folder:

node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
node -e 'require("dotenv").config({ path: ".env" }); const required = ["ATLASSIAN_BASE_URL", "ATLASSIAN_EMAIL", "ATLASSIAN_API_TOKEN"]; const missing = required.filter((key) => !(process.env[key] || "").trim()); if (missing.length) { console.error("Missing required Atlassian config: " + missing.join(", ")); process.exit(1); } console.log("OK: Atlassian config present")'
pnpm atlassian health

Usage Examples

• Search Jira issues:
  • pnpm atlassian jira-search --jql "project = ENG ORDER BY updated DESC" --max-results 25
• Inspect an issue:
  • pnpm atlassian jira-get --issue ENG-123
• Dry-run a Jira comment:
  • pnpm atlassian jira-comment --issue ENG-123 --body-file comment.md --dry-run
• Dry-run a Jira issue create with default project fallback:
  • pnpm atlassian jira-create --type Story --summary "Add Atlassian skill" --description-file story.md --dry-run
• Search Confluence pages:
  • pnpm atlassian conf-search --query "title ~ \\\"Runbook\\\"" --max-results 10 --start-at 0
• Inspect a Confluence page:
  • pnpm atlassian conf-get --page 12345
• Dry-run a Confluence page update:
  • pnpm atlassian conf-update --page 12345 --title "Runbook" --body-file page.storage.html --dry-run
• Dry-run a Confluence footer comment:
  • pnpm atlassian conf-comment --page 12345 --body-file comment.storage.html --dry-run
• Use bounded raw mode:
  • pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"
  • pnpm atlassian raw --product confluence --method POST --path "/wiki/api/v2/pages" --body-file page.json --dry-run

Scope Notes

• Atlassian Cloud is first-class in v1.
• Data Center support is future work.
• Full mcp-atlassian parity is not the goal in v1; the initial scope is the approved core workflow set above.