AGENT SKILL

jira-integration

Use this skill when retrieving Jira tickets, analyzing requirements, updating ticket status, adding comments, or transitioning issues. Provides Jira API patterns via MCP or direct REST calls.

License 许可
MIT
所属仓库
agisota/old-one
最近更新
2026-07-04
Stars
★ 3
Forks
1

01 前言 Front Matter

name
jira-integration
origin
ECC
description
Use this skill when retrieving Jira tickets, analyzing requirements, updating ticket status, adding comments, or transitioning issues. Provides Jira API patterns via MCP or direct REST calls.

03 SKILL.md 正文

Jira Integration Skill

Retrieve, analyze, and update Jira tickets directly from your AI coding workflow. Supports both MCP-based (recommended) and direct REST API approaches.

When to Activate

  • Fetching a Jira ticket to understand requirements
  • Extracting testable acceptance criteria from a ticket
  • Adding progress comments to a Jira issue
  • Transitioning a ticket status (To Do → In Progress → Done)
  • Linking merge requests or branches to a Jira issue
  • Searching for issues by JQL query

Prerequisites

Option A: MCP Server (Recommended)

Install the mcp-atlassian MCP server. This exposes Jira tools directly to your AI agent.

Requirements:

  • Python 3.10+
  • uvx (from uv), installed via your package manager or the official uv installation documentation

Add to your MCP config (e.g., ~/.claude.json → mcpServers):

{
  "jira": {
    "command": "uvx",
    "args": ["mcp-atlassian==0.21.0"],
    "env": {
      "JIRA_URL": "https://YOUR_ORG.atlassian.net",
      "JIRA_EMAIL": "your.email@example.com",
      "JIRA_API_TOKEN": "your-api-token"
    },
    "description": "Jira issue tracking — search, create, update, comment, transition"
  }
}

Security: Never hardcode secrets. Prefer setting JIRA_URL, JIRA_EMAIL, and JIRA_API_TOKEN in your system environment (or a secrets manager). Only use the MCP env block for local, uncommitted config files.

To get a Jira API token:

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click Create API token
  3. Copy the token — store it in your environment, never in source code

Option B: Direct REST API

If MCP is not available, use the Jira REST API v3 directly via curl or a helper script.

Required environment variables:

Variable Description
JIRA_URL Your Jira instance URL (e.g., https://yourorg.atlassian.net)
JIRA_EMAIL Your Atlassian account email
JIRA_API_TOKEN API token from id.atlassian.com

Store these in your shell environment, secrets manager, or an untracked local env file. Do not commit them to the repo.

MCP Tools Reference

When the mcp-atlassian MCP server is configured, these tools are available:

Tool Purpose Example
jira_search JQL queries project = PROJ AND status = "In Progress"
jira_get_issue Fetch full issue details by key PROJ-1234
jira_create_issue Create issues (Task, Bug, Story, Epic) New bug report
jira_update_issue Update fields (summary, description, assignee) Change assignee
jira_transition_issue Change status Move to "In Review"
jira_add_comment Add comments Progress update
jira_get_sprint_issues List issues in a sprint Active sprint review
jira_create_issue_link Link issues (Blocks, Relates to) Dependency tracking
jira_get_issue_development_info See linked PRs, branches, commits Dev context

Tip: Always call jira_get_transitions before transitioning — transition IDs vary per project workflow.

Direct REST API Reference

Fetch a Ticket

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{
    key: .key,
    summary: .fields.summary,
    status: .fields.status.name,
    priority: .fields.priority.name,
    type: .fields.issuetype.name,
    assignee: .fields.assignee.displayName,
    labels: .fields.labels,
    description: .fields.description
  }'

Fetch Comments

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {
    author: .author.displayName,
    created: .created[:10],
    body: .body
  }'

Add a Comment

curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "version": 1,
      "type": "doc",
      "content": [{
        "type": "paragraph",
        "content": [{"type": "text", "text": "Your comment here"}]
      }]
    }
  }' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"

Transition a Ticket

# 1. Get available transitions
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'

# 2. Execute transition (replace TRANSITION_ID)
curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transition": {"id": "TRANSITION_ID"}}' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"

Search with JQL

curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \
  "$JIRA_URL/rest/api/3/search"

Analyzing a Ticket

When retrieving a ticket for development or test automation, extract:

1. Testable Requirements

  • Functional requirements — What the feature does
  • Acceptance criteria — Conditions that must be met
  • Testable behaviors — Specific actions and expected outcomes
  • User roles — Who uses this feature and their permissions
  • Data requirements — What data is needed
  • Integration points — APIs, services, or systems involved

