FRAMEWORK DEVELOPMENT / Svelte
Svelte Core Best Practices
Svelte-maintained guidance for reactivity, component composition and integration with browser APIs.
“Guidance on writing fast, robust, modern Svelte code. Load this skill whenever in a Svelte project and asked to write/edit or analyze a Svelte component or module. Covers reactivity, event handling, styling, integration with libraries and more.”
01 / THE REASONING
Why this made the selection.
- Explains when to derive state instead of synchronizing it with effects, and when reactive wrappers or subscriptions are needed.
- Includes focused references for attachments, bindings, keyed lists, snippets and hydration rather than reducing modern Svelte to a component style checklist.
02 / THE REVIEW RECORD
What we actually inspected.
Source review has boundaries.
A clear record is more useful than a “safe” badge.
Material inspected
- tools/skills/svelte-core-bestpractices/SKILL.md
- SKILL.md at 5c15fbcb, diffed against 6b5d0dab
- documentation/docs/40-skills/10-skills.md
- documentation/docs/60-plugins/10-claude-plugin.md
- README.md (MCP server development setup only)
- LICENSE
- tools/skills/svelte-core-bestpractices/references/attach.md
- tools/skills/svelte-core-bestpractices/references/await-expressions.md
- tools/skills/svelte-core-bestpractices/references/bind.md
- tools/skills/svelte-core-bestpractices/references/each.md
- tools/skills/svelte-core-bestpractices/references/hydratable.md
- tools/skills/svelte-core-bestpractices/references/inspect.md
- tools/skills/svelte-core-bestpractices/references/render.md
- tools/skills/svelte-core-bestpractices/references/snippet.md
- tools/skills/svelte-core-bestpractices/references/svelte-reactivity.md
Our findings
- SKILL.md tells the agent to compute values with $derived rather than $effect, to treat $effect as an escape hatch, and to reach for {@attach}, event handlers, $inspect or createSubscriber instead.
- Its legacy-features list maps older patterns to replacements: export let to $props, on:click to onclick, <slot> to snippets, use:action to {@attach}, stores to classes with $state fields.
- The repository README covers MCP server development setup only. Skill hosts and the manual install folders (.claude/skills, .copilot/skills, .opencode/skills) are documented in documentation/docs/40-skills/10-skills.md.
- Guidance is qualitative; this review did not benchmark the suggested patterns or compile every example.
- Re-pinned from 5c15fbcb5b630ac8ce0281ee1782fc2056fab853 to 6b5d0dab3c9c083387247ab20dc684573481076b: only SKILL.md changed. It adds a #key section warning that the block unmounts everything inside it on each change, and says experimental.async can be set in the Vite plugin options as well as svelte.config.js. The nine references, LICENSE and README are byte-identical.
Not established by this review
- No upstream definition, helper, installer or generated workload was executed.
- No end-to-end agent session or effectiveness benchmark was run.
The review applies to the material and revision named here. A newer upstream release can change its behavior.
03 / PUT IT TO WORK
Add a skill to your workflow.
DOCUMENTED COMMAND
npx skills add sveltejs/ai-tools/tools/skills/svelte-core-bestpractices --skill svelte-core-bestpractices Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.
Optional: install the reviewed revision
Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose.
npx skills add https://github.com/sveltejs/ai-tools/tree/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices --skill svelte-core-bestpractices - Install the complete skill directory, including its references and helpers; select your AI tools and project or global scope.
- Review the instructions before invoking them. The source revision shown here is the one reviewed; the installer was not executed or version-pinned by this review.
- Claude Code alternative from documentation/docs/60-plugins/10-claude-plugin.md: /plugin marketplace add sveltejs/ai-tools, then /plugin install svelte. That plugin also brings the Svelte stdio MCP server and a file-editor agent, which this review did not inspect.
- For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/svelte-svelte-core-bestpractices/bundle.zip and extract it into a new directory. It holds SKILL.md and 9 supporting files unchanged at revision 6b5d0dab, the upstream licence and an attribution file.
- Place the extracted directory in your host's documented skills directory, named svelte-core-bestpractices. Keep SKILL.md and the licence together.
Before you start
- Node.js/npm and git for the documented Skills installer
- An agent host that supports the skill format and the tools required by the workflow
THE COMPLETE REVIEWED DEFINITION
Read it before you reuse it.
Original source bytes, with attribution.
Review the host-specific setup notes above.
---
name: svelte-core-bestpractices
description: Guidance on writing fast, robust, modern Svelte code. Load this skill whenever in a Svelte project and asked to write/edit or analyze a Svelte component or module. Covers reactivity, event handling, styling, integration with libraries and more.
---
## `$state`
Only use the `$state` rune for variables that should be _reactive_ — in other words, variables that cause an `$effect`, `$derived` or template expression to update. Everything else can be a normal variable.
Objects and arrays (`$state({...})` or `$state([...])`) are made deeply reactive, meaning mutation will trigger updates. This has a trade-off: in exchange for fine-grained reactivity, the objects must be proxied, which has performance overhead. In cases where you're dealing with large objects that are only ever reassigned (rather than mutated), use `$state.raw` instead. This is often the case with API responses, for example.
## `$derived`
To compute something from state, use `$derived` rather than `$effect`:
```js
// do this
let square = $derived(num * num);
// don't do this
let square;
$effect(() => {
square = num * num;
});
```
> [!NOTE] `$derived` is given an expression, _not_ a function. If you need to use a function (because the expression is complex, for example) use `$derived.by`.
Deriveds are writable — you can assign to them, just like `$state`, except that they will re-evaluate when their expression changes.
If the derived expression is an object or array, it will be returned as-is — it is _not_ made deeply reactive. You can, however, use `$state` inside `$derived.by` in the rare cases that you need this.
## `$effect`
Effects are an escape hatch and should mostly be avoided. In particular, avoid updating state inside effects.
- If you need to sync state to an external library such as D3, it is often neater to use [`{@attach ...}`](references/attach.md)
- If you need to run some code in response to user interaction, put the code directly in an event handler or use a [function binding](references/bind.md) as appropriate
- If you need to log values for debugging purposes, use [`$inspect`](references/inspect.md)
- If you need to observe something external to Svelte, use [`createSubscriber`](references/svelte-reactivity.md)
Never wrap the contents of an effect in `if (browser) {...}` or similar — effects do not run on the server.
## `$props`
Treat props as though they will change. For example, values that depend on props should usually use `$derived`:
```js
// @errors: 2451
let { type } = $props();
// do this
let color = $derived(type === 'danger' ? 'red' : 'green');
// don't do this — `color` will not update if `type` changes
let color = type === 'danger' ? 'red' : 'green';
```
## `$inspect.trace`
`$inspect.trace` is a debugging tool for reactivity. If something is not updating properly or running more than it should you can add `$inspect.trace(label)` as the first line of an `$effect` or `$derived.by` (or any function they call) to trace their dependencies and discover which one triggered an update.
## `#key` block
While the `#key` block is useful when you want transitions/animations to run when a certain expression changes, it can be very expensive — it unmounts every element/component inside each time, so should be used sparingly. Instead of using `#key` to cause expressions in a child component's `<script>` block to re-run, for example, consider wrapping those expressions in `$derived`.
## Events
Any element attribute starting with `on` is treated as an event listener:
```svelte
<button onclick={() => {...}}>click me</button>
<!-- attribute shorthand also works -->
<button {onclick}>...</button>
<!-- so do spread attributes -->
<button {...props}>...</button>
```
If you need to attach listeners to `window` or `document` you can use `<svelte:window>` and `<svelte:document>`:
```svelte
<svelte:window onkeydown={...} />
<svelte:document onvisibilitychange={...} />
```
Avoid using `onMount` or `$effect` for this.
## Snippets
[Snippets](references/snippet.md) are a way to define reusable chunks of markup that can be instantiated with the [`{@render ...}`](references/render.md) tag, or passed to components as props. They must be declared within the template.
```svelte
{#snippet greeting(name)}
<p>hello {name}!</p>
{/snippet}
{@render greeting('world')}
```
> [!NOTE] Snippets declared at the top level of a component (i.e. not inside elements or blocks) can be referenced inside `<script>`. A snippet that doesn't reference component state is also available in a `<script module>`, in which case it can be exported for use by other components.
## Each blocks
Prefer to use [keyed each blocks](references/each.md) — this improves performance by allowing Svelte to surgically insert or remove items rather than updating the DOM belonging to existing items.
> [!NOTE] The key _must_ uniquely identify the object. Do not use the index as a key.
Avoid destructuring if you need to mutate the item (with something like `bind:value={item.count}`, for example).
## Using JavaScript variables in CSS
If you have a JS variable that you want to use inside CSS you can set a CSS custom property with the `style:` directive.
```svelte
<div style:--columns={columns}>...</div>
```
You can then reference `var(--columns)` inside the component's `<style>`.
## Styling child components
The CSS in a component's `<style>` is scoped to that component. If a parent component needs to control the child's styles, the preferred way is to use CSS custom properties:
```svelte
<!-- Parent.svelte -->
<Child --color="red" />
<!-- Child.svelte -->
<h1>Hello</h1>
<style>
h1 {
color: var(--color);
}
</style>
```
If this is impossible (for example, the child component comes from a library) you can use `:global` to override styles:
```svelte
<div>
<Child />
</div>
<style>
div :global {
h1 {
color: red;
}
}
</style>
```
## Context
Consider using context instead of declaring state in a shared module. This will scope the state to the part of the app that needs it, and eliminate the possibility of it leaking between users when server-side rendering.
Use `createContext` rather than `setContext` and `getContext`, as it provides type safety.
## Async Svelte
If using version 5.36 or higher, you can use [await expressions](references/await-expressions.md) and [hydratable](references/hydratable.md) to use promises directly inside components. Note that these require the `experimental.async` option to be enabled in the plugin options in `vite.config.js` or in the `svelte.config.js` as they are not yet considered fully stable.
## Avoid legacy features
Always use runes mode for new code, and avoid features that have more modern replacements:
- use `$state` instead of implicit reactivity (e.g. `let count = 0; count += 1`)
- use `$derived` and `$effect` instead of `$:` assignments and statements (but only use effects when there is no better solution)
- use `$props` instead of `export let`, `$$props` and `$$restProps`
- use `onclick={...}` instead of `on:click={...}`
- use `{#snippet ...}` and `{@render ...}` instead of `<slot>` and `$$slots` and `<svelte:fragment>`
- use `<DynamicComponent>` instead of `<svelte:component this={DynamicComponent}>`
- use `import Self from './ThisComponent.svelte'` and `<Self>` instead of `<svelte:self>`
- use classes with `$state` fields to share reactivity between components, instead of using stores
- use `{@attach ...}` instead of `use:action`
- use clsx-style arrays and objects in `class` attributes, instead of the `class:` directive
The download contains SKILL.md. Extract the whole bundle; the supporting files are required. Inspect the included MANIFEST.json for file hashes.
By Svelte. Exact upstream source ↗ · Licence · Attribution
SHA-256 96e025333e54533a31d37f70c7094da8df8b89c3c622a70d7edbf6332b84da47
Read the applicable licence
MIT License Copyright (c) 2026 [Svelte Contributors](https://github.com/sveltejs/ai-tools/graphs/contributors) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/SKILL.md
Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, access
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/LICENSE
Supports: license, access.cost
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/documentation/docs/40-skills/10-skills.md
Supports: install, compatibility
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/documentation/docs/60-plugins/10-claude-plugin.md
Supports: install
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/references/attach.md
Supports: review, limitations, install, access
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/references/await-expressions.md
Supports: review, limitations, install, access
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/references/bind.md
Supports: review, limitations, install, access
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/references/each.md
Supports: review, limitations, install, access
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/references/hydratable.md
Supports: review, limitations, install, access
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/references/inspect.md
Supports: review, limitations, install, access
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/references/render.md
Supports: review, limitations, install, access
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/references/snippet.md
Supports: review, limitations, install, access
https://github.com/sveltejs/ai-tools/blob/6b5d0dab3c9c083387247ab20dc684573481076b/tools/skills/svelte-core-bestpractices/references/svelte-reactivity.md
Supports: review, limitations, install, access
https://svelte.dev/docs/ai/skills
Supports: install, compatibility
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md
Supports: install
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts
Supports: install
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/source-parser.ts
Supports: install