GitHub Contribution Planner

Discover what to work on across your GitHub footprint, propose a prioritized daily plan, and — on approval — fan out parallel sub-agents to open draft PRs. The skill infers the current user from the authenticated gh CLI, so no manual configuration is required.

When to use

• "Plan my GitHub contributions for today" / "what should I work on across my repos" / "give me a daily contribution plan".
• You want to maintain your own repositories and forks without manually scanning each one.
• You want to find low-friction openings (good first issues, stale PRs, outdated forks) in projects you have already contributed to.

Do not use this skill to operate on a specific PR you already picked — use gh-fix-ci, gh-address-comments, or github-cli-workflow directly.

Prerequisites

• gh installed and authenticated (gh auth status exits 0). Scopes typically required: repo, read:org. doctor reports this under Integrations.
• python3 for the bundled analyzer.
• Network access to api.github.com (or the host configured via GH_HOST).
• A host that supports parallel sub-agent dispatch (Claude Code's Task tool, OpenCode's subagent fan-out, etc.). Hosts without that primitive fall back to sequential execution.

Workflow

1. Verify auth. Run gh auth status. If unauthenticated, ask the user to run gh auth login and stop. Do not prompt for tokens.
2. Resolve the current user. gh api user --jq .login — never ask the user; always infer from gh.

3. Run the analyzer.

   python3 ~/.local/share/agent-toolkit/skills/gh-contribution-planner/scripts/inspect_contributions.py \
     --since 90d --max-per-bucket 5

   Useful flags:

   • --json — machine-readable output (recommended when composing with another agent).
   • --user <login> — override the inferred login (useful for testing or planning for an organization the user maintains).
   • --dry-run — print the gh calls the analyzer would make and exit; useful for sanity-checking before a live run.
   • --max-per-bucket <n> — cap items per bucket (default 5).
   • --since <window> — lookback window for recent contributions. Accepts 30d, 90d, 180d, or an ISO date.

   The script:

   • Calls gh api user to resolve the login.
   • Calls gh api graphql to batch-fetch viewer repos (non-archived, forks + sources), open PRs authored by the user, and recent contributions across GitHub.
   • For each fork, compares the default branch with the parent's default branch to compute behind/ahead counts.
   • For each owned repo, fetches open issues labeled good first issue or help wanted, plus unassigned issues older than the lookback window.
   • Scores and buckets every item.

4. Present the plan in English grouped into these buckets (each item must show repo owner/name, a one-line summary, an effort estimate, and a suggested delegate skill):

   • Quick wins (~15 min) — README/typo/doc fixes, dependency bumps, missing CI badges in your own repos.
   • In-flight PRs — open PRs authored by you that need attention (red CI → gh-fix-ci; rebase needed → github-cli-workflow).
   • Review feedback — PRs with unresolved review comments → delegate to gh-address-comments.
   • Forks needing sync — forks lagging upstream by ≥ N commits; propose a sync via gh repo sync or a merge-from-upstream PR.
   • Maintenance — own non-archived repos with stale unanswered issues, security alerts, or abandoned PRs from contributors awaiting your review.
   • External contributions — repos where you contributed in the lookback window with open good first issue / help wanted issues that are currently unassigned.
5. Halt for approval. Ask the user which buckets and which specific items to execute. Do not open PRs or push commits before approval.

6. Dispatch parallel sub-agents for the approved items. One sub-agent per item, capped at 5 concurrent by default. Each sub-agent receives:

   • Target owner/name and (when relevant) issue / PR number.
   • A one-line goal extracted from the plan.
   • A directive to start with dev-assistant for repo discovery, then route to the right execution skill:
     • PR push / draft PR creation → github-cli-workflow.
     • Red CI on an existing PR → gh-fix-ci.
     • Open review comments → gh-address-comments.
     • Fork drift → gh repo sync (delegate the sync step; never force).
   • An explicit instruction to open the PR as draft unless the user marks the item as ready-for-review in the approval step.

   On hosts without parallel sub-agent dispatch, execute items sequentially in the same order and report progress between items.

7. Aggregate the run. When the parallel batch completes, summarize:
   • Draft PRs opened (owner/repo#NN + URL).
   • Items skipped or blocked (with reason).
   • Follow-ups that need the user's direct attention.

Parallel execution contract

• Concurrency cap: 5 sub-agents at a time. Raise only on explicit user request.
• Isolation: each sub-agent works in its own git worktree or a fresh clone under ~/.cache/agent-toolkit/contribution-planner/<owner>-<repo>/. Never reuse the host repo working tree.
• Idempotency: before opening a new PR, the sub-agent must check for an existing open PR with the same intent (label or title heuristic) and skip duplicates.
• Drafts by default: every PR is opened as draft. The user marks ready separately.
• No force pushes to branches that already exist on origin unless the user explicitly opts in.

Boundaries

• Read-only on GitHub during planning; writes only after explicit user approval, and only on approved items.
• Do not author commits or PRs from this skill directly — delegate every push to github-cli-workflow.
• Do not act on repos owned by other users beyond the external contributions bucket, and even there only via PRs (never direct pushes).
• Do not interact with non-GitHub forges; for GitLab, route to gitlab-cli-workflow instead.

Bundled resources

• scripts/inspect_contributions.py — stdlib-only analyzer. Defaults to Markdown output; --json for machine-readable output.

Validation

• skills check reports the gh and python3 requirements.
• doctor shows gh auth status under Integrations.

• Smoke test:

  python3 ~/.local/share/agent-toolkit/skills/gh-contribution-planner/scripts/inspect_contributions.py --dry-run