GitHub Stars Manager

Prerequisites and Configuration

Credential Requirements: GitHub Token (supports automatic local retrieval via GitHub CLI, or Classic PAT / Token with
```
public_repo
```
+
```
read:user
```
+
```
user
```
scopes).
Environment Requirements: Python >= 3.6,
```
pip install requests
```
(>= 2.28).
Configuration Sources (Cascading Resolution): No longer forcibly depends on the
```
.env
```
file in the Skill directory, but reads in the following priority order (each key takes the highest priority source; existing real environment variables are never overwritten):
1. Variables already existing in the process environment (
```
GITHUB_TOKEN
```
  injected by WorkBuddy/connectors, shell environment variables);
2. Explicit
```
.env
```
  path pointed to by
```
GH_STAR_MANAGER_ENV
```
  (can point to a secret file hosted by WorkBuddy);
3. User-level
```
~/.gh-star-manager/.env
```
  (shared across all workspaces/projects for the user);
4. ```
.env
```
  in the Skill root directory (only for backward compatibility legacy);
5. GitHub CLI Local Credentials (Auto-Retrieval): If none of the above are configured, automatically execute
```
gh auth token
```
  to read the local CLI login status, achieving zero configuration / no manual Token creation.
Credential Recommendation: Prefer local GitHub CLI login (
```
gh auth login
```
) or environment variables injected by WorkBuddy/shell.
Working Directory Isolation: All session intermediate artifacts (
```
stars.json
```
,
```
review_plan.json
```
,
```
review.html
```
, etc.) and state files are uniformly stored in the dedicated working directory
```
~/.gh-star-manager/
```
(can be overridden to any WorkBuddy-hosted path via
```
GH_STAR_MANAGER_WORKDIR
```
), never polluting the current project directory. When executing scripts, please point the
```
-o
```
output path to this directory.
Interactive Modes (
GH_STAR_MANAGER_REVIEW_MODE
):
- ```
chat
```
  (WorkBuddy recommended): Does not launch a browser. The Agent presents the plan summary in the conversation and directly calls the CLI to write back after obtaining explicit authorization, which best fits the Agent loop;
- ```
static
```
  :
```
build_review.py
```
  generates
```
review.html
```
  , which the Agent previews inline via
```
present_files
```
  , and the user confirms in the conversation;
- ```
server
```
  (independent desktop scenarios only): Old version local web service that starts and self-destructs automatically, not recommended for Agent environments.
Write Operation Gate: Before any write-back/modification operation is executed, the following must be completed in order:
```
Checkpoint (automatic backup)
```
->
```
Present plan
```
->
```
Explicit authorization confirmation
```
.
Security Boundaries:
- High-Star Protection: Repos with star count ≥ 5000 are excluded from unstar by default; the maximum number of unstar operations per batch is 50.
- Credential Isolation:
```
GITHUB_TOKEN
```
  is only stored in environment variables and
```
.env
```
  files, and is strictly prohibited from being exposed in JSON, logs, or CLI parameters.

Configuration Self-Healing

If the script reports

Missing GITHUB_TOKEN

401 Unauthorized

First prompt the user to run
```
gh auth login
```
or provide https://github.com/settings/tokens to ask the user for a Token;
Write to the user-level
```
~/.gh-star-manager/.env
```
(
```
GITHUB_TOKEN=ghp_xxx
```
, directory is automatically created if it does not exist);
Automatically re-run the previously failed command without requiring the user to repeat the instruction.

Freely Use in WorkBuddy

This Skill is decoupled from WorkBuddy's runtime environment and can be called anywhere without writing secrets into the Skill directory:

Method Zero (zero friction, most recommended): If you have logged in to GitHub CLI locally (
```
gh auth login
```
), the Skill can silently obtain credentials via
```
gh auth token
```
.
Method One (zero configuration): Connect the GitHub connector on the WorkBuddy connectors page. After connection,
```
GITHUB_TOKEN
```
is hosted by WorkBuddy and automatically injected into the script environment.
Method Two (zero files): Set
```
GITHUB_TOKEN
```
in the shell startup script or WorkBuddy's environment variable configuration.
Method Three (user-wide): Create
```
~/.gh-star-manager/.env
```
, all workspaces/projects share the same configuration.
Method Four (point to hosted secret): Set the environment variable
```
GH_STAR_MANAGER_ENV=/path/to/secret.env
```
.

Operation Workflow

Step 1: Credential Verification and Status Synchronization

The scripts are located in this Skill directory (usually
~/.workbuddy/skills/github-star-manager/scripts/
). Please use the absolute path of the Skill when executing; all
-o
outputs should point to the working directory
~/.gh-star-manager/
.

bash

python <skill_dir>/scripts/star_ops.py user; python <skill_dir>/scripts/star_ops.py check-scopes
python <skill_dir>/scripts/fetch_stars.py --sync -o ~/.gh-star-manager/stars.json
python <skill_dir>/scripts/github_lists.py list -o ~/.gh-star-manager/lists.json

