GitHub Project Skill

This skill provides a comprehensive CLI wrapper for the GitHub GraphQL API, enabling efficient management of GitHub Projects V2 and Issues directly from the terminal.

Usage

The main entry point is dist/cli.js (relative to the project root). You can verify it works with:

bash

node dist/cli.js --help

Global Options:

•-j, --json: Output results in JSON format. ALWAYS use this flag when parsing output programmatically.

Note: In --json mode, the CLI prints only JSON to stdout.

0. 🔍 Discovery

Goal: Explore owner resources and project structure.

List Projects

•Command: node dist/cli.js project-list <owner>

•Usage:

bash

node dist/cli.js project-list "my-org" --json

List Repositories

•Command: node dist/cli.js repo-list <owner>

•Usage:

bash

node dist/cli.js repo-list "my-org" --json

Get Project Board Details

•Command: node dist/cli.js board <owner> <project>
•Arguments: <project> can be the Project Number or the Project Title (case-insensitive).
•Options: --status-field <name> (Default: "Status")
•
Usage:
bash
```
node dist/cli.js board "my-org" "My Project Name" --json
```
Returns project ID, global node ID, and column definitions (including Option IDs needed for moving items).

1. 📋 Board Items

Goal: List all items (Issues/PRs/Drafts) on the board with their current status.

•Command: node dist/cli.js items <owner> <project>
•
Usage:
bash
```
node dist/cli.js items "my-org" 1 --json
```
Returns list of items with their Item IDs (for moving/archiving) and Content Node IDs.

List Issues Linked to a Project (Project-Centric)

Goal: One consistent way for AI agents: start from Project, get issues + both IDs (Issue node ID and Project item ID).

•Command: node dist/cli.js project-issues <owner> <project>
•
Options:
- •--status-field <name> (Default: "Status")
- •--state <open|closed|all> (Default: open)
- •--limit <n> (Default: 50)
- •--repo <owner/repo> (Optional: narrow search to a single repo)

•Usage:

bash

node dist/cli.js project-issues "my-org" "Trionix Lab" --state open --limit 50 --json
# optionally scope to one repo for speed/limits
node dist/cli.js project-issues "my-org" 1 --repo "my-org/my-repo" --json

Implementation note: uses GitHub GraphQL search + Issue.projectItems to avoid cases where ProjectV2.items listing is incomplete for some integrations.

Show Project Item by Item ID

Goal: Inspect a specific project item when listing is incomplete.

•Command: node dist/cli.js item-show <itemId>
•Options: --status-field <name> (Default: "Status")
•
Usage:
bash
```
node dist/cli.js item-show "PVTI_..." --json
```
Useful workaround if items does not show Issues/PRs due to access restrictions.

2. 🆕 Issue & Draft Management

List Issues

Goal: List issues in a repository (with pagination).

•Command: node dist/cli.js issue-list <owner/repo>
•Options: --state <open|closed|all> (Default: open), --limit <n> (Default: 50)

•Usage:

bash

node dist/cli.js issue-list "my-org/my-repo" --state open --limit 50 --json

Create Issue

•Command: node dist/cli.js issue-create <owner/repo> "<title>"
•Options: --body "<body>"

•Usage:

bash

node dist/cli.js issue-create "my-org/my-repo" "Fix bug" --body "Details" --json

Create Draft

•Command: node dist/cli.js draft-create <owner> <project> "<title>"
•Options: --body "<body>"

•Usage:

bash

node dist/cli.js draft-create "my-org" "Product Roadmap" "Task title" --body "Details" --json

Show Issue

•Command: node dist/cli.js issue-show <owner/repo> <issue_number>

•Usage:

bash

node dist/cli.js issue-show "my-org/my-repo" 123 --json

Get Issue by Node ID (Agent-Friendly)

Goal: Fetch issue content when you already have issue.id (node ID).

•Command: node dist/cli.js issue-get <issueNodeId>

•Usage:

bash

node dist/cli.js issue-get "I_kwDO..." --json

Update Issue

•Command: node dist/cli.js issue-update <issueNodeId>
•Options: --title <text>, --body <text>

