mc-skills/catalog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
catalog/repos/01000001-01001110--agent-jira-skills.md

14 KiB
Raw Blame History

Jira Cloud API 技能集

Jira Claude Code REST API SAFe 项目管理

Claude Code 的 Jira 技能集

用于 Claude Code CLI 的 Jira Cloud REST API 技能集，专为下一代（团队管理型）项目构建。

目录

项目简介

这是一套用于与 Jira REST API 交互的 Claude Code 技能集合。每个技能都是一个独立的文件夹，包含：

  • SKILL.md - 带有 YAML 前置元数据的 Markdown 文件，供 Claude 读取
  • scripts/ - 该领域可运行的 Node.js 和 Python 脚本

技能涵盖：身份验证、问题管理、搜索、流程转换、敏捷看板、项目管理、SAFe 模式以及 Confluence 空间管理。

目录结构

jira/
├── .env                    # 你的凭据（不提交到版本库）
├── .env.example            # 配置模板
├── .gitignore
├── README.md
├── run.js                  # 脚本运行器
├── .github/
│   ├── workflows/
│   │   └── ci.yml          # CI 检查
│   └── hooks/
│       └── pre-commit      # 本地预提交钩子
├── templates/              # 组织标准模板
│   ├── TEMPLATES.md        # 模板文档
│   ├── epic-template.json  # Epic 结构模板
│   ├── story-template.json # 用户故事 SAFe 模板
│   ├── subtask-template.json # 子任务模式
│   └── python-jira-utils.py  # 可复用的 Python 工具函数
├── jira-auth/
│   ├── SKILL.md
│   └── scripts/
│       ├── test.mjs
│       └── test.py
├── jira-issues/
│   ├── SKILL.md
│   └── scripts/
│       ├── create-one.mjs
│       ├── create-one.py
│       ├── delete-all.mjs
│       └── delete-all.py
├── jira-search/
│   ├── SKILL.md
│   └── scripts/
│       ├── check-issues.mjs
│       └── check-issues.py
├── jira-transitions/
│   ├── SKILL.md
│   └── scripts/
│       ├── workflow-demo.mjs
│       └── workflow-demo.py
├── jira-agile/
│   ├── SKILL.md
│   └── scripts/
│       ├── bulk-create.mjs
│       └── bulk-create.py
├── jira-projects/
│   ├── SKILL.md
│   └── scripts/
│       ├── check-fields.mjs
│       └── check-fields.py
├── jira-project-management/
│   └── SKILL.md
├── jira-workflow/
│   └── SKILL.md
├── jira-safe/
│   ├── SKILL.md
│   └── scripts/
│       ├── add-subtasks.mjs
│       ├── add-subtasks.py
│       ├── create-two-level.mjs
│       ├── create-two-level.py
│       ├── create-mvp.mjs
│       └── create-mvp.py
└── jira-spaces/
    ├── SKILL.md
    └── scripts/
        ├── list-spaces.mjs
        ├── list-spaces.py
        ├── create-space.mjs
        ├── create-space.py
        ├── delete-space.mjs
        └── delete-space.py

安装

用于 Claude Code CLI

Claude Code 会在 .claude/skills/[skill-name]/SKILL.md 路径下自动发现技能。每个技能的 YAML 前置元数据中包含 name 和 description 字段。

方式一：克隆到 .claude/skills/

cd your-project/.claude/skills
git clone https://github.com/your-repo/jira-skills.git jira

技能嵌套在 jira/ 目录内，不会被自动发现。可在项目的 CLAUDE.md 中引用，或直接运行脚本。

方式二：为单个技能创建符号链接

cd your-project/.claude/skills
git clone https://github.com/your-repo/jira-skills.git jira

# 创建符号链接以支持自动发现
ln -s jira/jira-auth jira-auth
ln -s jira/jira-issues jira-issues
ln -s jira/jira-search jira-search
# ... 以此类推

方式三：复制所需技能

cp -r jira-skills/jira-auth your-project/.claude/skills/
cp -r jira-skills/jira-issues your-project/.claude/skills/

独立使用

克隆到任意目录并直接运行脚本：

git clone https://github.com/your-repo/jira-skills.git
cd jira-skills
cp .env.example .env
# 编辑 .env 填入你的凭据
node run.js test

配置

1. 获取 API Token

