Claude Code guide in three levels, Beginner to Advanced: hands-on lessons with checked exercises, every volatile fact cited to its source. Independent community guide.
Advanced capstone: add CI review your team can share
Advanced · Capstone · 60 to 90 minutes, plus run time · Needs: the seven Advanced lessons, or their skills · Verified against Claude Code v2.1.308 (stable) on 2026-10-25
This task puts the whole Advanced level together, in a new copy of the practice template that you tear down at the end. It has no worked example: the brief says what the team needs, and you choose how to build it. The check reads what you commit and three files you save under .practice/, and you tick the rest of the Advanced Exit yourself under What the check can't see.
You need
Node.js LTS, git,
jq, and the GitHub CLI signed in withgh auth login.A new private copy of the practice template, made for this capstone and torn down after it. Make it with:
gh repo create claude-capstone --template wesammustafa/claude-code-practice --private --clone cd claude-capstone--templatebases the new repository on the template, and--cloneclones it (gh repo create). The check runs in this copy, without--dir.In the copy, start
claudeonce, accept the trust dialog and exit. In a folder you haven't trusted,claude --worktreeexits with an error (Start Claude in a worktree).A credential for CI: a Claude Console API key made for the capstone, recommended because the teardown deletes it, or, on a Pro, Max, Team or Enterprise plan, a token from
claude setup-token(Manual setup).On Pro, dynamic workflows turned on from the Dynamic workflows row in
/config(Orchestrate subagents at scale with dynamic workflows).macOS, Linux or WSL 2: the review script is bash.
Usage: heavy. Two sessions at once, a dynamic workflow, a scripted run and a CI run. Each CI run uses your GitHub Actions minutes, and tokens, which an API key bills to your Console account and a subscription token draws from your plan (Manage costs). Cheap variant: start every session with
--model sonnet(Model aliases), put--model sonnetin the script and inclaude_args(Pass CLI arguments), and have the dynamic workflow in part 4 review only two of the files insrc/.
The task
The team wants one review for every pull request, the same on laptops and in CI, with nothing left unbounded. The brief is in capstone/advanced-brief.md in your copy. Each part below is a problem the team has; the lesson it names shows one way to solve it.
Two parts at once (lesson 1). Parts 2 and 3 don't depend on each other, so build them at the same time, in two Claude Code sessions that can't touch each other's files, and land both changes on
main, by merge, rebase or squash. Keep those working copies out of git. New worktrees branch from the remote's default branch, so pushmainfirst (Choose the base branch). Once both sessions have committed, and while both working copies exist, save their state from the main checkout:mkdir -p .practice && git worktree list --porcelain > .practice/a-capstone-worktrees.txtOne review, everywhere (lessons 4 and 7). Write the team's review once, as a skill committed in
.claude/skills/<name>/SKILL.md, and run it in both places. Pick a name of your own, such asteam-review:/reviewis already an alias of the bundled/code-review(Commands). Aclaude -prun expands/<name>in its prompt (Create a commit), and part 5's workflow runs it as itsprompt. Locally the staged diff arrives on stdin; in CI, Claude reads the change withgit diff(part 5). Write the skill's instructions so they work in both places.Then write
scripts/review-staged.shto lesson 4's criteria: it pipes the staged diff into oneclaude -pcall whose prompt runs your skill, with JSON output anddontAskmode (dontAsk mode), pre-approves onlyRead,GrepandGlob, restricts the tools to those three, turns hooks off and uses no MCP server, and caps turns at 10 or fewer (CLI flags). As in lesson 7, it also caps spend with--max-budget-usd, written as a number in the script. Claude Code checks that cap against its client-side cost estimate, and spend can pass it, so leave headroom (CLI flags). After the merges, stage a one-line change in the main checkout, run the script once, read the review and commit the change:mkdir -p .practice && scripts/review-staged.sh .practice/a-capstone-run.jsonThe saved JSON's
total_cost_usdestimates what one review spent, and it must come in under your cap. As with lesson 7's slice, it's a client-side estimate, not your bill (Track cost and usage).Our plugin, for everyone (lesson 6): a marketplace in
team-marketplace/that lists one plugin by a relative path, with the plugin in its own folder underteam-marketplace/, as in lesson 6's example kit, and at least one skill or agent in the plugin. The committed.claude/settings.jsonregisters the marketplace by a relative path and turns the plugin on (Require plugins per repository). Both validations pass:claude plugin validateon the marketplace, and on the plugin directory with--strict(plugin validate). The kit is a good start; itssettings.snippet.jsonalso denies reading.env, which this copy has no rule for yet. Through these settings, the plugin reaches every teammate who trusts the repository, but not CI, where a fresh checkout was never trusted (When each surface applies the plugin keys): that is why part 2's review lives in.claude/skills/. Test the plugin only after the merges.A sweep before a release (lessons 2 and 3): from a session in the main checkout, after the merges, ask for a workflow that reviews each file under
src/and has a second agent check each finding. While it runs,/workflowsshows each agent's token usage (Cost). Save it to the project and commit it (Save the workflow for reuse).CI review with limits (lessons 5 and 7):
.github/workflows/claude-review.ymlruns onpull_request(Events that trigger workflows) and usesanthropics/claude-code-action(Anthropic) with your skill,/<name>, as itsprompt: for a skill in.claude/skills/,actions/checkoutmust run before the action (Run a skill). On a pull request, the action restores.claude/from the base branch before Claude starts, so a change to your skill reaches CI only once it's merged (security notes). Hold it to lesson 5's limits, and one more:- the action pinned to a release tag or a full commit SHA (Workflow syntax);
- the credential from a repository secret, through the matching input,
anthropic_api_keyorclaude_code_oauth_token(Manual setup); - a read-only job token: no write access in
permissionsexceptid-token: write(Workflow syntax), andgithub_tokenset to the job's ownGITHUB_TOKEN, so Claude acts with that token instead of the Claude GitHub App's (Action parameters); - in
claude_args,--max-turnsof 10 or fewer and an--allowedToolslist without unrestricted Bash; - a
timeout-minutesof 30 or fewer (Workflow syntax); - a
concurrencygroup for the pull request withcancel-in-progress: true, so a new push cancels the review still running for an older one (Workflow syntax), as the docs' cost advice suggests (Manage costs).
To let Claude see the change, check out the full history, as the template's
.github/workflows/progress.ymldoes, and allowgit diffwithBash(git diff *), a rule that matches onlygit diffcommands (Wildcard patterns). Have the skill ask forgit diffas a command on its own, as lesson 7's slice prompt did fornpm test: a rule must match each command in a chain (Compound commands).Set
display_report: true, as lesson 5 does, so Claude's review appears on the run's summary page (action.yml at v1.0.258). Turn it on only for trusted input, as here: the pull requests are your own, in a private copy. On a public repository, GitHub withholds secrets from runs that fork pull requests trigger, so a review like this runs only on pull requests from branches in the repository (Run a skill, Events that trigger workflows).Add the credential as a repository secret: run
gh secret set ANTHROPIC_API_KEY, orgh secret set CLAUDE_CODE_OAUTH_TOKEN, and paste the value when it asks (gh secret set). Never commit the credential; keep it in the repository secret (Protect your credentials). The copy needs no Claude GitHub App: the action authenticates as the App only whengithub_tokenis omitted (Action parameters).Commit the workflow to
mainand push. Then push a one-line change on a new branch and open a pull request.display_reportwrites Claude's review to the job summary, which GitHub shows on the run's summary page (Adding a job summary): find the run's id withgh run list --workflow claude-review.yml --limit 1, then open it withgh run view <run-id> --web, as in lesson 5 (gh run view). Read the review, and merge the pull request yourself. Once the review run has finished, and before you tear down, save its record for the check (gh run list):gh run list --workflow claude-review.yml --json databaseId,status,conclusion,event,url,workflowName > .practice/a-capstone-ci.json
Finish on main, with the merged pull request pulled, everything committed and npm test passing.
Listings checked against the listing bar on 2026-10-24.
Check
You are done when all of these are true:
- Lesson 1:
.practice/a-capstone-worktrees.txtlists two worktrees of this repository whose commits split from each other, and both changes are in your branch; a committed.gitignorekeeps any of them inside the repository out of git, and not the rest of.claude/. - Lessons 2 and 3: a committed script in
.claude/workflows/has a literalexport const meta, with anameand adescription, as its first statement, and callsagent()at least twice. - Lesson 4:
scripts/review-staged.shis committed, executable and meets lesson 4's criteria: oneclaude -pcall, with the prompt right after-p, JSON output,dontAskmode, onlyRead,GrepandGlob, pre-approved and as its only tools, hooks off, no MCP server, and 10 turns or fewer; the staged diff piped in; the JSON saved where its argument says and the result printed; a non-zero exit when the run fails; and no call to Claude when nothing is staged. - Lesson 5: a committed workflow runs
anthropics/claude-code-actiononpull_request, pinned to a release tag or a full commit SHA, in automation mode, with its credential from a secret and none in the file, a read-only job token (no write access inpermissionsexceptid-token: write, andgithub_tokenset to the job's own token),--max-turnsof 10 or fewer, an--allowedToolslist without unrestricted Bash, atimeout-minutesof 30 or fewer and aconcurrencygroup withcancel-in-progress: true; and no Claude API key or token is committed, atHEADor in the commit the check reads that workflow from; and.practice/a-capstone-ci.jsonshows a completed, successfulpull_requestrun of it. - Lesson 6: a committed team marketplace lists a plugin by a relative path, under the
namein the plugin'splugin.json, and the committed.claude/settings.jsonregisters that marketplace by a relative path and turns the plugin on. - Lesson 7: the review script's
claude -pcall caps spend with--max-budget-usd, and.practice/a-capstone-run.jsonholds a real run that succeeded within your turn cap and cost less than your spend cap. - One review: the review script's
claude -pprompt and the CI workflow'spromptboth run one skill committed in.claude/skills/. -
npm testpasses, andgit status --porcelainprints nothing.
Run npm run check -- a-capstone in this copy. It checks each box's parts one by one, and each part that fails prints what to fix. The check runs your script with a stand-in for claude, so it uses none of your usage, and it reads the workflow from your history, so it passes before and after the teardown.
What the check can't see
The check doesn't look at these parts of the Advanced Exit. Tick them yourself, honestly:
- I can say which review I'd run on every pull request (Code Review,
/code-reviewor my CI workflow) and which I'd keep for a sweep before a release (my saved workflow), and why, by what each costs and how deep it goes (Compare ways to get a review). - I can say when an unattended run needs the sandbox from lesson 7, and whether my review script and CI workflow need it.
- Before I merged, I acted on at least one point in Claude's review on the run's summary page, or dismissed it with a reason.
- Before I turned CI on, I multiplied the local run's
total_cost_usdby the pull requests my team opens in a week, to estimate what CI review spends, and I know a new push cancels the review still running.
When every box on this page is ticked, you've shown the Advanced Exit and finished the last of the guide's three levels. One step remains: the teardown below.
If this level helped, a star helps other developers find the guide.
Tear down
When the check passes, tear down: this is required.
[!WARNING] Until you tear down, a live credential sits in the copy's secrets. Deleting a secret leaves the credential it held valid (Uninstall). On 2026-10-24, a token from
claude setup-tokenis valid for one year (Authentication), and deleting the secret doesn't revoke it.
- Delete the workflow with
git rm .github/workflows/claude-review.yml, then commit and push. With the workflow gone, the Claude Code GitHub Action no longer runs (Uninstall). - Delete the secret:
gh secret delete ANTHROPIC_API_KEY, orgh secret delete CLAUDE_CODE_OAUTH_TOKEN(gh secret delete).gh secret listno longer shows it (gh secret list). - With an API key, delete the key on the Claude Console's API keys page. With a token from
claude setup-token, nothing in this teardown revokes it, so it stays valid until it expires (Uninstall): that's why this capstone recommends an API key.
Run npm run check -- a-capstone once more: it still passes.
Sources: Run parallel sessions with worktrees · Commands · Run Claude Code programmatically · Orchestrate subagents at scale with dynamic workflows · Track cost and usage · Choose a permission mode · CLI reference · Model configuration · Configure permissions · Plugin commands reference · Manage Claude Code plugins for your organization · Claude Code GitHub Actions · Code Review · Authentication · claude-code-action at v1.0.258: action.yml, security · GitHub: Events that trigger workflows, Workflow syntax, Workflow commands · GitHub CLI manual: gh repo create, gh run list, gh run view, gh secret set, gh secret delete, gh secret list · the Advanced lessons, which cite the official pages for each step.
← Put bounds on autonomous runs · Advanced index · Beyond this guide → · Stuck on this capstone?