home / skills / contextware / skills / jira-issue-manager

jira-issue-manager skill

safe

This skill helps manage Jira issues and list issue types by integrating with Nango proxy for authentication and dynamic cloudId discovery.

npx playbooks add skill contextware/skills --skill jira-issue-manager

Review the files below or copy the command above to add this skill to your agents.

Files (9)

SKILL.md

2.2 KB

---
name: jira-issue-manager
description: 'A skill to manage Jira issues, including listing issue types.'
metadata:
  createdAt: '2026-01-29T16:55:45.735Z'
allowed-tools: []
mcp-servers:
  - nango-mcp-server
depends-on:
  - connect-to-nango-mcp
---
# Jira Issue Manager

This skill helps manage Jira issues. It depends on the `connect-to-nango-mcp` skill for authentication.

## Critical Setup: Discovering Jira Cloud ID

Jira API calls via Nango proxy require a `cloudId` (site ID) in the path. You must discover this dynamically from the connection details before making other calls.

### 1. Discover the Cloud ID

Run the `scripts/get-cloud-id.cjs` script:

```bash
node scripts/get-cloud-id.cjs <NANGO_SECRET_KEY> <connectionId> [provider]
```

Example:
```bash
node scripts/get-cloud-id.cjs cf0e919c-5280-4908-9865-0baa6df2eb10 9072b6a9-a672-4b55-9566-f31a191b341d jira
```

### 2. List Projects (Optional)

To find project IDs or keys:

```bash
node scripts/get-projects.cjs <cloudId> <NANGO_SECRET_KEY> <connectionId> [provider]
```

### 3. Listing Issue Types

To list issue types (globally or for a specific project):

```bash
node scripts/get-issue-types.cjs <cloudId> <NANGO_SECRET_KEY> <connectionId> [provider] [projectId]
```

Example (Global):
```bash
node scripts/get-issue-types.cjs efe59576-1147-4e4b-96b5-7615e308a36b cf0e919c-5280-4908-9865-0baa6df2eb10 9072b6a9-a672-4b55-9566-f31a191b341d jira
```

Example (Project-specific):
```bash
node scripts/get-issue-types.cjs efe59576-1147-4e4b-96b5-7615e308a36b cf0e919c-5280-4908-9865-0baa6df2eb10 9072b6a9-a672-4b55-9566-f31a191b341d jira 10001
```

## Usage

### Creating a Jira Issue

To create a Jira issue, use the `nango-mcp-server_create_issue` tool with the following arguments:

*   `summary`: The summary of the issue.
*   `project`: The project ID (e.g., "10001").
*   `issueType`: The issue type ID (e.g., "10011").

Example:
```json
{
    "summary": "Test issue created by agent",
    "project": "10001",
    "issueType": "10011"
}
```

## Troubleshooting

If you receive a 404 error when calling Jira, verify that the `cloudId` is correct. Some Jira instances might use a different version of the API (v2 vs v3); the scripts default to v3.

Overview

This skill manages Jira issues through a Nango-proxied Jira API, including listing issue types and creating issues. It relies on a Nango-based authentication flow to call Jira on behalf of a connection and handles the necessary Jira cloudId discovery required for API paths.

How this skill works

Before making Jira API calls, the skill dynamically discovers the Jira cloudId from the connection details using the Nango-authenticated endpoint. With the cloudId resolved, it can list projects, list global or project-specific issue types, and create issues by passing the required fields (summary, project, issueType) through the Nango proxy. Error handling highlights common causes like incorrect cloudId or API version mismatches.

When to use it

Automating creation of Jira issues from an agent or integration workflow.
Enumerating available issue types globally or for a specific project before creating issues.
Fetching project lists to map external records to Jira project IDs or keys.
Embedding Jira operations behind Nango for secure, token-managed access.
Validating Jira configuration during onboarding or troubleshooting.

Best practices

Always discover and validate the Jira cloudId before other API calls to avoid 404s.
Use project-specific issue type listing to ensure the selected type is valid for that project.
Keep Nango connection credentials and secret keys secure; pass them only to the authenticated endpoints.
Handle API version differences: verify whether the Jira instance expects v2 or v3 endpoints.
Log and surface meaningful Jira errors (404 cloudId, 403 permission issues) to aid troubleshooting.

Example use cases

List global issue types to present choices in a UI before creating an issue.
List issue types for a given project to populate a project-specific form.
Create a Jira issue with summary, project ID, and issue type from an automated workflow.
Run an onboarding check that lists projects and issue types to confirm integration readiness.

FAQ

What is cloudId and why is it required?

cloudId is the Jira Cloud site identifier required in the API path. It must be discovered dynamically from the Nango connection before other Jira calls.

I get a 404 from Jira — how do I troubleshoot?

First verify the discovered cloudId is correct. Also check whether your Jira instance requires v2 vs v3 API paths and that the Nango connection has proper permissions.