Add create-jira-card skill for Jira issue creation

Introduces a project-level Cursor skill that guides agents through
creating well-structured Jira cards from natural language requests.
Includes workflow for drafting, confirming, and creating issues with
proper issue type selection, assignee lookup, and field templates.

Co-authored-by: ScottGits <ScottGits@users.noreply.github.com>
This commit is contained in:
Cursor Agent 2026-06-08 13:35:16 +00:00
parent af1cd602a3
commit 1b5d3434b5
No known key found for this signature in database
3 changed files with 652 additions and 0 deletions

View file

@ -0,0 +1,396 @@
---
name: create-jira-card
description: "Create well-structured Jira issues (cards) from natural language requests. When Claude needs to: (1) Create a Jira card, issue, ticket, story, task, bug, or epic, (2) File work in Jira from a description or conversation, (3) Create multiple Jira issues from a list or notes, (4) Add a card to an existing epic or sprint, or (5) Draft and create a Jira issue with assignee, priority, and labels. Gathers context, selects the right issue type, handles required fields, and confirms before creating."
---
# Create Jira Card
## Keywords
create jira card, create jira issue, create ticket, file a ticket, new jira card, new story, new task, new bug, new epic, log a ticket, add to jira, create issue in jira, make a jira ticket, open a ticket, jira card creation, bulk create issues, create multiple tickets
## Overview
Create individual or multiple Jira issues from natural language requests. This skill handles the full card-creation workflow: gathering context, selecting the right issue type, drafting a clear summary and description, resolving assignees and custom fields, and creating the issue after user confirmation.
**Use this skill when:** The user wants to create one or more Jira cards from a description, request, or list — without the specialized workflows covered by other skills.
**Do NOT use this skill for:**
- Bug triage or duplicate checking → use `triage-issue`
- Meeting notes with action items → use `capture-tasks-from-meeting-notes`
- Confluence specs → full backlog with Epic → use `spec-to-backlog`
- Status reports → use `generate-status-report`
---
## Workflow
Follow this 6-step process:
1. **Understand the request** — Parse what the user wants created
2. **Resolve project context** — Identify project, issue type, and parent links
3. **Draft the card(s)** — Write summary, description, and metadata
4. **Present for confirmation** — Show draft(s) before creating anything
5. **Create in Jira** — Call MCP tools to create issue(s)
6. **Confirm and link** — Return keys, URLs, and next steps
---
## Step 1: Understand the Request
Extract as much as possible from the user's message before asking questions.
### Extract These Elements
| Element | How to infer |
|---------|--------------|
| **Summary** | Main action or title the user provides |
| **Issue type** | Keywords: bug/error → Bug; feature/user story → Story; work item → Task; large initiative → Epic |
| **Project** | Explicit key (e.g., CASH, PROJ) or project name |
| **Assignee** | @mention, "assign to X", or "for Sarah" |
| **Priority** | urgent/critical → High; nice-to-have → Low |
| **Parent** | "under epic PROJ-123", "subtask of PROJ-456" |
| **Labels / components** | Any tags or area names mentioned |
| **Bulk items** | Numbered lists, bullet lists, or "create 3 tickets for..." |
### Ask Only for Missing Critical Info
If the user gave enough to draft a card, draft it and ask for confirmation. Only ask upfront when truly blocked:
- **No project and can't infer:** "Which Jira project should I create this in?"
- **Ambiguous issue type with very little context:** "Should this be a Story, Task, or Bug?"
- **Bulk without project:** "Which project for all of these?"
Do not ask for every optional field. Use sensible defaults and let the user adjust in the confirmation step.
---
## Step 2: Resolve Project Context
### Get Cloud ID
If not already known, call `getAccessibleAtlassianResources` to obtain the `cloudId` for the user's Atlassian site.
### Resolve Project Key
**If user provided a key:** Use it directly (e.g., `CASH`, `PROJ`).
**If user provided a name or is unsure:**
```
getVisibleJiraProjects(
cloudId="...",
action="create"
)
```
Present matching projects and confirm the key.
### Check Available Issue Types
Always check issue types before creating:
```
getJiraProjectIssueTypesMetadata(
cloudId="...",
projectIdOrKey="PROJ"
)
```
**Issue type selection guide** (see `references/issue-type-guide.md` for detail):
| User intent | Preferred type |
|-------------|----------------|
| Defect, error, broken behavior | Bug |
| User-facing feature or capability | Story |
| Technical work, chore, investigation | Task |
| Large body of work spanning multiple tickets | Epic |
| Work under an existing issue | Sub-task (if available) |
**Fallback:** Use the first available non-Epic type, or ask the user if none match.
### Resolve Parent / Epic Link
If the user references a parent epic or issue:
- Use the `parent` parameter when creating child issues
- Verify the parent key exists with `getJiraIssue` if uncertain
### Resolve Assignee
If an assignee is mentioned:
```
lookupJiraAccountId(
cloudId="...",
searchString="Sarah Johnson"
)
```
Handle 0, 1, or multiple matches per the patterns in `capture-tasks-from-meeting-notes`.
---
## Step 3: Draft the Card(s)
Write a clear summary and description before calling any create API.
### Summary Format
**Pattern:** `[Component/Area]: [Action] — [Brief context]`
**Good examples:**
- `Schedule page: Fix mobile recal loop on date change`
- `Payment: Add Afterpay breakout when deductible > 0`
- `Auth API: Implement token refresh endpoint`
**Bad examples:**
- `Bug` (not actionable)
- `Fix the thing` (too vague)
- Full paragraph in summary (belongs in description)
Keep summaries under ~100 characters when possible.
### Description Templates
Use templates from `references/field-templates.md` based on issue type. At minimum include:
- **Context** — Why this work exists
- **Requirements or steps** — What needs to happen
- **Acceptance criteria** — How to know it's done (for Stories/Tasks)
### Optional Metadata
Include in `additional_fields` when the user specifies or the project requires:
| Field | Example `additional_fields` value |
|-------|-----------------------------------|
| Priority | `{"priority": {"name": "High"}}` |
| Labels | `{"labels": ["frontend", "mobile"]}` |
| Components | `{"components": [{"name": "Checkout"}]}` |
### Bulk Creation
When the user provides multiple items:
1. Draft each card separately with its own summary and type
2. Number them in the confirmation preview
3. Create sequentially, tracking each returned key
---
## Step 4: Present for Confirmation
**CRITICAL:** Always show the draft and wait for user approval before calling `createJiraIssue`.
### Single Card Format
```
Here's the Jira card I'll create:
**Project:** CASH
**Type:** Story
**Summary:** Schedule page: Fix mobile recal loop on date change
**Assignee:** Sarah Johnson
**Priority:** High
**Parent Epic:** CASH-1234
**Description:**
[Rendered description preview]
Shall I create this card?
```
### Bulk Format
```
I'll create 3 cards in CASH:
1. **[Story]** Schedule page: Fix mobile recal loop
Assignee: Sarah | Epic: CASH-1234
2. **[Task]** Add unit tests for schedule recal logic
Assignee: Mike
3. **[Bug]** Payment summary shows wrong deductible on mobile
Priority: High
Create all 3, or would you like to change anything?
```
### User Can
- Confirm → proceed to Step 5
- Edit summary, type, assignee, or priority → update draft and re-present
- Skip items in a bulk list → create only selected ones
- Cancel → stop without creating
---
## Step 5: Create in Jira
### Single Issue
```
createJiraIssue(
cloudId="...",
projectKey="PROJ",
issueTypeName="Story",
summary="Schedule page: Fix mobile recal loop on date change",
description="[markdown description]",
assignee_account_id="[accountId if resolved]",
parent="CASH-1234",
additional_fields={
"priority": {"name": "High"},
"labels": ["mobile", "schedule"]
}
)
```
### Epic Creation
When creating an Epic (not part of a bulk backlog — use `spec-to-backlog` for that):
```
createJiraIssue(
cloudId="...",
projectKey="PROJ",
issueTypeName="Epic",
summary="Mobile Schedule Experience Improvements",
description="[epic description with objectives and success criteria]"
)
```
Save the returned Epic key if follow-up child cards are requested in the same session.
### Handle Required Field Errors
If creation fails due to missing required fields:
1. Fetch field metadata:
```
getJiraIssueTypeMetaWithFields(
cloudId="...",
projectIdOrKey="PROJ",
issueTypeId="10001"
)
```
2. Ask the user for required values
3. Retry with `additional_fields`
### Handle Permission Errors
If creation fails with permission errors, inform the user clearly:
- They may lack create permission in that project
- The MCP app may need admin authorization
- Suggest trying a different project or contacting a Jira admin
---
## Step 6: Confirm and Link
After successful creation, return a concise summary.
### Single Card
```
✅ **Jira card created**
**CASH-2564** — Schedule page: Fix mobile recal loop on date change
Type: Story | Priority: High | Assignee: Sarah Johnson
https://yoursite.atlassian.net/browse/CASH-2564
**Next steps:**
- Add story points or sprint if needed
- Link related issues
- Attach designs or logs if you have them
```
### Bulk Creation
```
✅ **Created 3 cards in CASH:**
1. **CASH-2564** — Schedule page: Fix mobile recal loop
https://yoursite.atlassian.net/browse/CASH-2564
2. **CASH-2565** — Add unit tests for schedule recal logic
https://yoursite.atlassian.net/browse/CASH-2565
3. **CASH-2566** — Payment summary shows wrong deductible on mobile
https://yoursite.atlassian.net/browse/CASH-2566
```
---
## Edge Cases
### User Says "Create a Ticket" With Minimal Detail
Draft the best card you can from context (including conversation history and open files), present it, and ask the user to refine:
```
Based on our conversation, here's a draft card:
**Summary:** [inferred from context]
**Description:** [what I understood from the discussion]
Is this right, or what should I change?
```
### Linking to Existing Work
If the user wants to link (not parent) to another issue, note that link creation may require a separate MCP call or manual step in Jira. Mention related issue keys in the description under a **Related** section.
### Subtasks
Subtasks require a parent issue key, not an Epic key (unless the project uses a flat hierarchy). Confirm the parent issue before creating.
### Duplicate Concerns
This skill does not perform full duplicate triage. If the user asks "is this already filed?" or provides an error to triage, switch to `triage-issue`. For a quick sanity check, you may run one JQL search:
```
searchJiraIssuesUsingJql(
cloudId="...",
jql='project = "PROJ" AND summary ~ "keywords" ORDER BY created DESC',
fields=["summary", "status", "assignee"],
maxResults=5
)
```
Mention any close matches in the confirmation step.
---
## Tips
### Do
- Infer project and type from conversation context when reasonable
- Present drafts before creating
- Use action verbs in summaries
- Include acceptance criteria for Stories and Tasks
- Look up assignees by name when mentioned
- Check issue type availability per project
### Don't
- Create issues without user confirmation
- Use vague summaries like "New task" or "Fix bug"
- Assume project key — verify or ask
- Hard-code issue types without checking metadata
- Use this skill for full spec-to-backlog breakdowns
---
## Quick Reference
| Step | Tool |
|------|------|
| Get cloud ID | `getAccessibleAtlassianResources` |
| List projects | `getVisibleJiraProjects(cloudId, action="create")` |
| Issue types | `getJiraProjectIssueTypesMetadata(cloudId, projectIdOrKey)` |
| Required fields | `getJiraIssueTypeMetaWithFields(cloudId, projectIdOrKey, issueTypeId)` |
| Assignee lookup | `lookupJiraAccountId(cloudId, searchString)` |
| Create issue | `createJiraIssue(...)` |
| Quick duplicate check | `searchJiraIssuesUsingJql(cloudId, jql, fields, maxResults)` |
**Workflow:** Understand → Resolve context → Draft → Confirm → Create → Summarize
**References:**
- `references/issue-type-guide.md` — Choosing Story vs Task vs Bug vs Epic
- `references/field-templates.md` — Description templates by issue type

