Create a Jira Epic from an existing local epic markdown file. Read the epic file, map fields to Jira, create the issue via MCP, and sync the Jira key back to the local file.
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.
/x-jira-create-epic <epic_file_path> — create Jira Epic from the specified file/x-epic-create or /x-epic-decompose without Jira integration| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
EPIC_FILE_PATH | Path | No | — | Path to the epic markdown file (prompted if omitted) |
Read the field mapping reference before creating issues:
.claude/skills/x-jira-create-epic/references/jira-field-mapping.mdBash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-jira-create-epic Phase-1-Read-Markdown
question: "Qual o caminho do arquivo do epico? (ex: plans/epic-0012/epic-0012.md)"
header: "Epic File"
# Epico: <titulo> (line 1)epic-XXXX)**Chave Jira:** line until Section 2**Status:** field**Chave Jira:** fieldVerify 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.
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}."
Call mcp__atlassian__getAccessibleAtlassianResources to discover available Atlassian sites
Use the first available site's id as cloudId. If no sites returned:
ERROR: No accessible Atlassian sites found. Check your Atlassian credentials.
Abort.
Call mcp__atlassian__getVisibleJiraProjects with the discovered cloudId
Present the project list to the user:
question: "Selecione o projeto Jira para criar o epico:"
header: "Projeto Jira"
options:
- label: "{PROJECT_KEY} — my-java-cli"
description: "Project key: {PROJECT_KEY}"
(one option per project)
Capture the selected projectKey
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-jira-create-epic Phase-1-Read-Markdown ok
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-jira-create-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:
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh mcp-start x-jira-create-epic createJiraIssue
Call mcp__atlassian__createJiraIssue with:
cloudId: discovered cloudIdprojectKey: selected project keyissueTypeName: "Epic"summary: epic title (extracted from # Epico: <titulo>)description: Section 1 (Visao Geral) text contentcontentFormat: "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).
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh mcp-end x-jira-create-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.)
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-jira-create-epic Phase-2-MCP-Call ok
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-jira-create-epic Phase-3-Sync-Back
PROJ-123)**Chave Jira:** value:
<CHAVE-JIRA>: replace with the actual key—: replace with the actual keyOutput:
Epico criado no Jira: {JIRA_KEY}
Projeto: {PROJECT_KEY}
Arquivo local atualizado: {EPIC_FILE_PATH}
Label de sync: epic-XXXX
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-jira-create-epic Phase-3-Sync-Back ok
| 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" |
| 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-jira-create-stories | calls | Creates Jira stories linked to the epic |
Bidirectional lookup is enabled by:
epic-XXXX) is stored as a Jira labelPROJ-123) is stored in the **Chave Jira:** fieldlabels = "epic-XXXX" AND labels = "generated-by-ia-dev-env"