135 lines
3.3 KiB
Markdown
135 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
mkdir -p ~/.codex/skills/atlassian
|
|
cp -R skills/atlassian/codex/* ~/.codex/skills/atlassian/
|
|
cd ~/.codex/skills/atlassian/scripts
|
|
pnpm install
|
|
```
|
|
|
|
### Claude Code
|
|
|
|
```bash
|
|
mkdir -p ~/.claude/skills/atlassian
|
|
cp -R skills/atlassian/claude-code/* ~/.claude/skills/atlassian/
|
|
cd ~/.claude/skills/atlassian/scripts
|
|
pnpm install
|
|
```
|
|
|
|
### OpenCode
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
mkdir -p .cursor/skills/atlassian
|
|
cp -R skills/atlassian/cursor/* .cursor/skills/atlassian/
|
|
cd .cursor/skills/atlassian/scripts
|
|
pnpm install
|
|
```
|
|
|
|
Global install:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|