View file

@ -0,0 +1,138 @@
# Jira Card Description Templates
Copy and adapt the template that matches the issue type.
---
## Story Template
```markdown
## Context
[Why this story matters — user problem or business goal]
## User Story
As a [user type], I want [goal] so that [benefit].
## Requirements
- [Requirement 1]
- [Requirement 2]
## Acceptance Criteria
- [ ] [Testable outcome 1]
- [ ] [Testable outcome 2]
- [ ] [Testable outcome 3]
## Notes
[Any design links, dependencies, or out-of-scope items]
```
---
## Task Template
```markdown
## Context
[Why this task is needed]
## Objective
[What needs to be accomplished]
## Steps
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Acceptance Criteria
- [ ] [Done when...]
- [ ] [Done when...]
## Technical Notes
[Stack, files, or approach hints if known]
```
---
## Bug Template
```markdown
## Description
[1-2 sentences describing the problem]
## Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Expected Behavior
[What should happen]
## Actual Behavior
[What happens instead]
## Environment
- **Platform:** [Web / iOS / Android / API]
- **Browser/OS:** [if applicable]
- **Environment:** [Production / Staging / Dev]
## Impact
[Who is affected and how severely]
## Additional Context
[Screenshots, logs, related tickets]
```
---
## Epic Template
```markdown
## Overview
[1-2 sentences on what this epic delivers]
## Objectives
- [Objective 1]
- [Objective 2]
## Success Criteria
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
## Scope
[What's included]
## Out of Scope
- [Explicit exclusions]
## Notes
[Dependencies, timeline, or stakeholders]
```
---
## Minimal Template
Use when the user provides little detail and you need a lightweight card:
```markdown
## Summary
[Restate the work in 1-2 sentences]
## Acceptance Criteria
- [ ] [Primary done condition]
## Notes
[Source: conversation / request on DATE]
```
---
## Summary Formula
**[Area/Component]: [Action verb] [object] — [optional context]**
| Issue type | Verb examples |
|------------|---------------|
| Story | Add, Implement, Build, Enable |
| Task | Configure, Refactor, Document, Investigate |
| Bug | Fix, Resolve, Correct |
| Epic | (noun phrase, no verb required) |

