ReddRadar
Agent skill
file-organization
Organize project files and folders for maintainability and scalability. Use when structuring new projects, refactoring folder structure, or establishing conventions. Handles project structure, naming conventions, and file organization best practices.
Install this agent skill to your Project
npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/supercent-io/file-organization
Metadata
Additional technical details for this skill
- tags
- file-organization, project-structure, folder-structure, naming-conventions
- platforms
- Claude, ChatGPT, Gemini
SKILL.md
Project File Organization
When to use this skill
- New Projects: Initial folder structure design
- Project Growth: Refactoring when complexity increases
- Team Standardization: Establish consistent structure
Instructions
Step 1: React/Next.js Project Structure
src/
├── app/ # Next.js 13+ App Router
│ ├── (auth)/ # Route groups
│ │ ├── login/
│ │ └── signup/
│ ├── (dashboard)/
│ │ ├── layout.tsx
│ │ ├── page.tsx
│ │ └── settings/
│ ├── api/ # API routes
│ │ ├── auth/
│ │ └── users/
│ └── layout.tsx
│
├── components/ # UI Components
│ ├── ui/ # Reusable UI (Button, Input)
│ │ ├── Button/
│ │ │ ├── Button.tsx
│ │ │ ├── Button.test.tsx
│ │ │ └── index.ts
│ │ └── Input/
│ ├── layout/ # Layout components (Header, Footer)
│ ├── features/ # Feature-specific components
│ │ ├── auth/
│ │ └── dashboard/
│ └── shared/ # Shared across features
│
├── lib/ # Utilities & helpers
│ ├── utils.ts
│ ├── hooks/
│ │ ├── useAuth.ts
│ │ └── useLocalStorage.ts
│ └── api/
│ └── client.ts
│
├── store/ # State management
│ ├── slices/
│ │ ├── authSlice.ts
│ │ └── userSlice.ts
│ └── index.ts
│
├── types/ # TypeScript types
│ ├── api.ts
│ ├── models.ts
│ └── index.ts
│
├── config/ # Configuration
│ ├── env.ts
│ └── constants.ts
│
└── styles/ # Global styles
├── globals.css
└── theme.ts
Step 2: Node.js/Express Backend Structure
src/
├── api/ # API layer
│ ├── routes/
│ │ ├── auth.routes.ts
│ │ ├── user.routes.ts
│ │ └── index.ts
│ ├── controllers/
│ │ ├── auth.controller.ts
│ │ └── user.controller.ts
│ └── middlewares/
│ ├── auth.middleware.ts
│ ├── errorHandler.ts
│ └── validation.ts
│
├── services/ # Business logic
│ ├── auth.service.ts
│ ├── user.service.ts
│ └── email.service.ts
│
├── repositories/ # Data access layer
│ ├── user.repository.ts
│ └── session.repository.ts
│
├── models/ # Database models
│ ├── User.ts
│ └── Session.ts
│
├── database/ # Database setup
│ ├── connection.ts
│ ├── migrations/
│ └── seeds/
│
├── utils/ # Utilities
│ ├── logger.ts
│ ├── crypto.ts
│ └── validators.ts
│
├── config/ # Configuration
│ ├── index.ts
│ ├── database.ts
│ └── env.ts
│
├── types/ # TypeScript types
│ ├── express.d.ts
│ └── models.ts
│
├── __tests__/ # Tests
│ ├── unit/
│ ├── integration/
│ └── e2e/
│
└── index.ts # Entry point
Step 3: Feature-Based Structure (Large-Scale Apps)
src/
├── features/
│ ├── auth/
│ │ ├── components/
│ │ │ ├── LoginForm.tsx
│ │ │ └── SignupForm.tsx
│ │ ├── hooks/
│ │ │ └── useAuth.ts
│ │ ├── api/
│ │ │ └── authApi.ts
│ │ ├── store/
│ │ │ └── authSlice.ts
│ │ ├── types/
│ │ │ └── auth.types.ts
│ │ └── index.ts
│ │
│ ├── products/
│ │ ├── components/
│ │ ├── hooks/
│ │ ├── api/
│ │ └── types/
│ │
│ └── orders/
│
├── shared/ # Shared across features
│ ├── components/
│ ├── hooks/
│ ├── utils/
│ └── types/
│
└── core/ # App-wide
├── store/
├── router/
└── config/
Step 4: Naming Conventions
File Names:
Components: PascalCase.tsx
Hooks: camelCase.ts (useAuth.ts)
Utils: camelCase.ts (formatDate.ts)
Constants: UPPER_SNAKE_CASE.ts (API_ENDPOINTS.ts)
Types: camelCase.types.ts (user.types.ts)
Tests: *.test.ts, *.spec.ts
Folder Names:
kebab-case: user-profile/
camelCase: userProfile/ (optional: hooks/, utils/)
PascalCase: UserProfile/ (optional: components/)
✅ Consistency is key (entire team uses the same rules)
Variable/Function Names:
// Components: PascalCase
const UserProfile = () => {};
// Functions: camelCase
function getUserById() {}
// Constants: UPPER_SNAKE_CASE
const API_BASE_URL = 'https://api.example.com';
// Private: _prefix (optional)
class User {
private _id: string;
private _hashPassword() {}
}
// Booleans: is/has/can prefix
const isAuthenticated = true;
const hasPermission = false;
const canEdit = true;
Step 5: index.ts Barrel Files
components/ui/index.ts:
// ✅ Good example: Re-export named exports
export { Button } from './Button/Button';
export { Input } from './Input/Input';
export { Modal } from './Modal/Modal';
// Usage:
import { Button, Input } from '@/components/ui';
❌ Bad example:
// Re-export everything (impairs tree-shaking)
export * from './Button';
export * from './Input';
Output format
Project Template
my-app/
├── .github/
│ └── workflows/
├── public/
├── src/
│ ├── app/
│ ├── components/
│ ├── lib/
│ ├── types/
│ └── config/
├── tests/
├── docs/
├── scripts/
├── .env.example
├── .gitignore
├── .eslintrc.json
├── .prettierrc
├── tsconfig.json
├── package.json
└── README.md
Constraints
Required Rules (MUST)
- Consistency: Entire team uses the same rules
- Clear Folder Names: Roles must be explicit
- Max Depth: Recommend 5 levels or fewer
Prohibited (MUST NOT)
- Excessive Nesting: Avoid 7+ levels of folder depth
- Vague Names: Avoid utils2/, helpers/, misc/
- Circular Dependencies: Prohibit A → B → A references
Best practices
- Colocation: Keep related files close (component + styles + tests)
- Feature-Based: Modularize by feature
- Path Aliases: Simplify imports with
@/
tsconfig.json:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
"@/components/*": ["./src/components/*"],
"@/lib/*": ["./src/lib/*"]
}
}
}
Usage:
// ❌ Bad example
import { Button } from '../../../components/ui/Button';
// ✅ Good example
import { Button } from '@/components/ui';
References
Metadata
Version
- Current Version: 1.0.0
- Last Updated: 2025-01-01
- Compatible Platforms: Claude, ChatGPT, Gemini
Tags
#file-organization #project-structure #folder-structure #naming-conventions #utilities
Examples
Example 1: Basic usage
Example 2: Advanced usage
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
aiskillstore/marketplace
perigon-backend
Perigon ASP.NET Core + EF Core + Aspire conventions
aiskillstore/marketplace
perigon-agent
Pointers for Copilot/agents to apply Perigon conventions
aiskillstore/marketplace
perigon-angular
Angular 21+ standalone/Material/signal conventions for Perigon WebApp
aiskillstore/marketplace
fastapi-mastery
Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.
aiskillstore/marketplace
context7-efficient
Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.
aiskillstore/marketplace
browser-use
Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.
Didn't find tool you were looking for?