jira · odyssey4me — Claude Code skill for searching and managing Jira issues
A Claude Code skill that talks to the Jira Cloud API: JQL search, issue create and update, comments, child issues. Ships as a Python script with a setup check command.
MIT 139 installs ★ 13 updated 2026-10-25
npx skills add odyssey4me/agent-skills --skill jira -a claude-codeWhat jira does
The jira.py script exposes search, issue get, issue create, issue update, issue comment, and check subcommands.
Jira Cloud only. Auth comes from JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN environment variables or ~/.config/agent-skills/jira.yaml; the Atlassian API token is generated in account security settings. Outbound HTTPS to the Jira host must be allowed before the first remote call — the skill does not grant network access itself.
Search takes a JQL string, contributor, team, and project filters, plus --max-results (default 50). Batch-read multiple issues in one call, create from a markdown file with --from-file, and --contributors walks every comment to report reporter, assignee, and commenter roles. Python dependencies are requests, keyring, pyyaml, pyadf.
What it helps with
- find open issues in a project with JQL
- create a ticket from a markdown file
- collect all comment authors from a long thread
- update summary, priority, story points, or parent
- verify Jira connectivity before running queries
Example prompts for the agent
- Search project DEMO for open issues and list them with assignee and status
- Create a Story under EPIC-123 using the description in issue.md
- Comment on DEMO-123 that the deploy finished successfully
How to install jira
1Skills CLI (Vercel)
npx skills add odyssey4me/agent-skills --skill jira -a claude-code2Manually: put the files in place
~/.claude/skills/jira/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/jira/
1Skills CLI (Vercel)
npx skills add odyssey4me/agent-skills --skill jira -a codex2Manually: put the files in place
.agents/skills/jira/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add odyssey4me/agent-skills --skill jira -a cursor2Manually: put the files in place
.cursor/skills/jira/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install odyssey4me/agent-skills skills/jira2Manually: put the files in place
.github/skills/jira/SKILL.md1Skills CLI (Vercel)
npx skills add odyssey4me/agent-skills --skill jira -a gemini-cli2Platform CLI
gemini skills install https://github.com/odyssey4me/agent-skills --path skills/jiraManually: put the files in place
.devin/skills/jira/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add odyssey4me/agent-skills --skill jira -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about jira
How do I install the jira skill in Claude Code?
Run npx skills add odyssey4me/agent-skills --skill jira -a claude-code, then open ~/.claude/skills/jira/SKILL.md.
What does the jira skill do?
Searches issues with JQL, creates and updates tickets, reads comments and children, and checks setup with a single check command.
What credentials does it need?
Jira Cloud URL, Atlassian account email, and an API token from id.atlassian.com. Python packages requests, keyring, pyyaml, pyadf must be installed first.
Source text
SKILL.md · MIT
--- name: jira description: Search and manage Jira issues using JQL queries, create/update tickets, and manage workflows. Use when asked to find Jira tickets, check the backlog, manage sprints, track bugs, or work with Atlassian project management. metadata: author: odyssey4me version: "1.3.0" category: project-management tags: "issues, agile, sprints" complexity: standard license: MIT --- # Jira Interact with Jira for issue tracking, search, and workflow management. ## Resolving script paths `SKILL_DIR` in the examples is the directory containing this loaded `SKILL.md`. Set it to that absolute path before running commands; do not assume the agent sets this shell variable. Quote the script path if it contains spaces. ## Installation 1. **Install Python dependencies**: ```bash pip install --user requests keyring pyyaml pyadf ``` 2. **Download the skill** from [Releases](https://github.com/odyssey4me/agent-skills/releases) or use directly from this repository. ## Setup Verification After installation, verify the skill configuration by running: ```bash $SKILL_DIR/scripts/jira.py check ``` This will check: - Python dependencies (requests, keyring, pyyaml, pyadf) - Authentication configuration - Connectivity to Jira If anything is missing, the check command will provide setup instructions. ## Network access Jira API commands require outbound HTTPS to the configured Jira host. Remote operations require outbound network access. If the agent environment restricts it, obtain access through that environment's approval or network controls before the first remote command, reusing authorization already granted. Local help and file processing do not need network access. Skill instructions do not grant network permission. Report DNS, connection, and timeout failures as network errors; do not reset credentials to resolve them. If approved access also fails, stop and report it. Authentication and permission errors require user action. ## Authentication This skill supports Jira Cloud only. Configure Jira authentication using one of these methods: ### Option 1: Environment Variables (Recommended) ```bash export JIRA_BASE_URL="https://yourcompany.atlassian.net" export JIRA_EMAIL="[email protected]" export JIRA_API_TOKEN="your-token" ``` Add these to your `~/.bashrc` or `~/.zshrc` for persistence. ### Option 2: Config File Create `~/.config/agent-skills/jira.yaml`: ```yaml url: https://yourcompany.atlassian.net email: [email protected] token: your-token ``` ### Required Credentials - **URL**: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`) - **Email**: Your Atlassian account email - **API Token**: Create at https://id.atlassian.com/manage-profile/security/api-tokens ## Configuration Defaults Optionally configure defaults (JQL scope, fields, custom fields, project defaults) in `~/.config/agent-skills/jira.yaml`. CLI arguments always override config defaults. See [configuration.md](references/configuration.md) for the full config format and defaults behavior. ```bash # Show all configuration $SKILL_DIR/scripts/jira.py config show # Show project-specific defaults $SKILL_DIR/scripts/jira.py config show --project DEMO ``` ## Commands See [permissions.md](references/permissions.md) for read/write classification of each command. ### check Verify configuration and connectivity. ```bash $SKILL_DIR/scripts/jira.py check ``` This validates: - Python dependencies are installed - Authentication is configured - Can reach the Jira Cloud API - Automation API access - Custom field mappings ### search Search for issues using JQL (Jira Query Language). ```bash $SKILL_DIR/scripts/jira.py search "project = DEMO AND status = Open" $SKILL_DIR/scripts/jira.py search "assignee = currentUser() ORDER BY updated DESC" --max-results 20 ``` **Arguments:** - `jql`: JQL query string (required unless `--contributor`, `--team`, or `--team-name` is used) - `--contributor`: Search for issues where this user is a contributor (reporter, assignee, or updater). Prefer an accountId or exact email; display names can be ambiguous. - `--project`: Project key to scope a `--contributor` search - `--max-results`: Maximum number of results (default: 50) - `--fields`: Comma-separated list of fields to include - `--team`: Team ID to scope the search; repeatable - `--team-name`: Team name to resolve (shared teams only); repeatable Text output renders summary, type, parent, status, resolution and assignee; use `--json` for other fields. Bulk comment authors: see [examples.md](references/examples.md#collect-comment-authors-in-bulk). **JQL patterns:** See [jql-reference.md](references/jql-reference.md) for Cloud-native JQL patterns (status, dates, fields, ordering, linked issues, hierarchy). ### issue Get, create, update, or comment on issues. ```bash # Get issue details (--fields, --contributors) $SKILL_DIR/scripts/jira.py issue get DEMO-123 $SKILL_DIR/scripts/jira.py issue get DEMO-123 --fields "summary,status,assignee" --contributors # Batch several issues into one search call $SKILL_DIR/scripts/jira.py issue get DEMO-1,DEMO-2,DEMO-3 --contributors # List comments $SKILL_DIR/scripts/jira.py issue comments DEMO-123 # List child issues and subtasks, or only their distinct assignees $SKILL_DIR/scripts/jira.py issue children EPIC-123 $SKILL_DIR/scripts/jira.py issue children EPIC-123 --assignees-only $SKILL_DIR/scripts/jira.py issue children EPIC-1,EPIC-2 --assignees-only # Create (--project, --type, --summary required; --description, --priority, --labels, --assignee, --parent, --set-field, --link, --from-file, --json) $SKILL_DIR/scripts/jira.py issue create --project DEMO --type Task --summary "New task" $SKILL_DIR/scripts/jira.py issue create --project DEMO --type Story --summary "New story" --parent EPIC-123 $SKILL_DIR/scripts/jira.py issue create --from-file issue.md --priority Critical # Update (--summary, --description, --priority, --labels, --assignee, --parent, --remove-parent, --set-field, --link, --unlink, --from-file) $SKILL_DIR/scripts/jira.py issue update DEMO-123 --summary "Updated" --set-field story_points=5 $SKILL_DIR/scripts/jira.py issue update DEMO-123 --parent EPIC-456 $SKILL_DIR/scripts/jira.py issue update DEMO-123 --remove-parent $SKILL_DIR/scripts/jira.py issue update DEMO-123 --link "Blocks:DEMO-456" $SKILL_DIR/scripts/jira.py issue update DEMO-123 --unlink "Blocks:DEMO-456" # Comment (--security-level for private comments) $SKILL_DIR/scripts/jira.py issue comment DEMO-123 "This is a comment" ``` `--contributors` reports each person with the roles they hold: `reporter`, `assignee`, and `commenter`. Every comment is read, so a commenter late in a long thread is still reported. With `--json`, `_contributors` is `[{"name": "Jane Doe", "roles": ["reporter", "commenter"]}]`. A batch reads the `comment` field from the search result, falls back to the full thread when the page is truncated, and uses the default fields (no description, issue links or web links); pass `--fields` to request more. `issue children --assignees-only` prints just the distinct assignee names — the cheap way to get the collaborator set. See [from-file-format.md](references/from-file-format.md) for the `--from-file` markdown format and [examples.md](references/examples.md) for more patterns. ### transitions Manage issue workflow transitions. ```bash # List available transitions $SKILL_DIR/scripts/jira.py transitions list DEMO-123 # Transition issue $SKILL_DIR/scripts/jira.py transitions do DEMO-123 "In Progress" $SKILL_DIR/scripts/jira.py transitions do DEMO-123 "Done" --comment "Completed" # Transition with private comment $SKILL_DIR/scripts/jira.py transitions do DEMO-123 "Done" --comment "Internal resolution notes" --security-level "Internal" ``` ### Additional Commands See [advanced-commands.md](references/advanced-commands.md) for full documentation of these commands: - **config** — view/manage configuration defaults and discover custom field mappings - **fields** — list available fields (global or per project/issue type) - **statuses** — list statuses and status categories - **user** — search users by email/name (returns accountId on Cloud) - **collaboration** — discover cross-team collaboration patterns across issue types - **automations** — list and inspect Jira automation rules (Cloud-only) - **versions** — list project versions (releases) and view release reports ## JQL Reference Common JQL queries and patterns: see [jql-reference.md](references/jql-reference.md). Quick reference — combine with `AND`, `OR`, and `ORDER BY`: ```jql assignee = currentUser() AND statusCategory != Done ORDER BY priority DESC ``` Use `statusCategory` (`"To Do"`, `"In Progress"`, `Done`) for queries that work across projects. ## Examples Common Jira workflows: **Search and view:** ```bash # Find all open tasks assigned to you jira search "assignee = currentUser() AND status = Open" # Get issue details jira issue get DEMO-123 --fields "summary,status,assignee" # List issue comments jira issue comments DEMO-123 ``` **Create and update:** ```bash # Create a new bug jira issue create --project DEMO --type Bug --summary "Login page broken" # Create a story under an epic jira issue create --project DEMO --type Story --summary "Implement feature" --parent EPIC-123 # Set or change an issue's parent (works for any hierarchy level) jira issue update DEMO-123 --parent EPIC-456 # Remove an issue's parent jira issue update DEMO-123 --remove-parent # Update an issue and add a comment jira issue update DEMO-123 --priority High --assignee "[email protected]" jira issue comment DEMO-123 "Assigned to review" ``` **Workflow:** ```bash # List available transitions jira transitions list DEMO-123 # Move issue to Done jira transitions do DEMO-123 "Done" --comment "Completed" ``` ## Model Guidance This skill makes API calls requiring structured input/output. A standard-capability model is recommended.
© odyssey4me · MIT · odyssey4me/agent-skills
Similar skills
All skills for Agent setup: memory, context, orchestration →jira by other authors comes first.