Every SvelteKit project I have worked on hits the same wall around the twentieth route. The app runs fine, but nobody can answer a simple question anymore: where does this file go? Business logic slips into +page.server.ts
, a utils.ts
grows to 600 lines, and one day you find a database client imported straight into a component.
There is a lot of advice out there about folder structure, but most of it is either a beginner tutorial or a single opinionated layout presented as the only right answer. Real projects are messier than that. A structure that is perfect for a three route side project is wrong for a forty engineer platform, and the reverse is also true.
So I built a Claude skill that treats project structure the way a senior architect would: it asks about your scale and team, explains tradeoffs instead of handing down rules, and never pretends there is one correct layout.
The skill works in two modes.
Design from scratch. It does not jump straight to a folder tree. It first asks about the size, the team, the domain, and how long the project needs to live, then recommends the simplest structure that will not need reworking too soon. Over engineering a small app is just as costly as under engineering a large one.
Review an existing project. This is where it earns its keep. It traces a feature end to end, probes the server and client boundary, runs a checklist, and produces a report with an executive summary, strengths, weaknesses ordered by impact, an architecture score from one to ten, immediate and long term improvements, a suggested folder tree, a migration plan, risks, and a final recommendation.
Here is a taste of the weaknesses section from a review of a messy sample app:
- [Critical] Server/client boundary leak. lib/stripe.ts uses the secret and is
imported inside a component. Risk of shipping credentials to the browser.
- [High] Per-user state in module scope. lib/store.ts exports currentUser at
module level, which leaks data between users on the server.
- [Medium] God utility. utils.ts (600 lines) mixes dates, currency, DB helpers,
fetch, and DOM. A dependency and cycle magnet.
Each finding comes with where it shows up, why it will hurt as the project grows, and how to fix it incrementally so the app stays deployable at every step.
Generic frontend advice does not help here, because SvelteKit's conventions are load bearing. The $lib/server
boundary is a real security guarantee enforced by the build. The $env
modules decide what can reach the browser. Route groups organize the URL tree without adding segments. Runes changed how shared state is organized. The skill is built around these mechanics, and it labels features as stable, experimental, or deprecated so the guidance stays honest as the framework evolves.
It also avoids hardcoding version numbers and links to the official docs throughout, so it does not rot every time a new version ships.
The skill lives on GitHub and installs with a single command through the skills CLI, which works with Claude Code and other agents:
npx skills add poolcamacho/sveltekit-project-structure
Then just ask naturally. Things like "review the structure of my SvelteKit app", "where should this billing logic live?", or "design a folder layout for a multi tenant SvelteKit SaaS" all trigger it.
Two principles run through the whole thing.
First, maintainability over cleverness. A layout a new teammate can navigate in ten minutes beats an elegant one only its author understands.
Second, fit over dogma. No single architecture is universally correct, so every recommendation comes with why it exists, when to apply it, when not to, and the alternatives.
The code and the full reference material are on GitHub: poolcamacho/sveltekit-project-structure. If you try it on a real project, I would love to hear what score it gave you and whether the migration plan held up.