jira

Jira

課題追跡、検索、ワークフロー管理のためにJiraを操作します。

スクリプトパスの解決

例にあるSKILL_DIRは、読み込まれたSKILL.mdを含むディレクトリです。 コマンドを実行する前に、この絶対パスを設定してください。エージェントがこのシェル変数を設定すると想定しないでください。スクリプトパスにスペースが含まれる場合は、引用符で囲んでください。

インストール

1. Pythonの依存関係をインストールします：

   pip install --user requests keyring pyyaml pyadf
   

2. リリースからスキルをダウンロードするか、このリポジトリから直接使用します。

セットアップの確認

インストール後、次のコマンドを実行してスキルの設定を確認します。

$SKILL_DIR/scripts/jira.py check

次の項目が確認されます：

• Pythonの依存関係（requests、keyring、pyyaml、pyadf）
• 認証設定
• Jiraへの接続

不足しているものがある場合、確認コマンドにセットアップ手順が表示されます。

ネットワークアクセス

Jira APIコマンドでは、設定されたJiraホストへのアウトバウンドHTTPS接続が必要です。リモート操作にはアウトバウンドネットワークアクセスが必要です。エージェント環境で制限されている場合は、最初のリモートコマンドを実行する前に、その環境の承認またはネットワーク制御を通じてアクセス権を取得し、すでに付与された承認を再利用してください。ローカルのヘルプ表示やファイル処理にはネットワークアクセスは必要ありません。スキルの指示によってネットワークアクセスの許可が与えられることはありません。DNS、接続、タイムアウトの失敗はネットワークエラーとして報告してください。解決のために認証情報をリセットしないでください。承認済みのアクセスでも失敗する場合は、処理を中止して報告してください。認証エラーや権限エラーへの対応には、ユーザーの操作が必要です。

認証

次のいずれかの方法でJiraの認証を設定します。

オプション1：環境変数（推奨）

export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-token"

永続化するには、これらを~/.bashrcまたは~/.zshrcに追加します。

オプション2：設定ファイル

~/.config/agent-skills/jira.yamlを作成します。

url: https://yourcompany.atlassian.net
email: [email protected]
token: your-token

必要な認証情報

• URL：JiraインスタンスのURL（例：https://yourcompany.atlassian.net）
• メールアドレス：Atlassianアカウントのメールアドレス
• APIトークン：https://id.atlassian.com/manage-profile/security/api-tokens で作成します

設定のデフォルト値

必要に応じて、~/.config/agent-skills/jira.yamlでデフォルト値（JQLの対象範囲、フィールド、カスタムフィールド、プロジェクトのデフォルト値）を設定できます。CLI引数は常に設定のデフォルト値より優先されます。設定形式とデフォルト値の動作について詳しくは、configuration.mdを参照してください。

# Show all configuration
$SKILL_DIR/scripts/jira.py config show

# Show project-specific defaults
$SKILL_DIR/scripts/jira.py config show --project DEMO

コマンド

各コマンドの読み取り／書き込みの分類については、permissions.mdを参照してください。

check

設定と接続を確認します。

$SKILL_DIR/scripts/jira.py check

次の項目を検証します：

• Pythonの依存関係がインストールされていること
• 認証が設定されていること
• Jiraに接続できること
• APIバージョンが検出され、互換性があること

search

JQL（Jira Query Language）を使用して課題を検索します。

$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

引数：

• jql：JQLクエリ文字列（--contributorを使用しない場合は必須）
• --contributor：このユーザーが関与する課題を検索します（報告者、担当者、またはコメント投稿者）。Jira Cloudでは、メールアドレスまたは名前からaccountIdを自動的に解決します。
• --project：--contributor検索の対象とするプロジェクトキー
• --max-results：結果の最大数（デフォルト：50）
• --fields：含めるフィールドをカンマ区切りで指定したリスト

デプロイ形態ごとのクエリ：

使用できるJQL関数は、Jiraのデプロイ形態によって異なります。checkを実行すると、デプロイ形態とScriptRunnerが利用可能かどうかを確認できます。

• すべてのデプロイ形態：標準的なJQLパターン（ステータス、日付、フィールド、並べ替え）については、jql-reference.mdを参照してください。
• ScriptRunnerを使用するData Center／Server：linkedIssuesOf()、subtasksOf()、commentedByUser()などの高度な関数については、scriptrunner.mdを参照してください。
• Jira Cloud：ScriptRunner関数は利用できません。jql-reference.mdに記載されているCloudネイティブの代替方法を使用してください。

issue

課題を取得、作成、更新、またはコメントします。

# 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

# List comments
$SKILL_DIR/scripts/jira.py issue comments DEMO-123

# 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"

--from-file の Markdown 形式については from-file-format.md を、その他のパターンについては examples.md を参照してください。

transitions

課題のワークフロー遷移を管理します。

# 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"

追加コマンド

これらのコマンドの詳細については、advanced-commands.md を参照してください。

• config — 設定のデフォルト値を表示・管理し、カスタムフィールドのマッピングを確認します
• fields — 利用可能なフィールドを一覧表示します（全体、またはプロジェクト／課題タイプごと）
• statuses — ステータスとステータスカテゴリを一覧表示します
• user — メールアドレス／名前でユーザーを検索します（Cloud では accountId を返します）
• collaboration — エピックにおけるチーム間の連携パターンを確認します
• automations — Jira の自動化ルールを一覧表示し、詳細を確認します（Cloud のみ）
• versions — プロジェクトのバージョン（リリース）を一覧表示し、リリースレポートを表示します

JQL リファレンス

一般的な JQL クエリとパターンについては、jql-reference.md を参照してください。

クイックリファレンス — AND、OR、ORDER BY と組み合わせてください。

assignee = currentUser() AND statusCategory != Done ORDER BY priority DESC

プロジェクトをまたいで機能するクエリには、statusCategory（"To Do"、"In Progress"、Done）を使用してください。

例

一般的な Jira のワークフロー：

検索と表示：

# 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 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"

ワークフロー：

# List available transitions
jira transitions list DEMO-123

# Move issue to Done
jira transitions do DEMO-123 "Done" --comment "Completed"

モデルに関するガイダンス

このスキルは、構造化された入力／出力を必要とする API 呼び出しを行います。標準的な能力を備えたモデルを推奨します。