Jira-AI Skill

The jira-ai skill provides comprehensive command-line access to Atlassian Jira and Confluence platforms, allowing agents to manage issues, projects, users, and documentation efficiently.

Installation

To install jira-ai, run:

npm install -g jira-ai

Authentication Setup

Before using jira-ai, you need to configure your Jira credentials:

1. Create a .env file with the following values:

   JIRA_HOST=your-domain.atlassian.net
   [email protected]
   JIRA_API_TOKEN=your-api-token
   

2. Authenticate using the .env file:

   jira-ai auth --from-file path/to/.env
   

Configuration

You can manage settings using the settings command:

jira-ai settings --help

Apply settings from a YAML file:

jira-ai settings --apply my-settings.yaml

Validate settings:

jira-ai settings --validate my-settings.yaml

Commands Overview

Top-Level Commands

Command	Description
jira-ai auth	Set up Jira authentication credentials
jira-ai settings	View, validate, or apply configuration settings
jira-ai about	Show information about the tool
jira-ai help	Display help for commands

Issue Management (issue)

Command	Description
jira-ai issue get <issue-id>	Retrieve comprehensive issue data
jira-ai issue create	Create a new Jira issue
jira-ai issue search <jql-query>	Execute a JQL search query
jira-ai issue transition <issue-id> <to-status>	Change the status of a Jira issue
jira-ai issue update <issue-id>	Update a Jira issue's description
jira-ai issue comment <issue-id>	Add a new comment to a Jira issue
jira-ai issue stats <issue-ids>	Calculate time-based metrics for issues
jira-ai issue assign <issue-id> <account-id>	Assign or reassign a Jira issue
jira-ai issue label add <issue-id> <labels>	Add labels to a Jira issue
jira-ai issue label remove <issue-id> <labels>	Remove labels from a Jira issue

Project Management (project)

Command	Description
jira-ai project list	List all accessible Jira projects
jira-ai project statuses <project-key>	Fetch workflow statuses for a project
jira-ai project types <project-key>	List issue types available for a project

User Management (user)

Command	Description
jira-ai user me	Show profile details for authenticated user
jira-ai user search [project-key]	Search and list users
jira-ai user worklog <person> <timeframe>	Retrieve worklogs for a user

Organization Management (org)

Command	Description
jira-ai org list	List all saved Jira organization profiles
jira-ai org use <alias>	Switch the active Jira organization profile
jira-ai org add <alias>	Add a new Jira organization profile
jira-ai org remove <alias>	Delete credentials for an organization

Confluence Commands (confl)

Command	Description
jira-ai confl get <url>	Download Confluence page content
jira-ai confl spaces	List all allowed Confluence spaces
jira-ai confl pages <space-key>	Display pages within a space
jira-ai confl create <space> <title> [parent-page]	Create a new Confluence page
jira-ai confl comment <url>	Add a comment to a Confluence page
jira-ai confl update <url>	Update a Confluence page

Usage Examples

Search for issues assigned to the current user

jira-ai issue search "assignee = currentUser()"

Get details of a specific issue

jira-ai issue get PROJ-123

Create a new issue

jira-ai issue create --project "PROJ" --summary "New task" --issuetype "Story"

Transition an issue to a new status

jira-ai issue transition PROJ-123 "In Progress"

Add a comment to an issue

jira-ai issue comment PROJ-123 --file comment.md

List all projects

jira-ai project list

Get worklogs for a user

jira-ai user worklog [email protected] 2w

Configuration Options

The jira-ai tool supports extensive configuration through settings files. You can define:

• Allowed Jira projects
• Allowed commands
• Allowed Confluence spaces
• Default behaviors for various operations

Example settings structure:

defaults:
  allowed-jira-projects:
    - all                     # Allow all projects
  allowed-commands:
    - all                     # Allow all commands
  allowed-confluence-spaces:
    - all                     # Allow all Confluence spaces

organizations:
  work:
    allowed-jira-projects:
      - PROJ                  # Allow specific project
      - key: PM               # Project-specific config
        commands:
          - issue.get         # Only allow reading issues
        filters:
          participated:
            was_assignee: true
    allowed-commands:
      - issue                 # All issue commands
      - project.list          # Only project list
      - user.me               # Only user me
    allowed-confluence-spaces:
      - DOCS

Benefits

• Efficient API Usage: Minimizes the number of API calls needed to perform common operations
• Batch Operations: Process multiple items at once to reduce API usage
• Smart Filtering: Use JQL to retrieve only the specific data needed
• Local Processing: Handle operations locally before sending targeted requests to Jira
• Configuration-Based Access Control: Define allowed commands and projects to prevent unauthorized operations
• Specific Command Targeting: Get only the information needed, reducing payload sizes and API usage

Security Considerations

• Store API tokens securely in environment files
• Use configuration-based access controls to limit operations
• Regularly rotate API tokens
• Limit permissions to the minimum required for operations