访问 https://id.atlassian.com/manage-profile/security/api-tokens 创建令牌。

2. 创建 .env 文件

cp .env.example .env

编辑 .env：

变量 是否必填 说明
JIRA_EMAIL 是 你的 Atlassian 账户邮箱
JIRA_API_TOKEN 是 第一步创建的 API 令牌
JIRA_BASE_URL 是 你的实例 URL（例如 https://yourcompany.atlassian.net）
JIRA_PROJECT_KEY 否 默认项目键（默认为 SCRUM）
JIRA_BOARD_ID 否 默认看板 ID（默认为 1）

3. 测试连接

node run.js test

使用方法

脚本运行器

run.js 脚本可运行任意技能的 scripts 文件夹中的命令：

node run.js <命令> [参数...]
node run.js --python <命令> [参数...]   # 强制使用 Python
node run.js --node <命令> [参数...]     # 强制使用 Node.js

命令列表

命令 所属技能 说明 Node.js Python
test jira-auth 验证身份认证并运行测试套件 是 是
check-fields jira-projects 列出项目字段和配置 是 是
check-issues jira-search 列出项目中的问题 是 是
create-one jira-issues 创建单个测试问题 是 是
delete-all jira-issues 删除所有问题（默认为试运行） 是 是
workflow-demo jira-transitions 演示工作流转换 是 是
bulk-create jira-agile 根据 git 提交批量创建问题 是 是
add-subtasks jira-safe 为问题添加子任务 是 是
create-two-level jira-safe 创建 Epic/Story/Subtask 层级结构 是 是
create-mvp jira-safe 创建完整 MVP 待办事项 是 是
list-spaces jira-spaces 列出 Confluence 空间 是 是
create-space jira-spaces 创建 Confluence 空间 是 是
delete-space jira-spaces 删除 Confluence 空间 是 是

命令示例

# 身份验证测试
node run.js test

# 列出所有问题
node run.js check-issues

# 创建测试问题
node run.js create-one

# 删除所有问题（先试运行）
node run.js delete-all
node run.js delete-all --confirm   # 实际执行删除

# 工作流转换
node run.js workflow-demo status SCRUM-123      # 检查状态
node run.js workflow-demo start SCRUM-123       # 移至进行中
node run.js workflow-demo complete SCRUM-123    # 移至已完成
node run.js workflow-demo demo SCRUM-123        # 完整周期演示

# 添加子任务
node run.js add-subtasks demo                              # 创建带子任务的演示故事
node run.js add-subtasks SCRUM-123 "任务1" "任务2"          # 添加到已有问题

# 创建层级结构
node run.js create-two-level    # Epic -> Stories -> Subtasks
node run.js create-mvp          # 完整 MVP 待办事项结构

# Confluence 空间
node run.js list-spaces                           # 列出所有空间
node run.js list-spaces --type global --limit 50  # 过滤并限制数量
node run.js create-space DOCS "Project Docs"      # 创建空间
node run.js create-space DOCS "Docs" "描述"
node run.js delete-space DOCS                     # 交互式删除
node run.js delete-space DOCS --confirm           # 强制删除

直接执行脚本

不使用运行器，直接运行脚本：

# Python（自动加载 .env）
python jira-auth/scripts/test.py
python jira-issues/scripts/create-one.py

# Node.js（需要预先设置环境变量）
export JIRA_EMAIL=... JIRA_API_TOKEN=... JIRA_BASE_URL=...
node jira-issues/scripts/create-one.mjs

平台说明

  • Windows：Python 对控制台编码的处理更好，运行器会自动检测并优先选择 Python。
  • Linux/macOS：Node.js 运行良好且启动更快。
  • CI/CD：两种运行时均可，直接设置环境变量即可。

技能列表

技能 涵盖内容
jira-auth 身份验证、请求头、速率限制
jira-issues 创建、读取、更新、删除问题
jira-search JQL 查询、分页、字段选择
jira-transitions 推动问题经历工作流状态
jira-agile 看板、冲刺、待办事项管理
jira-projects 项目信息、问题类型、状态
jira-project-management 组件、版本、角色、权限
jira-workflow 端到端工作流编排
jira-safe SAFe 模式（Epic/Story/Subtask 层级结构）
jira-spaces Confluence 空间管理（创建、列出、删除）

