Feature-Sliced Design: Agent Skills

Agent skills that teach AI coding agents how to apply the Feature-Sliced Design (FSD) v2.1 methodology.

Installation

npx skills add feature-sliced/skills

Available skills

feature-sliced-design

Apply FSD v2.1 principles when structuring frontend projects. The agent learns layer hierarchy, import rules, the decision framework for code placement, and common patterns.

Its bias is pages-first: start with app/, pages/, and shared/, and open a features or entities boundary only when a stable shared responsibility has earned one. Code used in two places does not, by itself, earn a layer.

It follows the official FSD v2.1 documentation but is not a verbatim copy. Where two official guides answer the same question differently, it picks one and says which. Where an integration guide has fallen behind a framework's own docs, it follows the framework. It also folds in recent maintainer guidance so an agent decides consistently across tasks. Passages that depart from a guide say so inline.

Use when:

• Setting up or reorganizing a frontend project structure
• Deciding where code belongs across app, pages, features, entities, and shared
• Placing static assets (images, icons, fonts, PDFs) in the right slice or layer
• Grouping closely related slices into slice groups as the project grows
• Deciding where page layouts belong, or whether to use the widgets layer (discouraged)
• Resolving cross-import issues or evaluating the @x pattern
• Deciding whether to create or remove an entity, or whether to skip the entities layer entirely
• Migrating from FSD v2.0 or a non-FSD codebase
• Integrating FSD with Next.js (App Router or Pages Router), React Router, Nuxt, Vite, or Astro
• Implementing auth, API request handling, or state management (Redux, TanStack Query) within FSD

Examples:

Set up FSD project structure with Next.js App Router

This rule is used on two pages now. Should it become an entity?

Where should I put auth tokens and session state?

These two entities need to import from each other. How do I fix this?

Where should I put hero images for my landing page?

Skill structure

feature-sliced-design/
  SKILL.md                         Core rules and decision framework
  references/
    layer-structure.md             Detailed folder structures per layer (incl. slice groups)
    growth-walkthrough.md          One shop through four snapshots: which moments earn a layer
    asset-handling.md              Where to place images, icons, fonts, and other static assets
    cross-import-patterns.md       Cross-import resolution: 4 strategies for features/widgets, @x for entities
    excessive-entities.md          Keeping the entities layer clean: when to skip, what to extract
    migration-guide.md             v2.0→v2.1 and non-FSD migration
    framework-integration.md       Next.js, React Router, Nuxt, Vite, Astro setup
    auth-and-api.md                Auth, type definitions, API request handling
    state-management.md            Redux, TanStack Query (React Query)
  evals/
    README.md                      How to grade and maintain the cases
    evals.json                     Placement regression cases

SKILL.md is the entry point. It tells the agent to read a reference file only when the task calls for it, so the initial context stays small.

Contributing