agentleFS
baseballyamabaseballyama/rsvelte/.claude/skills/upgrade-svelte/SKILL.md

upgrade-svelte

Skill252 starsChanged 2 months agoMITView on GitHub

Upgrade the Svelte submodule to the latest (or specified) version, regenerate fixtures, identify test failures, and fix all regressions until tests pass 100%.

  • Installs packages
  • Commits and pushes

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use $ARGUMENTS if given (e.g.

    line 25
  2. Distinctive:

    Read the reference implementation first.

    line 99
  3. Very specific:

    Commit before the next failure: cargo fmt && cargo clippy --all-targets --all-features -- -D warnings && git add -u && git commit -m "fix: …

    line 106
  4. Distinctive:

    Use subagents for parallel investigation when several categories fail.

    line 109

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Upgrade Svelte Submodule

Upgrade submodules/svelte, regenerate fixtures, and fix every regression until the compatibility report is 100%.

Phase 1: Upgrade   → checkout tag, build compiler, regenerate fixtures (script)
Phase 2: Assess    → read the compatibility report, group failures by cause
Phase 3: Fix       → one category at a time, one commit per fix
Phase 4: Validate  → full report, cargo test --release, docs, commit

Phase 1: Upgrade

1.1 Pick the version

Use $ARGUMENTS if given (e.g. 5.52.0). Otherwise take the latest stable svelte@* tag (skip next / rc); confirm with the user if ambiguous.

cd submodules/svelte && git fetch --tags && git tag -l 'svelte@*' --sort=-version:refname | head -5

1.2 Run the upgrade script

./scripts/dev/upgrade-svelte.sh <VERSION>

It performs, in order: submodule checkout → writes crates/rsvelte_core/svelte-version.txt → pnpm install && pnpm build in submodules/svelte/packages/svelte (compiler/index.js is gitignored, so this step is mandatory) → generate-fixtures --force → compatibility-report → update-docs → bumps apps/playground/src/lib/preview.ts and apps/playground/rsvelte-shim/compiler.mjs.

Step failsTry
pnpm installpnpm install --no-frozen-lockfile
pnpm buildNode >= 22? new build deps?
generate-fixturesSvelte's compile/test API changed — read the error

1.3 Read what changed upstream

cd submodules/svelte
git log --oneline svelte@<OLD>..svelte@<NEW> -- packages/svelte/src/compiler/
git diff --stat  svelte@<OLD>..svelte@<NEW> -- packages/svelte/src/compiler/

Also packages/svelte/CHANGELOG.md. Look for: new syntax, changed codegen output, new/removed/renamed compiler options, CSS scoping changes, new warning/error codes.

Phase 2: Assess

2.1 Read the report

COMMIT=$(git -C submodules/svelte rev-parse --short=12 HEAD)
node -e "
const r = require('./fixtures/${COMMIT}/compatibility-report.json');
const s = r.summary;
console.log('Overall: ' + s.total_passed + '/' + (s.total_tests - s.total_skipped) + ' (' + s.overall_percentage.toFixed(1) + '%)');
for (const [cat, d] of Object.entries(r.categories)) {
  const st = d.stats;
  if (st.failed || st.errors) console.log(cat + ': ' + st.passed + '/' + st.total + ' failed=' + st.failed + ' errors=' + st.errors);
}"

2.2 Categorize, then order

PatternFix in
New AST node typeparser + crates/rsvelte_core/src/ast/template.rs
Changed codegen outputtransform phase
New compiler optionCompileOptions + plumbing
New warning/error codevalidator + crates/rsvelte_core/src/error/
CSS output changed3_transform/css.rs
Renamed internal APImirror the rename

Fix order: parser → compiler errors → validator warnings → CSS → SSR → snapshot (client) → runtime (depends on everything above).

Phase 3: Fix regressions

Mirror layout: submodules/svelte/packages/svelte/src/compiler/phases/{1-parse,2-analyze,3-transform}/ → crates/rsvelte_core/src/compiler/phases/{1_parse,2_analyze,3_transform}/; errors.js / warnings.js → crates/rsvelte_core/src/error/.

For each failure:

  1. Read the reference implementation first; use the same algorithm and structure.
  2. Diff the fixture (fixtures/${COMMIT}/<category>/<sample>/…) against rsvelte's output.
  3. Implement in the mirror module. New feature: ast/template.rs → 1_parse → 2_analyze → 3_transform/client → 3_transform/server → 3_transform/css.rs if CSS-related.
  4. Changed codegen: rg "<unique output string>" submodules/svelte/packages/svelte/src/compiler/, then the same string under crates/rsvelte_core/src/compiler/.
  5. Verify: cargo test --release <test_name> -- --nocapture
  6. Commit before the next failure: cargo fmt && cargo clippy --all-targets --all-features -- -D warnings && git add -u && git commit -m "fix: <what>"

Use subagents for parallel investigation when several categories fail.

Phase 4: Validate & ship

pnpm run compatibility-report      # must be 0 failures, 0 errors in every category
cargo test --release               # runtime/ssr suites; audit_skipped re-checks the skip lists
pnpm run update-docs               # README.md + apps/playground/static/test-results.json
./scripts/bench/bench.sh --quick   # only if codegen hot paths changed

Also update AGENTS.md (Test Status table and the Svelte **vX.Y.Z** line) if numbers moved. The former USE_RSVELTE=true npx vitest step is gone: nothing in submodules/svelte reads that variable; runtime parity is the Runtime * rows of the report.

git add -A
git commit -m "chore: upgrade Svelte to <VERSION>

- Updated submodule to svelte@<VERSION>
- Regenerated all test fixtures
- Fixed N regressions: <brief list>
- Compatibility report 100%"
git push

Quick reference

cd submodules/svelte && git describe --tags --abbrev=0          # current version
./scripts/dev/upgrade-svelte.sh <VERSION>                        # automated Phase 1
pnpm run compatibility-report                                    # report → fixtures/<commit>/compatibility-report.json
cargo test --release <test_name> -- --nocapture                  # single test
pnpm run update-docs                                             # docs
cargo fmt && cargo clippy --all-targets --all-features -- -D warnings

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.