•Usage:

bash

node dist/cli.js issue-update "I_kwDO..." --title "New Title" --json

Close Issue

•Command: node dist/cli.js issue-close <issueNodeId>

•Usage:

bash

node dist/cli.js issue-close "I_kwDO..." --json

Delete Issue (Behavior)

Note: GitHub APIs do not support hard-deleting Issues. This command closes the issue.

•Command: node dist/cli.js issue-delete <issueNodeId>

•Usage:

bash

node dist/cli.js issue-delete "I_kwDO..." --json

3. 💬 Collaboration

Goal: Add comments to issues.

•Command: node dist/cli.js issue-comment <issueNodeId> "Comment text"

•Usage:

bash

node dist/cli.js issue-comment "I_kwDO..." "Done" --json

List Comments

Goal: Get existing comments for an issue (for agents that need context).

•Command: node dist/cli.js issue-comments <issueNodeId>
•Options: --limit <n> (Default: 50)

•Usage:

bash

node dist/cli.js issue-comments "I_kwDO..." --limit 50 --json

4. 🚚 Kanban Operations

Add Issue to Project

•Command: node dist/cli.js issue-add-to-project <owner> <project> <issueNodeId>

•Usage:

bash

node dist/cli.js issue-add-to-project "my-org" "Project Name" "I_kwDO..." --json

Move Item

•Command: node dist/cli.js issue-move <itemId> <projectId> <statusFieldId> <optionId>

•Usage:

bash

# IDs are obtained from 'board' and 'items' commands
node dist/cli.js issue-move "PVTI_..." "PVT_..." "PVTSSF_..." "f75ad846" --json

Move Item (Agent-Friendly)

Goal: Move an item without dealing with option IDs.

•Command: node dist/cli.js item-move <owner> <project> <itemId> --status "<Status Name>"
•Options: --status-field <name> (Default: "Status")

•Usage:

bash

node dist/cli.js item-move "my-org" "Product Roadmap" "PVTI_..." --status "In progress" --json

Archive Item

•Command: node dist/cli.js item-archive <owner> <project> <itemId>
•Options: --unarchive

•Usage:

bash

node dist/cli.js item-archive "my-org" 1 "PVTI_..." --json

Delete Item from Project

•Command: node dist/cli.js item-delete <owner> <project> <itemId>

•Usage:

bash

node dist/cli.js item-delete "my-org" "Project Alpha" "PVTI_..." --json

Best Practices

•Use JSON: Always append --json for robust parsing.
•Get IDs First: Most mutation commands require Node IDs (strings starting with like PVT_, I_, PVTI_). Use project-list, board and items commands to retrieve these IDs.
•Owner Logic: Owner can be either an Organization or a User. The tool automatically tries both.

Troubleshooting

•"Project not found": Check if owner and project_number are correct.
•"Resource not accessible by integration": Check your .env credentials and GitHub App permissions.

Notes on Project Items Visibility

•A Project V2 may contain items that the current token cannot fully view. GitHub can return items as REDACTED when the integration lacks permissions to view the underlying Issue/PR.
•If issue-add-to-project succeeds but items does not show the Issue/PR item, use item-show <itemId> (the itemId returned by issue-add-to-project) to inspect it directly.

Recommended Single Workflow (for AI agents)

•List work from the Project (project-centric): project-issues <owner> <project> --json. Note: <project> can be a name or a number.
•Read issue content by node ID: issue-get <issueNodeId> --json.
•
Update / comment:
- •issue-update <issueNodeId> --title ... --body ... --json
- •issue-comments <issueNodeId> --json (get context)
- •issue-comment <issueNodeId> "..." --json (add)
•
“Delete” in practice:
- •GitHub APIs do not support hard-deleting Issues.
- •Use issue-delete <issueNodeId> (closes the issue) and/or item-delete <owner> <project> <projectItemId> (removes it from the Project).
•
Move on the board using readable status:
- •item-move <owner> <project> <projectItemId> --status "To Do" --json
•
Optional lifecycle:
- •item-archive <owner> <project> <projectItemId> --json