skills.rest
Gamaroff
GamaroffCOMMUNITY
Explore all skills by this author →
Website𝕏@gamaroffGitHub

sync-jira-bug

Sync local bug report markdown files to Jira issues with create, update, and linking.

2|Updated Feb 14, 2026
Search Tags:#automation#markdown#backlog#sync#jira#bug tracking#issue link
One-click install
npx skills add https://github.com/Gamaroff/agent-skills --skill sync-jira-bug-gamaroff
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sync-jira-bug
Source: https://github.com/Gamaroff/agent-skills/tree/main/skills/sync-jira-bug
Command: npx skills add https://github.com/Gamaroff/agent-skills --skill sync-jira-bug-gamaroff

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Keeping local bug report documents and Jira issues in sync manually is error-prone: duplicate cards get created, parent relationships get lost, and status drift goes unnoticed. This Skill automates the one-way sync of a bug report markdown file to Jira, creating the issue when no jira_key exists and updating it when one does. ## Core Features & Use Cases - Create-or-update detection: Reads the bug file's jira_key to decide between create and update, with idempotent create via a synced-from-* label search so a failed write-back never produces a duplicate card. - Three bug modes inferred from the file path: story bugs, task bugs, and general bugs each get the correct parent linkage as a Jira issue link plus a Source Documents section, without asking the user anything. - Frontmatter adoption and Status History: Files without YAML frontmatter get a minimal block prepended, and Status History rows are written only on issue creation or an actual status transition. - Use Case: After writing a bug report like story.7.4.bug.4.tap-target.md, run the sync to create the Jira bug, link it to the parent story's card, place it in the Scrum backlog, and write the jira_key back into the file. ## Quick Start Ask the agent to sync your bug report to Jira, for example: create this bug in Jira from docs/prd/story.7.4.bug.4.tap-target.md.

Frequently Asked Questions about sync-jira-bug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I sync a bug report markdown file to Jira?▼

Run the sync script with the bug file path, for example node scripts/sync-jira-bug.js --file <bug.md>. The script creates the Jira issue if the file has no jira_key, or updates the existing issue if one is set, then writes the key and URL back into the file.

How does the skill decide between creating and updating a Jira bug?▼

It checks the file's jira_key frontmatter field. If absent, it first searches Jira for an issue carrying the bug's synced-from-* label to avoid duplicates, then creates a new issue only when no match exists.

Does it work with bug files that have no YAML frontmatter?▼

Yes. It parses the **Bug ID**: header block as a fallback, merges it with any frontmatter, and prepends a minimal YAML block seeded from the header values. The document body is preserved verbatim.

Why is the bug linked to its parent as an issue link instead of a sub-task?▼

In team-managed Jira projects a Bug is a standard issue type whose parent field only addresses Epics, and converting it to a sub-task would break backlog placement and status mapping. An issue link works in every project type and is queryable with JQL.

What happens when the Jira issue was edited since the last sync?▼

The concurrent-edit guard compares the Jira updated timestamp against the stored jira_last_synced_at value and aborts the sync if Jira is newer. Re-run with --force to override and overwrite the Jira issue.

When should I not use this skill for Jira sync?▼

Do not use it for stories, tasks, or epics, which have their own sync-jira-story, sync-jira-task, and sync-jira-epic skills. If the project tracks work in GitHub instead of Jira, use sync-github-bug.

Related Skills

Explore More Software Engineering Skills→
brand6brand6

bug-report

Generate structured Markdown bug reports with unique IDs and severity classification.

Community
Advanced
eugenelimeugenelim
15

jira-defect-flow

Coordinate Jira defect handling from intake to pull request and tracker update.

Community
Advanced
patternflypatternfly
10

duplicate-epic

Clone Jira epics into PatternFly Jira and link duplicates via REST API.

Official
Advanced
MohammedSaudAlsahliMohammedSaudAlsahli

project-session-manager

Manage project sessions with git worktrees and tmux.

Community
Advanced