opencode-github

Connect GitHub (three stages)

GitHub appears three times in the workshop, because it isn't a tool lesson — it'sthe answer to three pain points. Don't teach it all at once, and don't do it all in one go in order — each stage only appears after the user has "already felt the pain".

Stage	When it appears	What the teacher is thinking	This stage only does	Need an account?
① Consumer side	At the very start of the workshop	"How do I get the instructor's stuff?"	`git clone` someone else's repo	❌ No
② Producer side	After making the first piece of work	"I'm afraid of losing this"	Register → create repo → push	✅ Yes
③ Cross-computer verification	The next day / on another computer	"Is it really still there?"	`git pull` get it back	✅ Yes

⚠️ Reminder for the AI agent: when the user says "connect GitHub",first ask which stage they're at, and only do that stage. Dumping all three stages on a zero-background teacher at once is the easiest way for this pack to fail.

🔴 For the AI agent: how to use this document

The value of this document isn't in the "steps", it's in "the things you can't look up".

Type of content	Who you should trust
`gh` 's command names, flags, output format	🔴 Trust `--help` and the official docs. The gh version keeps updating
Where the buttons are on the GitHub web page, what the menus are called	🔴 Trust the screen in front of the user
The "two doors" concept(Git protocol door vs API door)	✅ Trust this document. This explains ninety percent of "the SSH key is clearly set up but I still can't create a repo"
The device code gets cut off by your timeout	✅ Trust this document. Actually tested, exit code 124
The registration puzzle is risk scoring, not problem solving	✅ Trust this document. Multiple people registering from the same IP get flagged as bots
credential helper not found ≠ not set up	✅ Trust this document. GCM's settings are at the system level
Symptom → real cause comparison(the common pitfalls table)	✅ Trust this document, the most time-saving part

Three execution principles

Check the current state before acting. First run gh auth status、git config --show-origin --get-all credential.helper to see what state this machine is in, and report it to the user.
On failure, report the original error text first, then stop. Don't switch methods and retry on your own,especially don't rerun gh auth login—rerunning once invalidates a whole set of codes, and the user gets more and more confused.
When the documentation and the current state don't match, the current state prevails, and tell the user where they don't match.

🔴 The three things most likely to go wrong in this package are all "what you did extra" rather than "what you did too little": Rerunning gh auth login, running interactive commands in your own shell, and when --global can't find it, telling the user to go fix it. If you see it stuck, stop first, ask first, don't take action.

Prerequisites

completed 00-env-setup(both Git and GitHub CLI are installed by 00; this package does not handle installation)
The computer has internet access

Verification:

git --version
gh --version

Expected output (different version numbers are fine):

git version 2.49.0.windows.1
gh version 2.65.0 (2025-01-06)

If you see "The term 'git'/'gh' is not recognized as the name of a cmdlet" or command not found → go back and run 00-env-setup, do not install it on the spot here.

Key knowledge: GitHub has "two doors"

This section is the real value of this package, and is worth three minutes in a workshop.

GitHub is actuallytwo systems stacked together, and each door must be opened separately:

Git protocol door — clone / push / pull, responsible for "moving files"
API door — creating repos, opening issues, submitting PRs, setting up Pages, responsible for "managing the things on your account"

Different authentication methods can only open different doors:

Authentication method	Git protocol door (clone/push/pull)	API door (create repo, issue, PR)	The cost the teacher pays
SSH key	✅	❌	Must generate a key, paste the public key, remember the passphrase
PAT pasted manually	✅	✅ But you must manage it yourself, and it is easy to leak	The token is scattered in config files/clipboard, will expire, will leak
gh CLI	✅	✅	Log in once, then no need to manage it

This explains a common dead end: many tutorials only teach SSH keys, and the teacher's clone and push work fine, but then as soon as they ask an agent to "help me create a repo" it fails—because that is the API door, and the SSH key cannot open it.

Unified approach: gh CLI + one command few people mention

