ai-coding-skills/docs/ATLASSIAN.md

ATLASSIAN

Purpose

Provide a portable Atlassian Cloud skill for Codex, Claude Code, Cursor Agent, and OpenCode 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.

Requirements

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

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

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

Verify Installation

Run in the installed scripts/ folder:

node -e "require.resolve('commander');require.resolve('dotenv');console.log('OK: runtime dependencies installed')"
test -n \"$ATLASSIAN_BASE_URL\"
test -n \"$ATLASSIAN_EMAIL\"
test -n \"$ATLASSIAN_API_TOKEN\"
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
• Search Confluence pages:
  • pnpm atlassian conf-search --query "title ~ \\\"Runbook\\\""
• Dry-run a Confluence page update:
  • pnpm atlassian conf-update --page 12345 --title "Runbook" --body-file page.storage.html --dry-run
• Use bounded raw mode:
  • pnpm atlassian raw --product jira --method GET --path "/rest/api/3/issue/ENG-123"

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.