x-create-jira-epic

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

Skill: Create Jira Epic

Purpose

Create a Jira Epic issue from an existing local epic-XXXX.md file. Parse the epic markdown, map fields to Jira issue attributes, create the Epic via MCP, and sync the returned Jira key back to the local file for bidirectional traceability.

Triggers

• /x-create-jira-epic <epic_file_path> — create Jira Epic from the specified file
• User says "create epic in Jira", "sync epic to Jira", or "push epic to Jira"
• After running /x-epic-create or /x-epic-decompose without Jira integration

Parameters

Parameter	Type	Required	Default	Description
EPIC_FILE_PATH	Path	No	—	Path to the epic markdown file (prompted if omitted)

Prerequisites

Read the field mapping reference before creating issues:

• .claude/skills/x-create-jira-epic/references/jira-field-mapping.md

Workflow

Step 1 — Input and Parse

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-create-jira-epic Phase-1-Read-Markdown

1. Accept the epic file path as argument. If not provided, ask:

   question: "Qual o caminho do arquivo do epico? (ex: ai/epics/epic-XXXX/epic-XXXX.md)"
   header: "Epic File"
   

2. Read the epic file completely
3. Extract:
   • Title: From # Epico: <titulo> (line 1)
   • Local ID: From the directory name (epic-XXXX)
   • Overview: From Section 1 (Visao Geral) — all text after **Chave Jira:** line until Section 2
   • Status: From the header **Status:** field
   • Existing Jira Key: From **Chave Jira:** field

Step 2 — Pre-checks

1. Verify mcp__atlassian__createJiraIssue is available. If not:

   ERROR: MCP tool mcp__atlassian__createJiraIssue not available.
   Ensure the Atlassian MCP server is configured in .claude/settings.json.
   

   Abort.

2. Check existing Jira key. If **Chave Jira:** has a real value (not <CHAVE-JIRA> and not —):

   question: "Este epico ja tem chave Jira: {KEY}. O que deseja fazer?"
   header: "Epico ja vinculado ao Jira"
   options:
     - label: "Criar novo epico no Jira"
       description: "Ignorar a chave existente e criar um novo issue"
     - label: "Pular — manter a chave existente"
       description: "Nao criar no Jira, manter o vinculo atual"
   

   If "Pular": exit with message "Epico mantido com chave {KEY}."

Step 3 — Project Selection

1. Call mcp__atlassian__getAccessibleAtlassianResources to discover available Atlassian sites

2. Use the first available site's id as cloudId. If no sites returned:

   ERROR: No accessible Atlassian sites found. Check your Atlassian credentials.
   

   Abort.

3. Call mcp__atlassian__getVisibleJiraProjects with the discovered cloudId

4. Present the project list to the user:

   question: "Selecione o projeto Jira para criar o epico:"
   header: "Projeto Jira"
   options:
     - label: "{PROJECT_KEY} — my-quarkus-service"
       description: "Project key: {PROJECT_KEY}"
     (one option per project)
   

5. Capture the selected projectKey

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-create-jira-epic Phase-1-Read-Markdown ok

Step 4 — Create Epic in Jira

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-create-jira-epic Phase-2-MCP-Call

Wrap the Jira MCP call with mcp-start / mcp-end markers (story-0040-0008 §3.2) so the tool.call event carries tool=mcp__atlassian__createJiraIssue and a measured durationMs:

<!-- TELEMETRY: tool.call mcp-start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh mcp-start x-create-jira-epic createJiraIssue

Call mcp__atlassian__createJiraIssue with:

• cloudId: discovered cloudId
• projectKey: selected project key
• issueTypeName: "Epic"
• summary: epic title (extracted from # Epico: <titulo>)
• description: Section 1 (Visao Geral) text content
• contentFormat: "markdown"
• additional_fields:

  {
    "labels": [
      { "name": "generated-by-ia-dev-env" },
      { "name": "epic-XXXX" }
    ]
  }
  

Where epic-XXXX is the local epic ID (e.g., epic-0012).

<!-- TELEMETRY: tool.call mcp-end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh mcp-end x-create-jira-epic createJiraIssue ok

(On MCP failure, invoke the mcp-end marker with status failed instead of ok so the telemetry record reflects the real outcome — §5.3.)

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-create-jira-epic Phase-2-MCP-Call ok

Step 5 — Sync Jira Key Back to Local File

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-create-jira-epic Phase-3-Sync-Back

1. Capture the returned Jira issue key (e.g., PROJ-123)
2. Read the epic markdown file
3. Replace the **Chave Jira:** value:
   • If current value is <CHAVE-JIRA>: replace with the actual key
   • If current value is —: replace with the actual key
   • If creating a new epic (user chose to ignore existing key): replace with the new key
4. Write the updated file

Step 6 — Report

Output:

Epico criado no Jira: {JIRA_KEY}
Projeto: {PROJECT_KEY}
Arquivo local atualizado: {EPIC_FILE_PATH}
Label de sync: epic-XXXX

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-create-jira-epic Phase-3-Sync-Back ok

Error Handling

Scenario	Action
MCP tool not available	Abort with clear message about MCP configuration
No Atlassian sites found	Abort with credential check message
Issue creation fails	Report the error, do NOT update the local file
File write fails	Report error, mention Jira key was created but local file not updated
Epic file not found	Abort with message: "Epic file not found at {path}"
Epic file unparseable	Abort with message: "Cannot parse epic file — verify format"

Integration Notes

Skill	Relationship	Context
x-epic-create	reads	Reads the epic file generated by this skill
x-epic-decompose	called-by	Orchestrator may invoke this in Phase B
x-create-jira-stories	calls	Creates Jira stories linked to the epic

ID Synchronization Strategy

Bidirectional lookup is enabled by:

• Local to Jira: The local ID (epic-XXXX) is stored as a Jira label
• Jira to Local: The Jira key (e.g., PROJ-123) is stored in the **Chave Jira:** field
• JQL Lookup: labels = "epic-XXXX" AND labels = "generated-by-ia-dev-env"