gh auth login By default only opens the API door(gh's own commands can be used), git's push / pull will still separately ask you for the account and password. Add this one line, and both doors will open together:

gh auth setup-git

What it does:Also connects git's HTTPS credentials to gh's token. After that, every time git needs authentication, it automatically asks gh for the token. The result is:

Log in once, both doors open
The token is stored inthe operating system's credential vault(Windows Credential Manager / macOS Keychain / Linux keyring),and does not land as a plaintext file
The AI agent cannot see the token—the agent only calls git and gh, and the token is handed over by the operating system
Completely consistent across agents: OpenCode, Claude Code, Codex, and AntiGravity all call the same gh, and configuring it once works for all of them

Teacher's minimal steps (never touch a token, never generate an SSH key):

gh auth login      →  選 GitHub.com → HTTPS → 瀏覽器登入輸入 8 碼
gh auth setup-git  →  把 git 的憑證也接上去
gh auth status     →  驗證

Why GitHub MCP is not recommended

GitHub MCP It only opens the API door. Once installed, the agent can create repos and open issues, but clone / push / pull it cannot do these git operations, so you still have to go back to the CLI.

So you end up maintaining two sets of things at the same time:the MCP token ＋ the git credentials—— one more set of settings that can expire, can leak, and needs to be reset when you switch agents, yet it doesn't save you from doing a single thing. gh One set opens both doors, sothis package does not install GitHub MCP。

(Exception: consider it only when you really need to automate a large amount of issue/PR analysis. Not needed for workshops.)

Stage 1 (consumer side): Grab someone else's ready-made package

Goal: Get the instructor's teaching materials. What this stage does not do: No account registration, no push, no explaining what git is, no talking about commits. For the teacher, just one sentence: "This is a download command that will grab the entire folder onto your computer."

1-1 Choose a place to put things

Windows（PowerShell）：

cd $HOME\Documents

Mac / Linux：cd ~/Documents

1-2 Download it

git clone https://github.com/mathruffian-dot/opencode-lazy-packs.git

Expected output:

Cloning into 'opencode-lazy-packs'...
remote: Enumerating objects: 120, done.
remote: Total 120 (delta 40), reused 118 (delta 38), pack-reused 0
Receiving objects: 100% (120/120), 84.21 KiB | 2.10 MiB/s, done.
Resolving deltas: 100% (40/40), done.

1-3 Verify

cd $HOME\Documents\opencode-lazy-packs
dir
git remote -v

Mac / Linux：ls replace dir

Expected to see README.md、skills and other files, as well as:

origin  https://github.com/mathruffian-dot/opencode-lazy-packs.git (fetch)
origin  https://github.com/mathruffian-dot/opencode-lazy-packs.git (push)

Seeing the files = this stage is done. Do not go any further.

1-4 Fallback: if clone fails, download the ZIP

When the school network blocks git, or the command just won't run no matter what:

Open the repo URL in a browser
Click the green Code button → Download ZIP
Extract to the 文件 folder

Downside:When the other party updates later, you have to re-download the whole package; with git clone , one line of git pull updates it (see Stage 3).

A reassurance for the teacher

What you download issomeone else'sstuff. No matter how you modify it on your own computer, it won't affect the other party, and youcan't push it up(you don't have permission for that repo). This is why Stage 1 is safe—you can only take, you can't break anything.

Stage 2 (production side): Put your own work up

Motivation: The teacher has just made a set of teaching materials, a webpage, or a presentation, and the thought pops up: "I'm afraid I'll lose this". This is the moment to teach this section, and acceptance is highest.

2-1 Register a GitHub account

Go to https://github.com/signup and register yourself in a browser.

