codelab-rebuild
Skill2.1k starsChanged 5 days agoBSD-3-ClauseView on GitHub
Guides the agent on using the `codelab_rebuild` CLI tool and authoring, debugging, and maintaining `codelab_rebuild.yaml` blueprint files in the Flutter codelabs repository. Use this skill whenever rebuilding codelabs, updating codelab steps for a new Flutter/Dart release, fixing broken patches in `codelab_rebuild.yaml`, or creating a new codelab blueprint.
- Deletes or force-pushes
Trending
More talk lately.about the whole repository
Who's talking about flutter/codelabs
- flutter/flutter“[go_router] Route triggered twice after navigating from 3rd party app by link (deep linking)”GitHub · Oct 22, 2023 · 9 reactions
- flet-dev/flet“Authentication”GitHub · Mar 24, 2022 · 8 reactions
- flutter/flutter“Flutter 1.22, FlutterFire, and Xcode 14 complains about IPHONEOS_DEPLOYMENT_TARGET”GitHub · Sep 18, 2020 · 5 reactions
- flutter/website“[Codelab] Example failing for Scrolling test in integration testing.”GitHub · Nov 23, 2021 · 4 reactions
- flutter/flutter“`flutter --enable-flutter-gpu test` doesn't work”GitHub · Jun 30, 2025 · 2 reactions
The biggest 5 of 34 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 34
Talked about on GitHub (34 times).
On GitHub · 34
- Oct 22, 2023[go_router] Route triggered twice after navigating from 3rd party app by link (deep linking) — flutter/flutter9 reactions · 8 comments
- Mar 24, 2022Authentication — flet-dev/flet8 reactions · 4 comments
- Sep 18, 2020Flutter 1.22, FlutterFire, and Xcode 14 complains about IPHONEOS_DEPLOYMENT_TARGET — flutter/flutter5 reactions · 6 comments
- Nov 23, 2021[Codelab] Example failing for Scrolling test in integration testing. — flutter/websitesays it tested it4 reactions · 8 comments
- Jun 30, 2025`flutter --enable-flutter-gpu test` doesn't work — flutter/flutter2 reactions · 4 comments
29 more on GitHub
- Dec 19, 2024Flutter `master` channel is broken on `flutter/codelabs` CI — flutter/flutter2 reactions · 11 comments
- Aug 4, 2022in_app_purchase codelabs demo has incorrect import causing a crash during `firebase deploy` — flutter/flutter2 reactions · 15 comments
- Dec 10, 2024`flutter_scene` failing to build on `main` — bdero/flutter_scene1 reaction · 10 comments
- Nov 6, 2023Automate updating `dartpad-workshops-io2021` — flutter/flutter1 reaction · 5 comments
- Feb 14, 2023Add "set up universal links" cookbook recipe — flutter/website1 reaction · 7 comments
- Oct 8, 2026wrong line of code in codelabs exercise — flutter/website0 reactions · 3 comments
- May 7, 2026feat: Flutter Tester — build & run any Flutter app from a GitHub URL or zip — mohammadalibalwe48-hub/Flutter-app0 reactions · 1 comment
- Apr 27, 2026Get to know Firebase for Flutter Codelab Issue — flutter/website0 reactions · 2 comments
- Oct 21, 2025`flutter/codelabs`: The Audio Soloud codelab is failing on main due to `experimental_member_use` lint failing — flutter/flutter0 reactions · 6 comments
- Jun 24, 2025Issue on `master`: pub is not an AOT snapshot, it cannot be run with 'dartaotruntime' — invertase/dart_custom_lint0 reactions · 1 comment
- Apr 25, 2025Fix dependencies dev.nix — flutter/ai0 reactions · 1 comment
- Mar 25, 2025VoiceOver Native iOS app crash with cacheExtent: double.infinity — flutter/flutter0 reactions · 6 comments
- Jan 21, 2025Running on Windows isn't happy — bdero/flutter_scene0 reactions · 10 comments
- Jan 5, 2025Firebase Flutter tutorial includes incorrect statement statement to define GuestBookState — flutter/website0 reactions · 2 comments
- Nov 19, 2024[Future] Update code to match new formatter style — flutter/website0 reactions
- Nov 6, 2024Bump examples/codelabs from `11bbf40` to `e438857` — khanhnwin/website0 reactions · 1 comment
- Oct 25, 2024Bump examples/codelabs from `11bbf40` to `3920ded` — khanhnwin/website0 reactions · 2 comments
- Oct 24, 2024Bump examples/codelabs from `11bbf40` to `f7a5728` — khanhnwin/website0 reactions · 2 comments
- Jun 17, 2024Bump examples/codelabs from `5211876` to `42192df` — toannmdev/flutter_test_l10n0 reactions · 1 comment
- Feb 8, 2024Bump examples/codelabs from `8b19a31` to `f2ba8d1` — AlexV525/flutter-website0 reactions · 2 comments
- Dec 1, 2023Bump examples/codelabs from `78adecc` to `4e2eb0c` — fong1966/website0 reactions · 1 comment
- Jun 14, 2023Bump examples/codelabs from `776582e` to `d828b96` — InMatrix/website0 reactions
- Jun 7, 2023Bump examples/codelabs from `d324e25` to `7fbeeda` — royarg02/website0 reactions
- Jun 5, 2023開発メモ — LeoAndo/flutter_use_palm_demo0 reactions · 4 comments
- Mar 26, 2023Gh — erickTsaf237/whats-view0 reactions
- Mar 6, 2023Bump examples/codelabs from `f551b92` to `887c00e` — qt-luigi/website0 reactions
- Mar 6, 2023Bump examples/codelabs from `094d6e0` to `887c00e` — yash1200/website0 reactions
- Mar 6, 2023Bump examples/codelabs from `91f843a` to `ebc73e7` — zanderso/website0 reactions
- Dec 28, 2022Worked examples of new Cupertino widgets missing — timsneath/landmarks_flutter0 reactions
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 0 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 15
Instead of manually editing generated step_XX/ directories across a codelab, changes should be captured in the codelab's …
- Very specific: line 78
Remove the leftover scratch project directory (rm -rf <codelab_dir>/<app_name>) so the next run starts from a clean state without leftover …
- Very specific: line 81
When upgrading a codelab for a newer Flutter SDK, flutter create output may differ from when the blueprint was written:
- Very specific: line 85
When a step fails (for example, a patch-u hunk no longer applies cleanly after a flutter create template change or package upgrade):
- Very specific: line 91
Run codelab_rebuild <codelab_dir>/codelab_rebuild.yaml.
- Very specific: line 93
Remove the stop: true step once resolved.
- Very specific: line 96
Always prefer patch-u over patch or patch-c.
- Very specific: line 99
If a file is small or changes almost entirely between steps, using replace-contents: | is often less brittle across Flutter SDK upgrades …
- Very specific: line 102
When patch -u runs during a rebuild:
- Very specific: line 107
Check for any .orig or .rej files in the codelab directory:
- Very specific: line 131
After rebuilding a codelab or modifying tooling/codelab_rebuild:
- Very specific: line 134
If lib/src/blueprint.dart changed, regenerate JSON serialization code:
- Very specific: line 139
Run the tool's unit tests and analyzer inside tooling/codelab_rebuild:
- Very specific: line 151
Ensure no .orig or .rej files were left behind by fuzzy/offset patches (find <codelab_dir> -name "*.orig" -o -name "*.rej" should return no …
- Very specific: line 152
Ensure git status shows no leftover scratch directory (e.g., <app_name>/ was cleaned up by the final step).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Codelab Rebuild & codelab_rebuild.yaml Maintenance
Codelabs in this repository are generated and maintained from declarative codelab_rebuild.yaml blueprints using the custom codelab_rebuild tool located in tooling/codelab_rebuild.
Instead of manually editing generated step_XX/ directories across a codelab, changes should be captured in the codelab's codelab_rebuild.yaml so the entire progression can be deterministically recreated against new Flutter/Dart releases.
1. Running codelab_rebuild
Activate or Run the Tool
From the repository root, you can either activate the tool globally once:
dart pub global activate --source path tooling/codelab_rebuildAnd invoke it on a blueprint:
codelab_rebuild <codelab_dir>/codelab_rebuild.yamlOr run it directly via dart run from the repository root:
dart run tooling/codelab_rebuild/bin/codelab_rebuild.dart <codelab_dir>/codelab_rebuild.yamlNote:
codelab_rebuildexecutes all steps with its working directory set to the parent directory of thecodelab_rebuild.yamlfile (e.g.,<codelab_dir>/). Allpath,mkdir,rmdir,copy, andcopydirvalues in the YAML are relative to that codelab directory.
2. Standard codelab_rebuild.yaml Architecture
A typical codelab_rebuild.yaml maintains a single scratch project directory (e.g., <app_name>/), incrementally evolves it from step to step, copies snapshots to step_XX/ directories, and deletes the scratch directory at the end:
- Initial Step (e.g.,
step_02orstep_03):rmdir: step_02(removes the old generated step directory).flutter: create <app_name> ...(creates a fresh Flutter project using the current SDK).strip-lines-containing: DEVELOPMENT_TEAM =on<app_name>/ios/Runner.xcodeproj/project.pbxproj.- Configures
<app_name>/analysis_options.yaml(usuallyinclude: ../../analysis_options.yaml). - Removes
<app_name>/README.md(rm) and adds.vscode/launch.jsonand.gemini/settings.jsonviamkdir+replace-contents. - Adds dependencies via
flutter: pub add ...and upgrades withflutter: pub upgrade --major-versions. - Populates initial source files and assets (
replace-contents,base64-contents, orpatch-u). - Optionally verifies builds (
flutter: clean, platform-gatedflutter: build ...). - Snapshots the working directory into the step folder:
- name: Copy step_02 copydir: from: <app_name> to: step_02
- Subsequent Steps (
step_03,step_04, ...):rmdir: step_XX(cleans previous snapshot).- Applies incremental modifications to
<app_name>/...usingpatch-u(for existing files) orreplace-contents(for new or completely replaced files). - Runs code generation or build verification if needed (
dart: run build_runner ...,flutter: clean,flutter: build ...). - Copies
<app_name>tostep_XXviacopydir.
- Final Cleanup:
- Removes the temporary working directory (
rmdir: <app_name>).
- Removes the temporary working directory (
3. Maintaining & Debugging codelab_rebuild.yaml
For the complete list of supported YAML keys, types, and validation rules, read the Blueprint Schema Reference.
Recovering from a Failed Rebuild
Each step in codelab_rebuild.yaml typically starts with rmdir: step_XX, which calls deleteSync(recursive: true) and throws a PathNotFoundException if step_XX does not exist on disk. When a rebuild fails mid-way through a step (after rmdir: step_XX has already run):
- Recreate any missing
step_XXdirectory before re-running (e.g.,mkdir -p <codelab_dir>/step_XXorgit checkout -- <codelab_dir>/step_XX). - Remove the leftover scratch project directory (
rm -rf <codelab_dir>/<app_name>) so the next run starts from a clean state without leftover.rej/.origpatch artifacts.
Adapting to flutter create Template Changes
When upgrading a codelab for a newer Flutter SDK, flutter create output may differ from when the blueprint was written:
material_uidefault import and version constraint: Recent Flutter SDKs includematerial_uiinpubspec.yamland generateimport 'package:material_ui/material_ui.dart';(instead ofimport 'package:flutter/material.dart';) inlib/main.dart, including withflutter create --empty. Update any initialpatch-uhunks onlib/main.dartthat still expectpackage:flutter/material.dart. However, do not removematerial_uifromflutter: pub add ...:flutter createwrites an older template constraint (e.g.,material_ui: ^1.1.0) inpubspec.yamleven whenpubspec.lockresolves to a newer version (e.g.,1.11.0), andflutter pub upgrade --major-versionsonly bumps major version constraints, leaving^1.1.0inpubspec.yaml. Keepingmaterial_uiinflutter: pub add ...(or runningflutter: pub upgrade --tighten) ensures thematerial_uiconstraint inpubspec.yamlis updated to the latest resolved version (e.g.,^1.11.0) rather than downgraded.
Incremental Debugging with stop: true
When a step fails (for example, a patch-u hunk no longer applies cleanly after a flutter create template change or package upgrade):
- Insert a temporary stop step right before or after the failing step:
- name: Stop for debugging stop: true - Run
codelab_rebuild <codelab_dir>/codelab_rebuild.yaml. The tool will execute up to that point and leave the<app_name>/scratch directory intact on disk. - Inspect the actual file in
<codelab_dir>/<app_name>/..., make the desired edits, and generate a clean unified diff. - Remove the
stop: truestep once resolved.
Generating patch-u Unified Diffs
Always prefer patch-u over patch or patch-c.
- To generate a unified diff for a modified file, use
git diff -U3(ordiff -u) between the prior state and the updated state, and paste the output underpatch-u: |. - Note that
codelab_rebuildinvokespatch -u <fullPath>directly on the target file specified bypath:, so the---/+++header paths in the diff are ignored bypatchin favor ofpath:, but keeping them accurate improves readability. - If a file is small or changes almost entirely between steps, using
replace-contents: |is often less brittle across Flutter SDK upgrades thanpatch-u.
Detecting and Fixing .orig and .rej Patch Artifacts
When patch -u runs during a rebuild:
.origfiles are created bypatch(notably BSDpatchon macOS) when a hunk succeeds with a line offset or fuzz because upstream template files (e.g.,web/index.html,pubspec.yaml,Info.plist) gained or lost lines in a newer Flutter SDK. Becausepatchstill exits with0, the rebuild succeeds, andcopydircopies the leftover<file>.origintostep_XX/and all subsequent steps..rejfiles (along with.origfiles) are created when a hunk fails to apply altogether.
To correct .orig or .rej files:
- Check for any
.origor.rejfiles in the codelab directory:find <codelab_dir> -name "*.orig" -o -name "*.rej" - Locate the
patch-ustep incodelab_rebuild.yamltargeting the base file (e.g.,web/index.htmlforweb/index.html.orig). - Regenerate the unified diff (
diff -uorgit diff -U3) against the actual file state prior to that patch—or update the@@ -start,count +start,count @@hunk header and context lines so the hunk applies at the exact line number with zero offset and zero fuzz. - Re-run
codelab_rebuild <codelab_dir>/codelab_rebuild.yaml(do not just delete the.origfile manually, or the next rebuild will recreate it) and confirmfind <codelab_dir> -name "*.orig" -o -name "*.rej"returns nothing.
Encoding Binary Assets (base64-contents)
To embed fonts, images, or other binary files in codelab_rebuild.yaml, encode the file and wrap lines at 76 characters (note that codelab_rebuild strips all newlines before decoding, so wrapping is purely for YAML readability):
# Cross-platform (POSIX sh, macOS & Linux):
base64 < path/to/asset.png | fold -w 76
# Or using platform-specific flags:
base64 -b 76 < path/to/asset.png # macOS (BSD base64)
base64 -w 76 < path/to/asset.png # Linux (GNU base64; 76 is also the default)Paste the multi-line base64 string into a step with path and base64-contents: |.
4. Verification Checklist
After rebuilding a codelab or modifying tooling/codelab_rebuild:
- If you modified
tooling/codelab_rebuild:- If
lib/src/blueprint.dartchanged, regenerate JSON serialization code:
(run insidedart run build_runner build --delete-conflicting-outputstooling/codelab_rebuild). - Run the tool's unit tests and analyzer inside
tooling/codelab_rebuild:dart analyze dart test
- If
- Verify the Rebuilt Codelab:
Match the checks in
flutter_ci_script_shared.shfor every generated project in<codelab_dir>:flutter pub getdart analyze --fatal-infos --fatal-warningsdart format --output none --set-exit-if-changed lib(and includetestif atest/directory exists; note thatflutter create --emptyomitstest/)flutter test(ordart testfor pure Dart projects, if atest/directory exists)- Ensure no
.origor.rejfiles were left behind by fuzzy/offset patches (find <codelab_dir> -name "*.orig" -o -name "*.rej"should return no results). - Ensure
git statusshows no leftover scratch directory (e.g.,<app_name>/was cleaned up by the final step).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

