doug-skinner avatar

atlassian-cli

Execute Atlassian CLI (acli) commands for Jira work items, projects, sprints, boards, and organizati

by doug-skinner|Open Source

Atlassian CLI Claude Skill

A comprehensive Claude Code skill that provides Atlassian CLI (acli) integration for managing Jira work items, projects, sprints, boards, and organization administration. Designed for both solo developers and team-based workflows.

Overview

This skill enables Claude to execute Atlassian operations using the acli CLI, providing:

  • Work Item Management: Create, edit, search, and manage Jira issues with full JQL support
  • Project Administration: Create, configure, and manage Jira projects
  • Sprint & Board Operations: Manage agile boards, sprints, and sprint planning
  • Organization Administration: User management and organization-level operations
  • Filter Management: Create, search, and manage saved Jira filters
  • Bulk Operations: Efficient batch processing for large-scale operations
  • Team Collaboration: Sprint planning, assignments, and team coordination
  • Solo Developer Tools: Optimized workflows for personal task management

Installation

Prerequisites

  1. Atlassian CLI: The skill requires acli to be installed and authenticated.

    Installation:

    Visit the Atlassian CLI installation guide for platform-specific instructions:

    • macOS: Download from Atlassian or use package manager
    • Linux: Download binary or use package manager
    • Windows: Download installer or use package manager

    Verify installation:

    acli --version

  2. Authentication: Authenticate with Jira/Atlassian

    API Token (Recommended for Jira):

    # Generate API token at: https://id.atlassian.com/manage-profile/security/api-tokens
echo YOUR_API_TOKEN | acli jira auth login \
  --site "yoursite.atlassian.net" \
  --email "your@email.com" \
  --token

    OAuth (Browser-based):

    acli jira auth login --web

    Admin API Key (for organization management): Follow Atlassian documentation to create an admin API key, then:

    acli admin auth login

  3. Claude Code: This skill is designed for Claude Code

Install the Skill

Quick Install (One-Liner)

The easiest way to install:

# User-level (recommended - available in all projects)
bash <(curl -s https://raw.githubusercontent.com/doug-skinner/acli-claude-skill/main/install.sh)

# Or for project-specific installation
bash <(curl -s https://raw.githubusercontent.com/doug-skinner/acli-claude-skill/main/install.sh) --project

Option 1: Clone Directly

Install for all your projects:

# Clone directly into your user skills directory
mkdir -p ~/.claude/skills
cd ~/.claude/skills
git clone https://github.com/doug-skinner/acli-claude-skill.git

That's it! The skill will be available in all Claude Code sessions.

Option 2: Project-Specific Installation

Install for a specific project only:

# Navigate to your project
cd /path/to/your/project

# Clone into project skills directory
mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/doug-skinner/acli-claude-skill.git

Option 3: Download and Copy

If you don't want to use git:

  1. Download this repository as a ZIP file
  2. Extract it
  3. Copy the acli-claude-skill folder to:
    • ~/.claude/skills/ for user-level
    • your-project/.claude/skills/ for project-specific

Verify Installation

Restart Claude Code, then ask:

"List my Jira projects"

If the skill is installed correctly, Claude will execute the acli jira project list command.

Usage

Basic Usage

Simply ask Claude to perform Atlassian operations:

"Create a new Jira issue for fixing the authentication bug"
"List all issues in the TEAM project that are in progress"
"Assign PROJ-123 to alice@example.com"
"Show me sprint work items for sprint 45"
"Create a new Jira project called 'Marketing Campaign'"
"Search for all high priority bugs"

Reference Documentation

The skill includes comprehensive reference documentation for different workflows:

Claude will automatically load these guides as needed based on your requests.

Helper Scripts

The skill includes several helper scripts in the scripts/ directory:

create-issue.sh

Quick issue creation with template support:

bash scripts/create-issue.sh --project PROJ --summary "Fix login bug" --type Bug

sprint-report.sh

Generate sprint reports and summaries:

bash scripts/sprint-report.sh --sprint-id 123

bulk-assign.sh

Bulk assign issues to team members:

bash scripts/bulk-assign.sh --assignee user@example.com --jql "project = PROJ AND status = 'To Do'"

daily-standup.sh

Generate daily standup summaries:

bash scripts/daily-standup.sh

Examples

Solo Developer Workflow

User: "I want to track a new feature for adding dark mode"

Claude executes:
1. Creates a Jira issue: PROJ-124 - "Add dark mode support"
2. Assigns it to you
3. Provides the issue key for tracking

Team Collaboration

User: "List all issues in sprint 45 and show who's assigned to what"

Claude executes:
1. Fetches sprint work items using acli jira sprint list-workitems
2. Displays organized list by assignee
3. Shows status of each issue

Bulk Operations

User: "Create 10 test issues for our QA sprint"

Claude executes:
1. Creates issues using acli jira workitem create-bulk
2. Assigns appropriate labels
3. Links them to the sprint

Workflow Examples

Quick Issue Creation

# 1. Create issue
acli jira workitem create \
  --summary "Implement user authentication" \
  --project "PROJ" \
  --type "Story" \
  --description "Add OAuth2 authentication flow"

# 2. Assign to yourself
acli jira workitem assign --key "PROJ-123" --assignee "$(acli jira auth status | grep Email | awk '{print $2}')"

# 3. Transition to In Progress
acli jira workitem transition --key "PROJ-123" --status "In Progress"

Sprint Planning

# View current sprint
acli jira sprint list-workitems --sprint-id 45

# Bulk assign issues
for issue in PROJ-101 PROJ-102 PROJ-103; do
  acli jira workitem assign --key "$issue" --assignee "alice@example.com"
done

# Add sprint label
acli jira workitem edit --key "PROJ-101,PROJ-102,PROJ-103" --label "sprint-45"

Daily Standup Report

# What I worked on yesterday
acli jira workitem search \
  --jql "assignee = currentUser() AND updated >= -1d" \
  --output table

# What I'm working on today
acli jira workitem search \
  --jql "assignee = currentUser() AND status = 'In Progress'" \
  --output table

Features

Work Item Operations

  • Create, edit, and delete issues
  • Advanced JQL search
  • Transitions and workflows
  • Comments and attachments
  • Linking and cloning
  • Bulk operations
  • Archive/unarchive

Project Management

  • Create and configure projects
  • Project settings
  • Archive and restore
  • Delete projects
  • List and view details

Sprint & Board Operations

  • Search and list boards
  • View sprint work items
  • Sprint reports
  • Board configuration

Organization Administration

  • User activation/deactivation
  • User deletion and recovery
  • Organization-level settings
  • Access management

Filter Management

  • Search and list filters
  • Favorite filters
  • Change filter ownership
  • Filter-based automation

Team Features

  • Bulk assignments
  • Sprint planning tools
  • Team velocity tracking
  • Permission management

Solo Developer Tools

  • Personal task tracking
  • Quick issue creation
  • Efficient workflows
  • Personal automation scripts

Configuration

Environment Variables

Set these for easier authentication:

export JIRA_SITE="yoursite.atlassian.net"
export JIRA_EMAIL="your@email.com"
export JIRA_API_TOKEN="your-api-token"

# Then authenticate without typing credentials
echo $JIRA_API_TOKEN | acli jira auth login --site "$JIRA_SITE" --email "$JIRA_EMAIL" --token

Shell Aliases

Create aliases for frequently used commands:

# Quick issue search
alias jira-mine='acli jira workitem search --jql "assignee = currentUser() AND status != Done"'

# Quick issue creation
alias jira-bug='acli jira workitem create --project PROJ --type Bug'
alias jira-task='acli jira workitem create --project PROJ --type Task'

# Status check
alias jira-status='acli jira auth status'

Configuration File

Create a config file for project defaults:

# ~/.acli/config.yaml
defaults:
  project: PROJ
  issue_type: Task
  priority: Medium

Tips and Best Practices

For Solo Developers

  1. Use Jira issues as your personal TODO list
  2. Create templates for common issue types
  3. Use labels for context and organization
  4. Regular cleanup of completed issues
  5. Automate repetitive tasks with scripts

For Teams

  1. Establish consistent naming conventions
  2. Use components for team organization
  3. Regular sprint planning sessions
  4. Define clear workflows and transitions
  5. Track team velocity with sprints
  6. Document decisions in issue comments

General

  1. Use --output json for scripting
  2. Leverage JQL for powerful searches
  3. Combine with other CLI tools (jq, grep, etc.)
  4. Use bulk operations for efficiency
  5. Keep acli updated for latest features
  6. Store API tokens securely

Troubleshooting

Authentication Issues

# Check authentication status
acli jira auth status

# Re-authenticate
echo $JIRA_API_TOKEN | acli jira auth login --site "$JIRA_SITE" --email "$JIRA_EMAIL" --token

# Switch accounts
acli jira auth switch

Permission Errors

  • Verify you have appropriate project permissions
  • Check if you're using the correct authentication method
  • Ensure your API token hasn't expired
  • Verify site URL is correct

Command Not Found

  • Ensure acli is installed: which acli
  • Verify acli is in your PATH
  • Try reinstalling acli

JQL Errors

  • Validate JQL in Jira web UI first
  • Use quotes around field values with spaces
  • Check field names match your Jira configuration

Skill Not Loading

  • Verify skill is in the correct directory
  • Check SKILL.md has valid YAML frontmatter
  • Restart Claude Code
  • Check Claude Code logs for errors

Contributing

Contributions are welcome! To contribute:

  1. Fork this repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

Resources

License

This skill is provided as-is for use with Claude Code. See LICENSE file for details.

Support

For issues or questions:

Version

Current version: 1.0.0

Changelog

1.0.0 (Initial Release)

  • Complete work item management
  • Project administration
  • Sprint and board operations
  • Organization administration
  • Filter management
  • Team collaboration features
  • Solo developer workflows
  • Helper scripts
  • Comprehensive documentation
Download Skill