Copilot Usage

Display GitHub Copilot premium request usage, quota, billing stats, and per-model multipliers for the authenticated user. Use when the user asks about their...

Security Scan

The skill's code and runtime instructions match its stated purpose: it uses the GitHub CLI to read Copilot billing usage and stores a small local plan config; nothing appears to exfiltrate data or request unrelated privileges.

Purpose & Capability

Name/description (Copilot usage, quota, billing, per-model multipliers) align with the included scripts and docs. The scripts call the GitHub REST billing endpoints via the gh CLI and require the manage_billing:copilot and user scopes — exactly what billing queries need. No unrelated binaries, env vars, or config paths are requested.

Instruction Scope

SKILL.md and the scripts only read/write a single local config (~/.config/copilot-usage/config.json), call gh api endpoints, and render a dashboard. They do not reference other system files, other skills' configs, or external endpoints beyond GitHub (no obfuscated endpoints or unexpected network sinks). The instructions are scoped and explicit about authentication and the manual plan configuration requirement.

Install Mechanism

There is no install spec — the skill is instruction+script-based and does not download or install remote code. Scripts rely on standard user tools (gh, python3, bash) already present on developer systems; nothing writes or extracts arbitrary archives.

Credentials

No declared environment variables, which is consistent. The only credential requirement is a GitHub classic Personal Access Token (via gh) with manage_billing:copilot and user scopes — this is necessary for billing endpoints but is a sensitive scope (billing access). The SKILL.md correctly warns fine-grained tokens aren't supported. Users should be aware this requires granting billing privileges to gh.

Persistence & Privilege

The skill does persist a small config file in ~/.config/copilot-usage/config.json to store the user's plan and quota; this is reasonable and documented. always:false and no changes to other skills or global settings are performed.

Assessment

This skill appears to do exactly what it says: call GitHub's Copilot billing API via the official gh CLI and show a local dashboard. Before installing or running: (1) review the scripts yourself — they will run locally and create ~/.config/copilot-usage/config.json; (2) understand you must authenticate gh with a classic PAT granting manage_billing:copilot and user scopes (billing scopes are sensitive — only grant to tokens you control); (3) gh stores auth state locally, so avoid running if you cannot protect that credential; (4) the plan quota is stored locally because the GitHub API doesn't provide it — keep that config private; and (5) if you don't want to grant billing scopes, do not run the scripts. Otherwise the skill is coherent and limited to the expected billing queries.

Copilot Usage Skill

Fetch and display GitHub Copilot premium request usage via the GitHub REST API.

Important API Limitations

The GitHub Billing API does not expose the plan quota (e.g., 50, 300, or 1500 requests/month). This information is not available in any endpoint. Therefore:

1. The user must configure their plan once — stored in ~/.config/copilot-usage/config.json
2. On first run, the script detects missing config and prompts the user to set their plan

Explain this limitation clearly to the user when asking for their plan. Reference: https://docs.github.com/en/rest/billing/usage

Auth Requirements

• Requires gh CLI authenticated with scopes: manage_billing:copilot + user
• Fine-grained tokens are not supported by GitHub billing endpoints — classic PAT required
• Check: gh auth status
• Fix: gh auth login then gh auth refresh -s manage_billing:copilot

Usage

bash scripts/copilot-usage.sh                        # current month
bash scripts/copilot-usage.sh --month 3 --year 2026  # specific month
bash scripts/copilot-usage.sh --model claude          # filter by model
bash scripts/copilot-usage.sh --json                  # raw JSON output
bash scripts/copilot-usage.sh --set-plan pro+         # configure plan
bash scripts/copilot-alert.sh --threshold 80          # quota alert check

Model Multipliers

The grossQuantity returned by the API already includes the multiplier. The script reverse-calculates the actual number of prompts sent and shows both values. See references/multipliers.md for the full table.

Key insight: actual_prompts = grossQuantity / multiplier

What the Dashboard Shows

• Monthly quota used vs. remaining (requires plan config)
• Progress bar with percentage
• Overage count and cost
• Per-model breakdown with multiplier, gross requests, and estimated actual prompts
• Days until monthly reset
• Warning if plan config is missing or stale

Config File

Stored at ~/.config/copilot-usage/config.json:

{
  "plan": "pro+",
  "quota": 1500,
  "set_at": "2026-04-08"
}

Handling Errors

• 403 Forbidden — token lacks billing scope: gh auth refresh -s manage_billing:copilot
• 404 Not Found — verify endpoint path or plan eligibility (org/enterprise users must use org-level endpoints)
• Config missing — run bash scripts/copilot-usage.sh --set-plan <plan>

API Endpoints

See references/api.md for full endpoint documentation and response schemas.