每个 SKILL.md 包含：

  • 带有 name 和 description 的 YAML 前置元数据
  • TypeScript/JavaScript/Python 实现模式
  • curl 示例
  • 常见错误及解决方案

模板

templates/ 文件夹包含遵循 SAFe 方法论创建 Jira 问题的组织标准模板。

模板 用途
epic-template.json Epic 结构，包含业务成果、成功指标、范围
story-template.json 用户故事，包含验收标准（Given/When/Then）、完成定义
subtask-template.json 子任务命名规范和常见任务分解
python-jira-utils.py 可复用的 Jira API Python 工具函数
TEMPLATES.md 使用模板的完整文档

模板使用说明

模板遵循 SAFe（规模化敏捷框架）模式：

Epic 格式：

  • 业务成果
  • 成功指标（可衡量的 KPI）
  • 范围（纳入/排除）
  • 目标用户

Story 格式：

  • 用户故事："作为 [用户]，我希望 [目标]，以便 [收益]"
  • 验收标准：Given/When/Then 场景
  • 完成定义清单

子任务命名：

  • 动词开头格式："创建 X"、"实现 Y"、"添加 Z"

完整文档请参阅 templates/TEMPLATES.md。

API 参考

核心 API（/rest/api/3/）

端点 方法 用途
/myself GET 测试认证，获取当前用户
/project/{key} GET 项目详情
/issue POST 创建问题
/issue/{key} GET, PUT, DELETE 读取、更新、删除问题
/issue/{key}/transitions GET, POST 获取/执行流程转换
/search POST JQL 搜索

敏捷 API（/rest/agile/1.0/）

端点 方法 用途
/board GET 列出看板
/board/{id}/sprint GET 列出冲刺
/sprint/{id}/issue GET, POST 冲刺问题
/sprint POST 创建冲刺

认证请求头

const auth = Buffer.from(`${email}:${token}`).toString('base64');
headers['Authorization'] = `Basic ${auth}`;

Atlassian 文档格式（ADF）

描述字段需要使用 ADF 格式，而非纯文本：

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [{"type": "text", "text": "你的文字"}]
    }
  ]
}

下一代项目与经典项目的区别

这些技能专为**下一代（团队管理型）**项目构建。主要区别如下：

方面 经典（公司管理型） 下一代（团队管理型）
Epic 关联 customfield_10014 parent: { key: 'EPIC-KEY' }
Epic Name 字段 customfield_10011 不可用
子任务类型 'Sub-task' 'Subtask'
项目样式 classic next-gen，simplified: true

检测项目类型：

const project = await fetch(`${JIRA_URL}/rest/api/3/project/${key}`);
const isNextGen = project.style === 'next-gen' || project.simplified === true;

故障排查

401 未授权

  • 令牌已过期或无效
  • 邮箱与 Atlassian 账户不匹配
  • 令牌没有 API 权限

403 禁止访问

  • 无权访问该项目/资源
  • 检查项目角色和权限

400 错误请求

  • 缺少必填字段（project.key、summary、issuetype.name）
  • 描述中 ADF 格式无效
  • 无效的转换 ID（请先查询可用的转换）

404 未找到

  • 问题或项目不存在
  • 键值拼写错误

429 请求过多

  • 已触发速率限制。Jira Cloud 每用户每小时约允许 900 次请求。
  • 退避并以指数级延迟重试。

速率限制

Jira Cloud 每用户每小时约允许 900 次请求。若收到 429 响应：

  1. 检查 X-RateLimit-Remaining 响应头
  2. 等待至 X-RateLimit-Reset 时间戳后再重试
  3. 对重试实现指数退避策略

贡献指南

CI 检查

Pull Request 会自动运行以下检查：

  • SKILL.md 文件的 YAML 前置元数据验证
  • Node.js 语法验证
  • Python 语法验证
  • 目录结构验证
  • 敏感信息检测

本地预提交钩子

安装预提交钩子，在推送前捕获问题：

cp .github/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

添加新技能

  1. 创建文件夹：jira-newskill/
  2. 添加带有前置元数据的 SKILL.md： 
    ---
name: jira-newskill
description: 简要描述，让 Claude 了解何时使用此技能。
---
  3. 添加包含 .mjs 和/或 .py 脚本的 scripts/ 文件夹
  4. 更新 run.js 中的脚本映射
  5. 更新 README 命令表格

许可证

MIT