⚠️ The AI agent should not fill in account passwords for you, should not register on your behalf, and should not solve verification on your behalf. Please have the teacher complete it in the browser. Write down youraccount name(you'll keep using it later).

🔴 Registration must be done at home in advance; don't leave it until the workshop

GitHub registration shows a puzzle verification (Arkose Labs FunCaptcha). Itis not testing whether you solve it correctly; it is scoring your source—if the score is low, it keeps issuing new puzzles, so you get an infinite loop of "I solved ten puzzles and I'm still solving them," and solving them correctly doesn't help.

The biggest score deduction is exactly what a workshop looks like: many people registering from the same IP in a short time. The whole classroom shares one external IP, so around the third or fourth person they start getting treated as a bot opening accounts in bulk.

So:

✅ Register at home the night before— everyone's IP is different, so this hurdle is naturally cleared
✅ After registering, also log in once in the browser(if email verification, device confirmation, or 2FA setup pops up, finish those too)
❌ Don't have the whole class register together on site

💡 The second point is more important than it looks. The next day on site you'll run gh auth login, and if the browser is already logged in, the teacher only has two actions left: 'type the eight-digit code, press Authorize' — a matter of tens of seconds. Conversely, if they're logging in for the first time that day, email verification, device confirmation, or even being asked to set up 2FA on the spot will be sandwiched in between— all of these have to be crammed into the authorization time, which is where the on-site 'authenticated three times before it succeeded' comes from (see 2-2).

When someone on site really must register, rescue them in this order:

Ask them to turn on their phone hotspot and register over mobile data(switching to a clean IP, most effective)
Turn off VPN
Switch to an incognito window, or a browser with no extensions installed (ad blockers and privacy extensions block the domains used for verification, or clear verification cookies, causing 'solved it but got another challenge')
Don't mash retry repeatedly, the more you try the lower your score, wait a few minutes and come back

Instructors, bring a phone hotspot as backup. TAs have no other way to rescue this hurdle.

2-2 Logging in to GitHub CLI

First check the status:

gh auth status

When not logged in it shows:

You are not logged into any GitHub hosts. To log in, run: gh auth login

gh auth login

It will ask four questions, choose like this:

Question	Choice
What account do you want to log into?	GitHub.com
What is your preferred protocol for Git operations?	HTTPS
Authenticate Git with your GitHub credentials?	Yes
How would you like to authenticate GitHub CLI?	Login with a web browser

Then the terminal will show a 8-digit one-time verification code(for example A1B2-C3D4), press Enter to open the browser → paste the verification code → press Authorize。

To skip two questions you can directly use:gh auth login --web --git-protocol https

🔴 For AI agents: never run this line in your own shell

This is the most common infinite loop at workshop sites, caused as follows:

gh auth login After printing the 8-digit codeit won't exit— it has to stay alive polling GitHub, and only gets the token after you authorize. And your (agent's) commands usually have a timeout (commonly 2 minutes).The teacher is still typing those eight digits on their phone,gh and it's already been killed by your timeout.

The result is: the teacher pressed Authorize in the browser, the screen shows success,but there is no longer any gh waiting to receive the token. You check gh auth status and it's still not logged in → you think it failed → rerun gh auth login → generating a brand-new 8-digit code → the teacher's screen still shows the old code, no matter how they type it it's wrong → you rerun again → infinite loop.

Tested (gh 2.89): without a TTY, gh auth login immediately prints the code and URL, then keeps running; when killed by timeout the exit code is 124。

Correct approach A: open a separate window and let it live (Windows)

Start-Process powershell -ArgumentList '-NoExit','-Command','gh auth login --web --git-protocol https'

This windowwon't be affected by your timeout，gh You can wait indefinitely. macOS/Linux has no equivalent one-line command, so go directly with Method B.

Correct Method B: Have the teacher open the terminal themselves

Tell them: "Please open a PowerShell window yourself, paste gh auth login, and follow its instructions.Don't close that window yet.」

Then—poll, don't rerun

Whether it's A or B, what you need to do next ischeck the status every few seconds, until it succeeds:

gh auth status

Exit code	Meaning
`0`	✅ Login successful, you can proceed
`1`	Not ready yet,check again later

🔴 If you see "not ready yet," don't rerun gh auth login。 Rerunning once invalidates a set of codes, and the teacher will get more and more confused.The set of codes generated on the first run remains valid until they finish authorizing.

Polling rhythm: check every 10 seconds,wait up to 10 minutes

Don't only wait 5 minutes. In practice, "success only after three repeated authentications" has actually happened—that's not three retries finally getting through, it'sonly the third time beating the timeout. The first time they were still finding the browser, the second time they were still logging in, and the third time they were familiar enough to make it in time.

