project-view-status

project-view-status

Aggregate the project's progress by status and priority, and generate a report.

Prerequisites

• The target GitHub Project must exist
• gh The CLI must be installed and authenticated (project scope)
• Aggregation is performed with gh の --jq(built-in jq), so a separate jq installation is not required

Flow

Step 1: Get project information

gh project view <number> --owner <owner> --format json

Get the project's title, description, and URL.

Step 2: Get all items

--limit A fixed value (e.g., 999) causes projects with more items than the limit to ignore the remainder, skewing the total count, breakdown, and completion rate. First get totalCount , then pass that count to --limit to retrieve all items.

total=$(gh project item-list <number> --owner <owner> --limit 1 --format json --jq '.totalCount')
[[ "${total}" =~ ^[0-9]+$ ]] || { echo "totalCount の取得に失敗した。中止する" >&2; exit 1; }
[ "${total}" -eq 0 ] && { echo "アイテム 0 件"; exit 0; }

In Step 4, ${total} を --limit as-is and retrieve all items only once (check for omissions using the Step 4 output).

Step 3: Get field definitions

gh project field-list <number> \
  --owner <owner> \
  --format json

Get the definitions and option values of the Status, Priority, and Size fields.

Step 4: Aggregate by status and priority

gh project item-list is the ${total} を --limit confirmed in Step 2, passed to only onceto retrieve, and from that same JSON all aggregations are computed together in --jq a single expression (do not re-retrieve in multiple passes, so that snapshots do not mix within the same report). Do not count by hand; a standalone jq installation is also unnecessary. Example:

gh project item-list <number> --owner <owner> --limit "${total}" --format json \
  --jq '{
    total: .totalCount,
    n: (.items | length),
    by_status: ([.items[] | .status // "(未設定)"] | group_by(.) | map({key: .[0], count: length})),
    open_by_priority: ([.items[] | select(.status != "Done") | .priority // "(未設定)"] | group_by(.) | map({key: .[0], count: length})),
    open_by_size: ([.items[] | select(.status != "Done") | .size // "(未設定)"] | group_by(.) | map({key: .[0], count: length})),
    open_status_x_priority: ([.items[] | select(.status != "Done") | {status: (.status // "(未設定)"), priority: (.priority // "(未設定)")}] | group_by(.) | map({key: .[0], count: length})),
    done: ([.items[] | select(.status == "Done")] | length)
  }'

Since retrieval happens only once, the result is a consistent snapshot at the time of retrieval, and it is unaffected even if items are deleted between Steps 2 and 4. The only problem is if items are added after Step 2 and exceed --limit "${total}" , causing omissions; when the output's total（.totalCount）と n（.items | length) do not match (total > n), do not treat it as an incomplete aggregation, but stop processing and report to the user (re-running is handled after reporting). If a field does not exist in the Step 3 field-list, it becomes (未設定) for all items, so skip the section for that field. The completion rate is calculated from done / n .open_by_priority・open_by_size・open_status_x_priority aligns with the Step 5 format (priority and size breakdowns are for incomplete items only), and aggregates only items whose Status is other than Done (including unset). The model formats the computed results into a table and comments if there is any notable skew.

Step 5: Generate the report

Output the report in the following format:

## プロジェクト進捗レポート: <タイトル>

**更新日時:** YYYY-MM-DD HH:MM

### 全体進捗
- 総アイテム数: N 件
- 完了率: XX% (N/M)
- 進行中: N 件
- レビュー中: N 件
- 未着手: N 件

### ステータス別

| ステータス | 件数 | 割合 |
|-----------|------|------|
| Done | N | XX% |
| In Review | N | XX% |
| In Progress | N | XX% |
| Todo | N | XX% |

### 優先度別（未完了のみ）

| 優先度 | 件数 | In Progress | Todo |
|--------|------|------------|------|
| High | N | N | N |
| Medium | N | N | N |
| Low | N | N | N |

### サイズ別（未完了のみ）

| サイズ | 件数 |
|--------|------|
| XL | N |
| L | N |
| M | N |
| S | N |
| XS | N |

Notes

• --limit is not a fixed value but totalCount(the ${total}), preventing pagination truncation
• Since this is a read-only operation, do not make any changes to the project
• If a field does not exist, skip the corresponding section
• If there are 0 items, report that fact
• Requires network (read-only. See the "Running in a sandbox environment" section below)

Verification

Complete if the Step 5 report output includes the following:

• The total item count and completion rate are displayed
• Counts by status and by priority are aggregated

No changes are made to the project (read-only).

Running in a sandbox environment

Step 1〜4 の gh project view / gh project item-list / gh project field-list(including the aggregation retrieval in Step 4) are all reads to the GitHub API and require network. Run the relevant commands with the sandbox disabled. This skill does not perform any writes whatsoever (no changes to the project, no writes outside the workspace). Only the report formatting in Step 5 is local processing and does not require network.