Agent-Skills.md

Agent Skills: JIRA Skill

Use when needing to search Jira issues, retrieve issue details, get pull request links, or manage issue workflows programmatically - provides complete workflows and examples for common Jira automation tasks using the atlassian CLI

UncategorizedID: zenobi-us/dotfiles/reading-and-writing-jira-tickets

Repository

zenobi-us/dotfiles
zenobi-usLicense: MIT
676

Install this agent skill to your local

pnpm dlx add-skill https://github.com/zenobi-us/dotfiles/tree/HEAD/devtools/files/pi/agent/bundles/business/skills/projectmanagement/reading-and-writing-jira-tickets

Skill Files

Browse the full folder contents for reading-and-writing-jira-tickets.

Download Skill

Loading file tree…

devtools/files/pi/agent/bundles/business/skills/projectmanagement/reading-and-writing-jira-tickets/SKILL.md

Skill Metadata

Name
reading-and-writing-jira-tickets
Description
Use when needing to search Jira issues, retrieve issue details, get pull request links, or manage issue workflows programmatically - provides complete workflows and examples for common Jira automation tasks using the atlassian CLI

JIRA Skill

Master Jira automation and integration using the atlassian MCP server. This skill enables programmatic access to Jira issues, projects, and metadata.

[!CRITICAL] ⚠️ IMPORTANT - Parameter Passing:

Use function-call syntax (NOT flag syntax). Parameters go inside the function call, not as flags:

mcporter call 'atlassian.functionName(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", fields: ["key", "summary"])'

Key Rules:

  • Parameters are camelCase inside the function call
  • String values use double quotes: "value"
  • Array values use bracket notation: ["item1", "item2"]
  • Object values use object notation: {key: "value"}
  • Environment variables are interpolated outside quotes: "'$VAR'"
  • NO --flag syntax, NO JSON string escaping needed

Quick Setup

Get Ticket Summary (One-Shot)

The fastest way to get ticket information:

mise x node@20 -- ./scripts/get_ticket_summary.sh TICKET-123

Returns human-readable summary with:

  • Key, summary, type, status, priority, assignee
  • Created/updated timestamps
  • Full description
  • Linked resources (PRs, etc.)
  • Direct link to Jira

JSON output for parsing:

mise x node@20 -- ./scripts/get_ticket_summary.sh TICKET-123 --json

Returns structured JSON with ticket and remoteLinks objects.

Get Current User Info

mise x node@20 -- ./scripts/get_current_user.sh

Returns: accountId, displayName, email

Or get specific fields:

mise x node@20 -- ./scripts/get_current_user.sh --account-id
mise x node@20 -- ./scripts/get_current_user.sh --email
mise x node@20 -- ./scripts/get_current_user.sh --display-name

Get Cloud ID (Required for all operations)

export JIRA_CLOUD_ID=$(mise x node@20 -- ./scripts/get_cloud_id.sh)
export JIRA_URL=$(mise x node@20 -- ./scripts/get_cloud_id.sh --url)

This sets up environment variables for all subsequent mcporter calls.

Core Operations

Search Issues

mise x node@20 -- mcporter call 'atlassian.searchJiraIssuesUsingJql(cloudId: "'$JIRA_CLOUD_ID'", jql: "assignee = currentUser() AND status = Open")'

With specific fields:

mise x node@20 -- mcporter call 'atlassian.searchJiraIssuesUsingJql(cloudId: "'$JIRA_CLOUD_ID'", jql: "assignee = currentUser()", fields: ["key", "summary", "status", "assignee"])'

With pagination:

mise x node@20 -- mcporter call 'atlassian.searchJiraIssuesUsingJql(cloudId: "'$JIRA_CLOUD_ID'", jql: "assignee = currentUser()", maxResults: 50)'

Returns: issues[] array with key, fields.summary, fields.status.name

Common JQL:

  • assignee = currentUser() - Issues assigned to you
  • status = Open - Filter by status
  • project = PROJ - Specific project
  • updated >= -7d - Updated in last 7 days
  • issuetype = Bug - Specific issue type

Get Issue Details

mise x node@20 -- mcporter call 'atlassian.getJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123")'

With specific fields:

mise x node@20 -- mcporter call 'atlassian.getJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", fields: ["key", "summary", "status", "assignee", "description"])'

With expand for additional details:

mise x node@20 -- mcporter call 'atlassian.getJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", expand: ["changelog", "editmeta"])'

Returns: Full issue object with key, fields (summary, status, assignee, description, etc)

Get Issue Transitions

mise x node@20 -- mcporter call 'atlassian.getTransitionsForJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123")'

Returns: List of available transitions with IDs and names for workflow state changes

Transition Issue to New Status

mise x node@20 -- mcporter call 'atlassian.transitionJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", transition: {id: "11"})'

With field updates:

mise x node@20 -- mcporter call 'atlassian.transitionJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", transition: {id: "11"}, fields: {assignee: {id: "USER_ID"}})'

Get Project Metadata

mise x node@20 -- mcporter call 'atlassian.getJiraProjectIssueTypesMetadata(cloudId: "'$JIRA_CLOUD_ID'", projectIdOrKey: "PROJ")'

Edit Jira Issue Fields

TODO: Add example for updating fields on an issue

Add Comment to Issue