During the wait, report back once a minute, for example:

"Still waiting for you to complete authorization, no rush. Once it's done, I'll detect it automatically on my end."

This sentence is very important. Without reporting back, the teacher will think it's stuck and go rerun it themselves gh auth login—— That will invalidate the current set of codes, which is effectively resetting your own progress to zero with your own hands, and then you have to start another round.

If it's still not done after 10 minutes, then ask them "Which step are you stuck on?"—still don't rerun it yourself。

Verification:

gh auth status

Expected output:

github.com
  ✓ Logged in to github.com account 你的帳號 (keyring)
  - Active account: true
  - Git operations protocol: https
  - Token: gho_************************
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

Token scopes must contain repo, otherwise creating the repo later will fail.

2-3 Also connect git's credentials (the most critical line in this package)

gh auth setup-git

No output on success(no news is good news).

Verification—look at all levels, don't just look at --global：

git config --show-origin --get-all credential.helper

Any of the following three results counts as passing：

What you see	Meaning	Verdict
Contains `gh.exe' auth git-credential`(or `/usr/bin/gh auth git-credential`）	`gh auth setup-git` is in effect	✅ Pass
`manager`, the source is `C:/Program Files/Git/etc/gitconfig`	Git Credential Manager (GCM) built into Git for Windows is managing it, and it works just as well	✅ Pass
No output at all	No credential manager at all	⚠️ Only then does it need handling

🔴 Important reminder for AI agents: don't use git config --global --get-regexp credential as the basis for judgment. Git for Windows installed with winget on Windows comes with GCM by default, and the setting is written at the system level, not the global level. Checking only --global will return an empty result, so it gets misjudged as "setup-git failed"—but the user's git push is actually fine. This is the item most prone to false alarms in this package.

The real test is whether git push it will succeed, not what the config file looks like. If the config doesn't show it but push works → pass, don't tell the user to fix a problem that doesn't exist.

The difference between the two credential managers(both work, no need to choose one):

	`gh auth setup-git`	GCM (built into Git for Windows)
On the first push	Passes directly, doesn't ask you	Opens the browserlets you authorize once, then it remembers
Where the token is stored	OS credential vault	OS credential vault
Need to install separately?	No (comes with gh)	No (comes with Git for Windows)

When neither is present,git push only then does it fall back to asking for a username and password—and GitHub no longer accepts password pushes, so it will definitely fail.gh auth setup-git 's value is "guaranteed to be there," not "the only solution."

2-4 Set Git user information

Every commit willpermanently recordyour name and email; anyone can see them in a public repo.

Check first:

git config --global user.name
git config --global user.email

No output at all = not set yet. Fill it in:

git config --global user.name "王小明"
git config --global user.email "12345678+你的帳號@users.noreply.github.com"

💡 It is strongly recommended to use the @users.noreply.github.com addressthat GitHub gives you, not a school email or personal Gmail—to avoid handing your email to crawlers through a public repo.

Where to get it: GitHub website → top-right avatar → Settings → Emails → check Keep my email addresses private → your 數字ID+帳號@users.noreply.github.com。

Advanced (if you're already logged in to gh you can get it in one line; if that doesn't work, use the website route):
gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'

2-5 Turn your work into a repo and upload it

Go intothe folder you really want to back up(don't create a separate test folder; using real work makes the motivation stronger):

cd $HOME\Documents\我的教材
git init
git branch -M main
git add .
git commit -m "第一次備份我的教材"

What the commands do (plain-language version for teachers):

Command	Plain language
`git init`	Tell this folder "start tracking versions for me"
`git branch -M main`	Rename the main line to `main`(GitHub's convention, to avoid mismatches later)
`git add .`	Put everything in the folder "into the packing box"
`git commit -m "..."`	Stamp and save it; put a note you can understand in the quotes

git init After hint: Using 'master' as the name for the initial branch... ifthat's a hint, not an error，git branch -M main is handling it.

Create a GitHub repo and upload in one go:

gh repo create 我的教材英文名 --private --source=. --push

Parameter-by-parameter explanation:

我的教材英文名 — repo name, use onlyalphanumeric characters and -, no Chinese, no spaces (e.g.,my-teaching-materials）
--private — only you can see it (for workshops always use private first, change it later if you decide to make it public)
--source=. — use the contents of "the current folder"
--push — upload immediately after creating

Expected output:

✓ Created repository 你的帳號/my-teaching-materials on GitHub
  https://github.com/你的帳號/my-teaching-materials
✓ Added remote https://github.com/你的帳號/my-teaching-materials.git
✓ Pushed commits to https://github.com/你的帳號/my-teaching-materials.git

2-6 Verify

Look with your eyes (recommended; the teacher's "wow" moment is right here):

gh repo view --web

The browser will open your repo, and seeing your own file list = success.

Plain text verification (for the agent to interpret, without opening a browser):

git remote -v
git log --oneline -1
gh repo view --json name,visibility,url

Expected:

{"name":"my-teaching-materials","url":"https://github.com/你的帳號/my-teaching-materials","visibility":"PRIVATE"}

Daily routine after 2-7 (three-line loop)

After changing something:

git add .
git commit -m "說明你這次改了什麼"
git push

Teachers only need to remember these three lines to last a whole year.

Stage 3 (cross-computer acceptance): confirm the stuff is really still there

Motivation: At the end of Stage 2, the teacher is actually half doubtful—"Did it really get saved?" This stage is aboutturning doubt into evidence. It's best to schedule it forthe next dayoron a different computer.

Scenario A: Switch to another computer (or the second one at the workshop)

Do four things in order on the new computer:

# 1. 先跑 00-env-setup 裝好 git 與 gh（略）
gh auth login          # 2. 登入（同 2-2）
gh auth setup-git      # 3. 接上 git 憑證（同 2-3）
cd $HOME\Documents
gh repo clone 你的帳號/my-teaching-materials    # 4. 抓回來

This is a good place to tie back to the "two doors":gh repo clone goes through the API door to find the repo, and actually downloading the file goes through the Git protocol door. Because gh auth setup-git both are open, one line gets through. Private repos can also be directly git clone <網址>, and likewise you don't need to enter any password again.

Scenario B: Same computer, coming back the next day

cd $HOME\Documents\my-teaching-materials
git pull

Expected output (choose one of two):

Already up to date.

or (when there are updates):

Updating a1b2c3d..e4f5g6h
Fast-forward
 教案.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

Acceptance checklist

dir
git log --oneline -3

The number of files matches what you originally uploaded
git log You can see the commit message you wrote yesterday
Open any file at random, and the content is correct

All three pass = the stuff is really in the cloud, not just on your computer.

Recommended "live drill" to do at the workshop

Computer A changes one line of text → git add . → git commit -m "測試" → git push
Computer B (or the teacher next door's computer)git pull
the change appears

Only at this moment will the teacher truly believe "it's alive," rather than it being yet another command to memorize.

By the way, answering "Then what do I do if my computer breaks?"

Four lines to rescue it:

# 新電腦：跑完 00-env-setup 之後
gh auth login
gh auth setup-git
gh repo clone 你的帳號/my-teaching-materials

About "deletion": this package deliberately does not teach it

This package does not teach gh repo delete, nor does it teach rm -rf。 There are three reasons:

Both are irreversible。gh repo delete deletes from the cloud,rm -rf deletes from the local machine,neither has a recycle bin. For a teacher with zero background, one mistyped path is a disaster.
It is the opposite of this package's purpose. This whole package is teaching "don't lose things again," and inserting a command in the middle that "makes things disappear" has risks far greater than the benefits.
It will also get stuck technically：gh auth login The token obtained by default does not have delete_repo scope， gh repo delete and will directly return HTTP 403, so you need to additionally run gh auth refresh -h github.com -s delete_repo to add permissions— getting stuck here midway through the workshop means all the time is gone.

If you really must delete: go to the GitHub web page → your repo → Settings → at the very bottom Danger Zone → Delete. The web page will require you tomanually type out the repo's full namebefore it will delete. This "deliberate hassle" is the protection; don't bypass it.

Common pitfalls

Symptom	Cause / solution
`gh auth login` Running it produces no response, it hangs	This isInteractive command, if the agent runs it in its own shell it will be killed by the timeout. Switch to a separate window + polling (see 2-2)
After entering the eight digits, the agent keeps saying it hasn't received verification and keeps giving new codes	The most common loop. `gh` It was killed by the agent's timeout, and no one is waiting for the token. Solution: run it in a separate window `gh auth login`, and the agent is only responsible for polling `gh auth status`(only exit 0 counts as success),do not rerun login(see 2-2)
No matter how I enter the eight digits it says it's wrong	Most likely it'sseeing an old code—login was rerun, and the old code is already invalid. Go by the code shown in the latest window
People who register a new account on-site that day log in especially slowly	A brand-new account's first login isn't just entering eight digits; in between it often also includesemail verification ＋ device confirmation for first login + some people are asked toset up 2FA on the spot. All of this has to fit into the authorization time,being several times slower than veterans is normal. → Always give polling a full 10 minutes, and report once per minute to reassure them. → The fundamental solution is still to register the account at home the night before and log in once while you're at it(see 2-1)—　 the next day on-site only two actions remain: 'enter the eight digits, press Authorize,' a matter of tens of seconds
During registration the puzzle keeps popping up and solving ten of them still doesn't get through	It's not that you solved it wrong—that's risk scoring,multiple people registering from the same IPgets treated as a bot batch-creating accounts. Solution:switch to a phone hotspot(change IP, most effective) / turn off VPN / switch to an incognito window or a browser without extensions / don't keep hammering clicks.The fundamental solution is to register at home the night before(see 2-1)
8-digit verification code expires	The device code flow is only valid for a few minutes.It's especially easy to run into this when dozens of people log in simultaneously at a workshop site: if the explanation drags on, the code expires. Just rerun `gh auth login` to get a new code
A bunch of people at the workshop site can't log in at the same time	Dozens of computers opening at the same time `github.com/login/device`+ network congestion. Suggestion:ask everyone to register their accounts the day before, on-site proceed in batches (row by row), and the instructor first demonstrates a complete round before letting them go
`git push` pops up a window asking for account and password	This machine has no credential manager at all. Run `gh auth setup-git`(see 2-3). GitHub no longer accepts password pushes, and forcing entry will also fail
`git push` opened a browser asking you to authorize	That's normal, that's the built-in GCM in Git for Windows doing its job. Once you authorize, it remembers, and you don't need to switch to gh
Even though push works, it's judged as 'setup-git not done'	Misjudgment. GCM's settings are at the system level, so using `git config --global` won't find them. Use instead `git config --show-origin --get-all credential.helper`(see 2-3)
`git commit` say `Author identity unknown`	Go back and do 2-4's `git config --global user.name` / `user.email`
`gh repo create` reply `HTTP 403` / insufficient permission	`gh auth status` check `Token scopes` whether there is `repo`; if not, `gh auth refresh -h github.com -s repo`
`remote origin already exists`	This folder is already connected to another repo.`git remote -v` See which one it is; usually it is because you ran it ina folder cloned by someone elseran `gh repo create`
push failed saying a file is too large	GitHub 100MB limit per file. Put videos and large PDFs on cloud storage; keep only text and code in the repo; use `.gitignore` to exclude large files
accidentally pushed private data	Deleting the file and committing again is useless; the history record is still there. First change the repo to private. If what leaked is a password or API key,immediately go to the original platform and replace that key—this is a hundred times more important than cleaning history
Chinese filenames display as garbled number codes on the GitHub web page	The display issue does not affect the file contents; if you care, `git config --global core.quotepath false`

Success signal (machine-readable)

Run the following checks; the agent determines according to the rules:

gh auth status
git config --show-origin --get-all credential.helper
git config --global user.email
git -C <專案資料夾> remote -v
git -C <專案資料夾> log --oneline -1

Decision rules:

Check item	Pass condition
`GH_AUTH`	`gh auth status` contains `Logged in to github.com`
`GH_SCOPE_REPO`	`Token scopes` string contains `repo`
`GH_SETUP_GIT`	credential helper contains `gh ... auth git-credential` or contains `manager`(GCM). If neither is present but `STAGE2_PUSH` succeeds → still record `OK`(see note below)
`GIT_IDENTITY`	`user.name` and `user.email` are both non-empty
`STAGE1_CLONE`	The target folder exists, and `git remote -v` has `origin`
`STAGE2_PUSH`	`gh repo view --json url` returns a URL, and `git log` at least one commit
`STAGE3_PULL`	`git pull` returns `Already up to date.` or a successful Fast-forward

Finally output this section (for stages not run, fill in SKIP, for failures fill in FAIL:<原因>）：

GITHUB_PACK_STATUS=OK
GH_AUTH=OK
GH_SCOPE_REPO=OK
GH_SETUP_GIT=OK
GIT_IDENTITY=OK
STAGE1_CLONE=OK
STAGE2_PUSH=OK
STAGE3_PULL=SKIP

As long as any item is FAIL，GITHUB_PACK_STATUS it must be FAIL。

⚠️ Only exception:GH_SETUP_GIT。 The credential manager settings may be written at the system level (the GCM built into Git for Windows); not finding it does not mean it is broken. As long as STAGE2_PUSH is OK, record GH_SETUP_GIT as OK—being able to push is the final evidence. Do not tell the user to fix a non-existent problem because of this item.

Reporting template

## GitHub 連接結果

**目前階段**：① 消費端 / ② 生產端 / ③ 跨電腦驗收

- 先備條件（00-env-setup）：git <版本> / gh <版本> ✅
- gh 登入：✅ 帳號 `<帳號>`（scopes 含 repo）
- gh auth setup-git：✅ 兩道門已開（credential helper 指向 gh）
- Git 使用者資訊：`<name>` / `<...@users.noreply.github.com>` ✅

### 階段一：消費端
- clone 目標：`<repo 網址>`
- 本機位置：`<路徑>`
- 結果：✅ 成功 / ⚠️ 改用 ZIP 下載 / ❌ 失敗（原因）

### 階段二：生產端
- repo：`<帳號>/<repo名>`（private）
- 網址：`<url>`
- 首次 commit：`<commit 訊息>`
- push：✅ 成功 / ❌ 失敗（原因）

### 階段三：跨電腦驗收
- 方式：換電腦 clone / 隔天 git pull
- 結果：✅ 檔案與 commit 紀錄都在 / ❌ 不一致（說明）

### 待處理
- <若有，列出；沒有就寫「無」>

About this skill

🔴 For the AI agent: how to use this document

Three execution principles

Prerequisites

Key knowledge: GitHub has "two doors"

Unified approach: gh CLI + one command few people mention

Why GitHub MCP is not recommended

1-1 Choose a place to put things

1-2 Download it

1-3 Verify

1-4 Fallback: if clone fails, download the ZIP

A reassurance for the teacher

2-1 Register a GitHub account

🔴 Registration must be done at home in advance; don't leave it until the workshop

2-2 Logging in to GitHub CLI

🔴 For AI agents: never run this line in your own shell

Correct approach A: open a separate window and let it live (Windows)

Correct Method B: Have the teacher open the terminal themselves

Then—poll, don't rerun

Polling rhythm: check every 10 seconds,wait up to 10 minutes

2-3 Also connect git's credentials (the most critical line in this package)

2-4 Set Git user information

2-5 Turn your work into a repo and upload it

2-6 Verify

Daily routine after 2-7 (three-line loop)

Scenario A: Switch to another computer (or the second one at the workshop)

Scenario B: Same computer, coming back the next day

Acceptance checklist

Recommended "live drill" to do at the workshop

By the way, answering "Then what do I do if my computer breaks?"

About "deletion": this package deliberately does not teach it

Common pitfalls

Success signal (machine-readable)

Reporting template