View file

@ -0,0 +1,118 @@
# Issue Type Selection Guide
Use this reference when choosing the right Jira issue type for a card.
---
## Decision Tree
```
Is it a defect or incorrect behavior?
├── Yes → Bug (if available)
└── No → Is it a large initiative with multiple child tickets?
├── Yes → Epic
└── No → Is it user-facing functionality or product value?
├── Yes → Story (if available)
└── No → Is it work under an existing issue?
├── Yes → Sub-task (if available)
└── No → Task
```
---
## Bug
**Use when:**
- Something is broken or behaves incorrectly
- Users see errors, crashes, or wrong data
- Regression of previously working behavior
**Keywords:** bug, fix, broken, error, defect, regression, incorrect, fails, crash, exception
**Summary verbs:** Fix, Resolve, Correct, Debug
**Example summaries:**
- `Checkout: Fix null total when coupon applied`
- `Mobile: Resolve infinite spinner on schedule page`
---
## Story
**Use when:**
- New user-facing feature or capability
- Product enhancement with clear user value
- Work that can be described as "As a user, I want..."
**Keywords:** feature, add, enable, user can, new capability, enhancement, implement UI
**Summary verbs:** Add, Implement, Build, Enable, Create, Introduce
**Example summaries:**
- `Profile: Add email notification preferences`
- `Search: Enable filter by date range`
---
## Task
**Use when:**
- Technical work without direct user-facing outcome
- Refactoring, infrastructure, DevOps, documentation
- Investigation or spike work
- Chores and maintenance
**Keywords:** refactor, configure, setup, migrate, document, investigate, spike, upgrade, optimize
**Summary verbs:** Configure, Refactor, Migrate, Document, Investigate, Upgrade, Optimize
**Example summaries:**
- `CI: Upgrade Node.js to v20 in pipeline`
- `API: Refactor auth middleware for testability`
---
## Epic
**Use when:**
- Work spans multiple stories/tasks over time
- User explicitly asks for an epic
- Large feature area that will have child issues
**Keywords:** epic, initiative, program, large feature, phase
**Do NOT use Epic for:**
- Single tickets (use Story or Task)
- Full spec breakdowns with many tickets (use `spec-to-backlog` skill)
**Summary style:** Noun phrase describing the initiative
- `Mobile Schedule Experience`
- `Payment Gateway Migration`
---
## Sub-task
**Use when:**
- Work is a slice of an existing parent issue
- User says "subtask of PROJ-123"
**Requires:** Valid parent issue key (not Epic key in most Jira configurations)
**Summary style:** Specific action within parent scope
- `Write unit tests for recal logic`
- `Update API contract documentation`
---
## Project-Specific Types
Some teams use custom types (e.g., "Improvement", "Initiative", "Spike"). After calling `getJiraProjectIssueTypesMetadata`, map user intent to the closest available type and confirm with the user if ambiguous.
| Custom type | Usually maps to |
|-------------|-----------------|
| Improvement | Story or Task |
| Initiative | Epic |
| Spike | Task |
| Technical debt | Task |
| Incident | Bug or Task |