file-organization_skill

Overview

This skill organizes project files and folders for maintainability and scalability. It provides opinionated templates and naming conventions for frontend (React/Next.js), backend (Node/Express), and large feature-based apps. Use it to design new projects, refactor structures as projects grow, or establish team-wide standards. The goal is clear responsibilities, shallow folder depth, and consistent imports.

How this skill works

I inspect your project type and suggest a minimal, role-oriented folder layout (app, components, lib, services, models, etc.). I recommend naming conventions for files, folders, variables, and exports, plus barrel file patterns and tsconfig path aliases. I also enforce constraints: consistent rules across the team, maximum recommended depth, and patterns to avoid (ambiguous names, excessive nesting, circular dependencies).

When to use it

• Starting a new web or API project and you need a scalable folder template
• Refactoring an existing codebase to reduce complexity and improve discoverability
• Onboarding a team and establishing consistent naming and export patterns
• Splitting a monolith into feature modules or migrating to a feature-based layout
• Setting up build-time path aliases and barrel files to simplify imports

Best practices

• Keep maximum folder depth small (recommend <=5 levels) and avoid deep nested folders
• Co-locate related files: component, styles, and tests together in the same folder
• Prefer descriptive folder names that reflect responsibilities (api, services, models)
• Use consistent naming: PascalCase for components, camelCase for hooks/utils, UPPER_SNAKE_CASE for constants
• Create selective barrel files with named re-exports to preserve tree-shaking
• Use path aliases (e.g. @/) to simplify imports and avoid long relative paths

Example use cases

• Next.js app: provide src/app, components/ui, lib/hooks, store, types and global config
• Node/Express API: structure with api/routes, controllers, services, repositories, models and database
• Large app: convert to feature-based layout where each feature contains components, hooks, api, store and types
• Refactor: replace ambiguous folders like helpers/ and utils2/ with purpose-named folders and consolidate responsibilities
• Team standardization: share naming rules and tsconfig path mappings to enforce consistent imports