jira

name: jira description: Use when asked to create, search, update, or transition Jira tickets. Use when user mentions KANBAN, SCRUM, AGRHELP, or MOD projects. Use when needing ticket status, assignments, or board views. argument-hint: [ticket-key or search query]

Alliance Jira Skill

Manage Jira tickets across all Alliance of Genome Resources projects.

CRITICAL: DO NOT pipe curl output to python3, jq, or any other process. Piping causes intermittent empty-stdin failures that silently break JSON parsing. Always run curl commands standalone and read the raw JSON output directly.

MANDATORY: Credentials & Version Check (Run on Skill Load)

CRITICAL: You MUST run this bash block when the skill is first loaded, before doing anything else. This is NOT optional. Always run it as the very first step when this skill initializes. Do not skip it or jump straight to Jira operations.

if [ -f ~/.alliance/jira/.env ]; then
  source ~/.alliance/jira/.env
  echo "Credentials loaded for: $JIRA_EMAIL"
else
  echo "ERROR: Jira credentials not configured"
  echo "Run the full setup guide"
fi

# Check for skill updates
PLUGIN_JSON=$(ls -t ~/.claude/plugins/cache/alliance-plugins/alliance-jira/*/.claude-plugin/plugin.json 2>/dev/null | head -1)
INSTALLED_VERSION=$(grep -o '"version": "[^"]*"' "$PLUGIN_JSON" 2>/dev/null | cut -d'"' -f4)
LATEST_VERSION=$(curl -sf --max-time 3 https://raw.githubusercontent.com/alliance-genome/agr_claude_code/main/plugins/alliance-jira/.claude-plugin/plugin.json 2>/dev/null | grep -o '"version": "[^"]*"' | cut -d'"' -f4)
if [ -z "$LATEST_VERSION" ]; then
  echo "Skill version: ${INSTALLED_VERSION} (could not check for updates)"
elif [ "$INSTALLED_VERSION" != "$LATEST_VERSION" ]; then
  echo "*** UPDATE AVAILABLE *** Installed v${INSTALLED_VERSION}, latest v${LATEST_VERSION}"
  echo "Run: /plugin marketplace update alliance-plugins"
else
  echo "Skill version: ${INSTALLED_VERSION} (up to date)"
fi

If Credentials Missing

SECURITY: Never paste your API token into the chat. Edit files directly.

See setup.md for the complete guided setup process, which includes:

1. Creating the credentials directory
2. Getting your API token from Atlassian
3. Securely saving credentials to a file
4. Testing your configuration

Need help? Contact Christopher Tabone (christopher.tabone@jax.org) or Slack.

Session Permission Management

When the skill is first loaded and credentials are verified, ask the user about API call permissions for the session using AskUserQuestion:

{
  "questions": [{
    "question": "I need to make Jira API calls. How would you like me to handle permissions for this session?",
    "header": "Jira API",
    "options": [
      {"label": "Allow all Jira calls (Recommended)", "description": "Auto-approve all Jira API requests for this session"},
      {"label": "Ask each time", "description": "I'll ask permission before each API call"}
    ],
    "multiSelect": false
  }]
}

Permission Behavior

• If user selects "Allow all Jira calls": Proceed with all Jira API requests without further prompts. Before each API call, briefly state what you're doing (e.g., "Searching for Blue Team sprint tickets...") but don't ask for permission.

• If user selects "Ask each time": Request permission before each curl command to Jira.

Example Flow

With session permission granted:

"Fetching current sprint tickets..."
[runs curl command]
"Found 15 tickets in the current sprint."

Without session permission:

"I need to run a curl command to fetch sprint tickets. May I proceed?"
[waits for approval]
[runs curl command]

Quick Navigation

Load these files only when needed for the specific task:

Safety Rules

1. Comments are allowed on any ticket the authenticated user can access. For all other modifications (status changes, field edits, reassignment, etc.), only modify tickets assigned to the authenticated user.
2. Exception: AGRHELP tickets - can close/comment on any accessible AGRHELP ticket even when assigned to someone else
3. NEVER expose API credentials in output
4. Always GET ticket first before any modification to verify current state and assignee. For non-comment changes outside AGRHELP, verify ownership before proceeding.
5. NEVER pipe curl output through python3 - this causes intermittent empty-stdin failures. Read raw JSON output from curl directly. You can parse JSON without python.
6. AI attribution on comments - Every Jira comment drafted by an AI agent MUST end with a subscript attribution line: "This comment was drafted by <agent name>." (e.g., "Claude", "Codex"). Use ADF subsup mark with sub type for the attribution. This is non-negotiable — watchers and stakeholders need to know when a comment was AI-generated.

API Quick Reference

Endpoints

Authentication

All requests use Basic Auth:

-u "${JIRA_EMAIL}:${JIRA_API_KEY}"

Common Operations

Search with JQL (Recommended)

source ~/.alliance/jira/.env
curl -s -X POST -u "${JIRA_EMAIL}:${JIRA_API_KEY}" \
  "https://agr-jira.atlassian.net/rest/api/3/search/jql" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "jql": "project = KANBAN AND status = \"In Progress\" ORDER BY created DESC",
    "maxResults": 20,
    "fields": ["key", "summary", "status", "assignee", "priority"]
  }'

Get a Ticket

source ~/.alliance/jira/.env
curl -s -u "${JIRA_EMAIL}:${JIRA_API_KEY}" \
  "https://agr-jira.atlassian.net/rest/api/3/issue/KANBAN-123" \
  -H "Accept: application/json"

List Tickets by Component

source ~/.alliance/jira/.env
curl -s -X POST -u "${JIRA_EMAIL}:${JIRA_API_KEY}" \
  "https://agr-jira.atlassian.net/rest/api/3/search/jql" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "jql": "project = KANBAN AND component = \"AI Curation\" ORDER BY updated DESC",
    "maxResults": 20,
    "fields": ["key", "summary", "status", "assignee", "priority"]
  }'

Change Status (e.g., to "In Progress")

source ~/.alliance/jira/.env
curl -s -X POST -u "${JIRA_EMAIL}:${JIRA_API_KEY}" \
  "https://agr-jira.atlassian.net/rest/api/3/issue/KANBAN-123/transitions" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"transition": {"id": "21"}}'

See reference/statuses.md for all transition IDs.

Key IDs

Board IDs

Transition IDs (KANBAN)

Issue Type IDs

Priority IDs

See reference files for complete lists.

Atlassian Document Format (ADF)

Description and comment fields use ADF:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Your text here"}
      ]
    }
  ]
}

See operations/create-tickets.md for full ADF examples.

Common Mistakes