atlassian-skills: Instructions file for Claude Code

atlassian-skills — CLAUDE.md

Project Overview

A Python CLI + Claude Code Skill that lets LLM agents drive our internal Atlassian Server/DC stack (Jira, Confluence, Bitbucket, Bamboo) in a token-efficient way. Serves as a complete replacement for the mcp-atlassian MCP server.

• Binary: atls
• Package: atlassian-skills
• Current version: 0.4.3 (a second publish of a document carrying a picture now posts a new attachment version instead of a create Confluence refuses, and external_images counts only the pictures the publish leaves elsewhere)

Build & Run

Release evidence comes from a built wheel in a throwaway venv, never from this working tree. uv run pytest here measures the tree, which is not the artifact anyone installs: it can pass over a packaging defect — missing package data, a broken console entry point, a runtime dependency declared only as a dev extra — and an editable install can pass over all three. scripts/wheel_smoke.sh is the part of that which lives in this repository and runs in CI.

# Install (uv recommended)
uv sync

# Run the CLI
uv run atls --help
uv run atls jira issue get PROJ-1 --format=compact

# Tests
uv run pytest                          # unit + contract + snapshot
uv run pytest -m integration           # hit live internal instance (manual)
uv run pytest tests/benchmarks         # token benchmarks

# Lint & type check
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/

Project Structure

src/atlassian_skills/
├── cli/                    # Typer CLI (main.py = entry point, split by product)
├── core/
│   ├── client.py           # BaseClient (httpx, retry, auth, pagination)
│   ├── auth.py             # PAT/Basic, env > keyring > config
│   ├── config.py           # ~/.config/atlassian-skills/config.toml
│   ├── errors.py           # AtlasError, exit codes per §15.4
│   ├── pagination.py       # offset + link-follow patterns
│   └── format/             # compact, md, json, raw formatters
├── jira/
│   ├── client.py           # JiraClient(BaseClient)
│   ├── models.py           # pydantic response models
│   └── preprocessing.py    # mention / smart-link preprocessing (§5.1.1)
├── confluence/
│   ├── client.py
│   └── models.py
├── bitbucket/
│   ├── client.py           # BitbucketClient(BaseClient)
│   └── models.py           # pydantic response models (PR, Comment, Branch, Task, etc.)
└── bamboo/                 # planned

tests/
├── fixtures/               # MCP capture JSON (golden files)
├── unit/                   # respx mocking
├── contract/               # response ↔ pydantic models
├── snapshot/               # syrupy CLI output regression
└── benchmarks/             # tiktoken token measurements

src/atlassian_skills/_assets/skills/atls/SKILL.md   # canonical SKILL.md installed by `atls setup` for both Claude Code and Codex
docs/                       # design docs and analyses