Jira CLI Skill | Agent Skills

Jira CLI

使用本 skill 自带的 scripts/jira_cli.py。当前契约面向 Jira Server/Data Center 8.20.6，不支持 Jira Cloud API v3 或 ADF。

首次配置

默认配置文件为 ~/.config/jira-cli/config.toml。使用 config set 创建或修改配置：

cd skills/jira-cli
./scripts/jira_cli.py config set --default-project SATOS
./scripts/jira_cli.py config set --server https://jira.example --prompt-token
./scripts/jira_cli.py config show

配置文件权限固定为 0600。已有配置只会在显式执行 config set 时更新。

环境变量和全局选项可以临时覆盖配置，但不会反写 TOML：

JIRA_SERVER
JIRA_API_TOKEN
JIRA_USERNAME
JIRA_AUTH_TYPE
JIRA_TIMEOUT
JIRA_DANGEROUSLY_ALLOW_HTTP
JIRA_DANGEROUSLY_DISABLE_TLS_VERIFICATION

默认只允许 HTTPS 并校验 TLS。只有用户明确要求时才使用 --dangerously-allow-http 或 --dangerously-disable-tls-verification；前者会让凭据明文传输。临时 token 只通过 JIRA_API_TOKEN 传入，不接受可能进入 shell history 和进程参数的 --token。

调用约定

从 skill 目录直接执行；全局选项放在子命令之前：

./scripts/jira_cli.py --help
./scripts/jira_cli.py --json user me
./scripts/jira_cli.py --json issue get SATOS-261728

--json 保留 Jira 原始响应结构，适合 Agent 和脚本处理。
普通模式提供 Rich 摘要或表格。
复杂正文优先写入临时文件，再用 --description-file 或 --body-file 传递。
额外字段使用重复的 --field KEY=JSON_OR_TEXT。

常用查询

./scripts/jira_cli.py server-info
./scripts/jira_cli.py user search jun.fan
./scripts/jira_cli.py project list
./scripts/jira_cli.py project versions SATOS
./scripts/jira_cli.py metadata fields
./scripts/jira_cli.py metadata issue-types
./scripts/jira_cli.py metadata create --project SATOS --type Task
./scripts/jira_cli.py issue list --jql 'assignee = currentUser() ORDER BY updated DESC'
./scripts/jira_cli.py board list --project SATOS
./scripts/jira_cli.py sprint list 12345

状态名称依赖真实 Workflow。流转前先查合法 transition，不猜测：

./scripts/jira_cli.py issue transitions SATOS-261728
./scripts/jira_cli.py issue move SATOS-261728 'Mark as Done' \
  --field 'resolution={"name":"Done"}'

未封装的查询可使用只读逃生口；路径必须以 rest/ 开头，不支持任意写请求：

./scripts/jira_cli.py api get rest/api/2/priority
./scripts/jira_cli.py api get rest/api/2/search --param 'jql=project = SATOS'

Issue 与 Epic

创建 Task 或 Sub-task：

./scripts/jira_cli.py issue create \
  --type Task \
  --summary '中文任务标题' \
  --description-file /tmp/description.txt

./scripts/jira_cli.py issue create \
  --type Sub-task \
  --parent SATOS-261716 \
  --summary '中文子任务标题'

编辑、指派和 clone：

./scripts/jira_cli.py issue edit SATOS-261728 --summary '新的标题'
./scripts/jira_cli.py issue edit SATOS-261728 --set-label reviewed
./scripts/jira_cli.py issue assign SATOS-261728 'user@example.com'
./scripts/jira_cli.py issue clone SATOS-261728 --summary '复制后的标题' \
  --field customfield_10001='复制后的 Epic 名称'

issue edit 的 --set-label、--set-component 和 --set-fix-version 会替换对应字段的完整集合；追加或移除单项时应先读取 Issue，再显式提交完整目标集合。 clone 会依据 Jira create metadata 复制无默认值的必填字段；目标项目缺少可复用值时，使用 --field KEY=VALUE 显式提供。

Epic 使用配置中的 epic_name_field 和 epic_link_field：

./scripts/jira_cli.py epic create --summary 'Epic 标题' --epic-name '简短名称'
./scripts/jira_cli.py epic add SATOS-100 SATOS-101 SATOS-102
./scripts/jira_cli.py epic remove SATOS-100 SATOS-101 SATOS-102

epic add 不会默认覆盖 Issue 已有的其他 Epic 归属；确认需要移动时显式传 --allow-move。epic remove 的第一个参数是预期 Epic，只有当前归属匹配时才会移除。

评论与链接

评论正文按 Jira wiki markup 原样发送，不做 Markdown 转换或转义。需要简洁且可点击的链接时使用：

[Midgard MR !38|https://git.garena.com/example/-/merge_requests/38]

./scripts/jira_cli.py comment add SATOS-261728 --body-file /tmp/comment.txt
./scripts/jira_cli.py comment edit SATOS-261728 22384028 --body-file /tmp/comment.txt
./scripts/jira_cli.py comment list SATOS-261728

Issue link 和外部链接分别使用 link、remote-link：

./scripts/jira_cli.py link types
./scripts/jira_cli.py link add SATOS-1 SATOS-2 --type Relates
./scripts/jira_cli.py link delete 123 --inward-issue SATOS-1 \
  --outward-issue SATOS-2 --yes
./scripts/jira_cli.py remote-link add SATOS-1 --title 'MR !38' --url https://git.example/mr/38
./scripts/jira_cli.py remote-link upsert SATOS-1 --global-id mr-38 \
  --title 'MR !38' --url https://git.example/mr/38

附件、Watcher、Vote 与 Worklog

./scripts/jira_cli.py attachment add SATOS-1 /tmp/evidence.txt
./scripts/jira_cli.py attachment delete SATOS-1 123 --filename evidence.txt --yes
./scripts/jira_cli.py watcher list SATOS-1
./scripts/jira_cli.py watcher add SATOS-1 'user@example.com'
./scripts/jira_cli.py vote get SATOS-1
./scripts/jira_cli.py worklog add SATOS-1 --time-spent 30m --comment '排查问题'

Worklog 默认使用 --adjust-estimate leave，不会隐式修改 Remaining Estimate。需要联动估时时可显式选择 auto、new 或 manual；new 搭配 --new-estimate，新增时的 manual 搭配 --reduce-by，删除时搭配 --increase-by。

使用各命令的 --help 查看完整参数。

删除与写操作安全

创建 Issue 前先搜索是否已有重复任务；除非用户明确要求，不自行创建 Jira 任务。
修改、流转或删除前先回读目标，确认 Issue key 和当前状态。
Issue、评论、附件、关联和 Worklog 的删除均要求显式 --yes。
删除存在 Sub-task 的 Issue 默认失败；只有明确接受级联时才加 --delete-subtasks。
测试写操作只使用本次新建且带唯一测试前缀的临时资源，结束后逆序删除并逐项回查 404。
不在命令、日志或回复中输出完整 token；config show 只展示遮蔽值。

Agent Skills: Jira CLI

Install this agent skill to your local

Skill Files