Completion Criteria:
can_create_lists
is true;
fetch_stars.py
and
github_lists.py
return
status: success
(exit code 0).

Step 2: Generate Plan (

review_plan.json

)

First read the user profile with

python <skill_dir>/scripts/state.py dump-profile

. Select the corresponding branch based on user intent:

Full Organization Branch (
mode: organize
):
- Run
```
python <skill_dir>/scripts/generate_review_plan.py --plan-mode organize -o ~/.gh-star-manager/review_plan.json
```
  ;
- Detailed categorization strategies, intent-driven tag locking (
```
FROZEN
```
  ), dissolving generalized tags and preset modes (
```
STARS_ORGANIZE_MODE
```
  ) strictly follow references/analysis-guide.md;
- Output
```
review_plan.json
```
  containing suggested List assignments and unstar recommendations.

Batch Import Branch (
mode: import
):

Write the repos to be evaluated into

~/.gh-star-manager/new_repos.json

in the format

["owner/repo", ...]

;

Fetch insights:

python <skill_dir>/scripts/repo_insight.py --input-file ~/.gh-star-manager/new_repos.json -o ~/.gh-star-manager/insights.json

;

Run

python <skill_dir>/scripts/generate_review_plan.py --plan-mode import --insights-file ~/.gh-star-manager/insights.json -o ~/.gh-star-manager/review_plan.json

to output

review_plan.json

containing suggested List assignments.

Completion Criteria:
review_plan.json
that meets the contract specifications is successfully generated.

Step 3: Plan Confirmation and Write-Back (WorkBuddy Native Flow)

In WorkBuddy's Agent loop, do not start the local browser service, but use conversation-driven mode. The three modes are selected according to

GH_STAR_MANAGER_REVIEW_MODE

(Recommended) chat mode: Directly read
```
~/.gh-star-manager/review_plan.json
```
, present suggestions in a clear list in the conversation (create/merge Lists, unstar list, star categorization), and clearly list the write operations to be executed; after obtaining the user's explicit authorization, strictly follow the write operation gate (backup first then execute), and call
```
github_lists.py
```
and
```
star_ops.py
```
batch CLI in sequence to complete the write-back (see references/analysis-guide.md for write-back details).
static mode (visual preview): Generate interactive HTML for users to preview and check within the conversation:
bash
```
python <skill_dir>/scripts/build_review.py --plan-file ~/.gh-star-manager/review_plan.json --output ~/.gh-star-manager/review.html
```
Then use
```
present_files
```
to preview
```
review.html
```
inline for the user; after the user confirms or adjusts in the conversation, the Agent executes the CLI write-back according to the authorization.
server mode (independent desktop only):
```
python <skill_dir>/scripts/review_server.py --plan-file ~/.gh-star-manager/review_plan.json
```
starts a local web service and automatically opens the browser. After confirmation, it forces a backup first before execution and self-destructs in 3 seconds. Do not use this mode in Agent environments.

Completion Criteria: After the user explicitly authorizes in the conversation, the CLI write-back is successful (backup is completed, exit code 0); or in static mode, the user confirms and the Agent has executed the authorized write-back.

Step 4: Preference Distillation

After the interaction ends, compare the user's final plan with the original suggestions, summarize the differences as preference rules and append them to the profile:

bash

python scripts/state.py add-preference "规则描述"

Step 5: Backup and Restore (Optional)

For specific CLI commands for viewing and loading backups, restoring stars/List assignments, see references/analysis-guide.md#备份与恢复流程.

Exception Degradation and Resource Index

GraphQL API Changes: Degrade to outputting Markdown/Awesome-list structured reports.
Service Startup Failure: Degrade to static mode (
```
build_review.py
```
) and export JSON for execution.
Resource Index: scripts/fetch_stars.py | scripts/github_lists.py | scripts/star_ops.py | scripts/review_server.py | scripts/state.py

github-star-manager

NPX Install

Tags

SKILL.md Content (Chinese)

GitHub Stars Manager

Prerequisites and Configuration

Configuration Self-Healing

Freely Use in WorkBuddy

Operation Workflow

Step 1: Credential Verification and Status Synchronization

Step 2: Generate Plan (
`review_plan.json`
)

Step 3: Plan Confirmation and Write-Back (WorkBuddy Native Flow)

Step 4: Preference Distillation

Step 5: Backup and Restore (Optional)

Exception Degradation and Resource Index

github-star-manager

NPX Install

Tags

SKILL.md Content (Chinese)

GitHub Stars Manager

Prerequisites and Configuration

Configuration Self-Healing

Freely Use in WorkBuddy

Operation Workflow

Step 1: Credential Verification and Status Synchronization

Step 2: Generate Plan (review_plan.json)

Step 3: Plan Confirmation and Write-Back (WorkBuddy Native Flow)

Step 4: Preference Distillation

Step 5: Backup and Restore (Optional)

Exception Degradation and Resource Index

Step 2: Generate Plan (
`review_plan.json`
)