From 1b5d3434b58b3ccaf0564d59b3e851378fccff06 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 8 Jun 2026 13:35:16 +0000 Subject: [PATCH] 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 --- .cursor/skills/create-jira-card/SKILL.md | 396 ++++++++++++++++++ .../references/field-templates.md | 138 ++++++ .../references/issue-type-guide.md | 118 ++++++ 3 files changed, 652 insertions(+) create mode 100644 .cursor/skills/create-jira-card/SKILL.md create mode 100644 .cursor/skills/create-jira-card/references/field-templates.md create mode 100644 .cursor/skills/create-jira-card/references/issue-type-guide.md diff --git a/.cursor/skills/create-jira-card/SKILL.md b/.cursor/skills/create-jira-card/SKILL.md new file mode 100644 index 000000000..0a5d38b78 --- /dev/null +++ b/.cursor/skills/create-jira-card/SKILL.md @@ -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 diff --git a/.cursor/skills/create-jira-card/references/field-templates.md b/.cursor/skills/create-jira-card/references/field-templates.md new file mode 100644 index 000000000..1ca2847e9 --- /dev/null +++ b/.cursor/skills/create-jira-card/references/field-templates.md @@ -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) | diff --git a/.cursor/skills/create-jira-card/references/issue-type-guide.md b/.cursor/skills/create-jira-card/references/issue-type-guide.md new file mode 100644 index 000000000..fe762971f --- /dev/null +++ b/.cursor/skills/create-jira-card/references/issue-type-guide.md @@ -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 |