mise x node@20 -- mcporter call 'atlassian.addCommentToJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", commentBody: "Your comment here")'

With GitHub permalink:

mise x node@20 -- mcporter call 'atlassian.addCommentToJiraIssue(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123", commentBody: "See implementation details:\n\nhttps://github.com/owner/repo/blob/commit-hash/path/to/file.ts#L123")'

Returns: Comment object with id, body, author, created, updated

Create New Issue

TODO: Add example for creating a new issue

Get Issue Type Metadata

mise x node@20 -- mcporter call 'atlassian.getJiraIssueTypeMetaWithFields(cloudId: "'$JIRA_CLOUD_ID'", projectIdOrKey: "PROJ", issueTypeId: "10001")'

Get Related Links (PRs, Confluence, etc)

mise x node@20 -- mcporter call 'atlassian.getJiraIssueRemoteIssueLinks(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123")'

Returns: remoteIssueLinks[] array with linked resources

Filter for GitHub PRs:

mise x node@20 -- mcporter call 'atlassian.getJiraIssueRemoteIssueLinks(cloudId: "'$JIRA_CLOUD_ID'", issueIdOrKey: "PROJ-123")' | \
  jq '.[]? | select(.type.name == "GitHub" or (.globalId | contains("github"))) | .object.url'

Helper Scripts

| Script | Purpose | |--------|---------| | ./scripts/get_ticket_summary.sh | One-shot ticket summary - Get all ticket info in one call (human or JSON format) | | ./scripts/get_current_user.sh | Get authenticated user info (accountId, displayName, email) | | ./scripts/get_cloud_id.sh | Get Jira Cloud ID and URL |

Common Issues & Solutions

| Problem | Solution | |---------|----------| | No cloud ID available | Run ./scripts/get_cloud_id.sh to fetch and export it | | Need current user info | Use ./scripts/get_current_user.sh to fetch accountId, displayName, email | | Search returns 0 results | Verify JQL syntax. Try status = Open instead of status = "To Do". Test queries in Jira UI first. | | PR link not found in remoteIssueLinks | Not all PRs auto-link. Check if "Link" was created in GitHub/Jira. | | Transition fails with "Cannot transition" | Wrong transition ID. Always run getTransitionsForJiraIssue first to see valid transitions for current status. | | "Invalid arguments" or command fails | Use function-call syntax, NOT flag syntax. Parameters go inside functionName(param: value) not --param value | | Arrays not working | Use bracket notation inside function call: fields: ["key", "summary"] NOT --fields '["key","summary"]' | | Objects not working | Use object notation inside function call: transition: {id: "11"} NOT --transition '{"id":"11"}' |

Discovering Function Parameters with Schema Introspection

The mcporter CLI can introspect the MCP server schema to discover correct parameters and their types.

List All Available Tools

mise x node@20 -- mcporter list atlassian --json | jq -r ".tools[].name"

Returns:

atlassianUserInfo
getAccessibleAtlassianResources
getConfluenceSpaces
getConfluencePage
getPagesInConfluenceSpace
getConfluencePageFooterComments
getConfluencePageInlineComments
getConfluencePageDescendants
createConfluencePage
updateConfluencePage
createConfluenceFooterComment
createConfluenceInlineComment
searchConfluenceUsingCql
getJiraIssue
editJiraIssue
createJiraIssue
getTransitionsForJiraIssue
transitionJiraIssue
lookupJiraAccountId
searchJiraIssuesUsingJql
addCommentToJiraIssue
addWorklogToJiraIssue
getJiraIssueRemoteIssueLinks
getVisibleJiraProjects
getJiraProjectIssueTypesMetadata
getJiraIssueTypeMetaWithFields
search
fetch

Inspect a Specific Tool Schema

mise x node@20 -- mcporter list atlassian --json | jq '.tools[] | select(.name == "addCommentToJiraIssue")'

This returns the full JSON schema including:

  • inputSchema.properties - All available parameters with types and descriptions
  • inputSchema.required - Which parameters are mandatory
  • options - CLI-specific metadata for each parameter

Filter for just required parameters:

mise x node@20 -- mcporter list atlassian --json | \
  jq '.tools[] | select(.name == "addCommentToJiraIssue") | .inputSchema.required[]'

Get parameter descriptions:

mise x node@20 -- mcporter list atlassian --json | \
  jq '.tools[] | select(.name == "addCommentToJiraIssue") | .inputSchema.properties | to_entries[] | "\(.key): \(.value.description)"'

This introspection approach works for any tool - just change the tool name in the select() filter.

Tips

  • Setup once per session:

    export JIRA_CLOUD_ID=$(mise x node@20 -- ./scripts/get_cloud_id.sh)
export JIRA_URL=$(mise x node@20 -- ./scripts/get_cloud_id.sh --url)

  • Function-call syntax is the mcporter standard - use mcporter call 'func(param: value)' not flags

  • Always use getTransitionsForJiraIssue before transitioning - transition IDs vary by project workflow

  • Interpolate env vars outside the quotes: mcporter call 'func(cloudId: "'$VAR'")' works, but mcporter call 'func(cloudId: "$VAR")' does not

  • Use jq for JSON parsing in shell scripts

  • Use schema introspection when unsure about parameters - mcporter list atlassian --json | jq is your friend

  • See examples/ directory for full workflow examples