2. Test Types Needed

  • Unit tests — Individual functions and utilities
  • Integration tests — API endpoints and service interactions
  • E2E tests — User-facing UI flows
  • API tests — Endpoint contracts and error handling

3. Edge Cases & Error Scenarios

  • Invalid inputs (empty, too long, special characters)
  • Unauthorized access
  • Network failures or timeouts
  • Concurrent users or race conditions
  • Boundary conditions
  • Missing or null data
  • State transitions (back navigation, refresh, etc.)

4. Structured Analysis Output

Ticket: PROJ-1234
Summary: [ticket title]
Status: [current status]
Priority: [High/Medium/Low]
Test Types: Unit, Integration, E2E

Requirements:
1. [requirement 1]
2. [requirement 2]

Acceptance Criteria:
- [ ] [criterion 1]
- [ ] [criterion 2]

Test Scenarios:
- Happy Path: [description]
- Error Case: [description]
- Edge Case: [description]

Test Data Needed:
- [data item 1]
- [data item 2]

Dependencies:
- [dependency 1]
- [dependency 2]

Updating Tickets

When to Update

Workflow Step Jira Update
Start work Transition to "In Progress"
Tests written Comment with test coverage summary
Branch created Comment with branch name
PR/MR created Comment with link, link issue
Tests passing Comment with results summary
PR/MR merged Transition to "Done" or "In Review"

Comment Templates

Starting Work:

Starting implementation for this ticket.
Branch: feat/PROJ-1234-feature-name

Tests Implemented:

Automated tests implemented:

Unit Tests:
- [test file 1] — [what it covers]
- [test file 2] — [what it covers]

Integration Tests:
- [test file] — [endpoints/flows covered]

All tests passing locally. Coverage: XX%

PR Created:

Pull request created:
[PR Title](https://github.com/org/repo/pull/XXX)

Ready for review.

Work Complete:

Implementation complete.

PR merged: [link]
Test results: All passing (X/Y)
Coverage: XX%

Security Guidelines

  • Never hardcode Jira API tokens in source code or skill files
  • Always use environment variables or a secrets manager
  • Add .env to .gitignore in every project
  • Rotate tokens immediately if exposed in git history
  • Use least-privilege API tokens scoped to required projects
  • Validate that credentials are set before making API calls — fail fast with a clear message

Troubleshooting

Error Cause Fix
401 Unauthorized Invalid or expired API token Regenerate at id.atlassian.com
403 Forbidden Token lacks project permissions Check token scopes and project access
404 Not Found Wrong ticket key or base URL Verify JIRA_URL and ticket key
spawn uvx ENOENT IDE cannot find uvx on PATH Use full path (e.g., ~/.local/bin/uvx) or set PATH in ~/.zprofile
Connection timeout Network/VPN issue Check VPN connection and firewall rules

Best Practices

  • Update Jira as you go, not all at once at the end
  • Keep comments concise but informative
  • Link rather than copy — point to PRs, test reports, and dashboards
  • Use @mentions if you need input from others
  • Check linked issues to understand full feature scope before starting
  • If acceptance criteria are vague, ask for clarification before writing code

04 同仓库更多 Skills

agisota
agisota/old-one

zoom-out

Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.

★ 3
agisota
agisota/old-one

zeroize-audit

Detects missing zeroization of sensitive data in source code and identifies zeroization removed by compiler optimizations, with assembly-level analysis, and control-flow verification. Use for auditing C/C++/Rust code handling secrets, keys, passwords, or other sensitive data.

★ 3
agisota
agisota/old-one

yeet

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

★ 3
agisota
agisota/old-one

yara-rule-authoring

Guides authoring of high-quality YARA-X detection rules for malware identification. Use when writing, reviewing, or optimizing YARA rules. Covers naming conventions, string selection, performance optimization, migration from legacy YARA, and false positive reduction. Triggers on: YARA, YARA-X, malware detection, threat hunting, IOC, signature, crx module, dex module.

★ 3
agisota
agisota/old-one

x-twitter-growth

X/Twitter growth engine for building audience, crafting viral content, and analyzing engagement. Use when the user wants to grow on X/Twitter, write tweets or threads, analyze their X profile, research competitors on X, plan a posting strategy, or optimize engagement. Complements social-content (generic multi-platform) with X-specific depth: algorithm mechanics, thread engineering, reply strategy, profile optimization, and competitive intelligence via web search.

★ 3
agisota
agisota/old-one

x-api

X/Twitter API integration for posting tweets, threads, reading timelines, search, and analytics. Covers OAuth auth patterns, rate limits, and platform-native content posting. Use when the user wants to interact with X programmatically.

★ 3