How do I install the Code Organization skill?

Run npx skillmds@latest add usenotra/code-organization in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Code Organization safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Code Organization?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Code Organization free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Code Organization?

usenotra (@usenotra) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Code Organization by usenotra — Agent Skill

Name: Code Organization
Author: usenotra

Code Organization

Repo file-organization convention for TypeScript projects. ALWAYS use this when creating new files or deciding where code goes — types, schemas, validation, utility/helper functions, constants, enums, and config literals each belong in their own dedicated folder, not inline next to feature code or dumped in one grab-bag file. Use whenever you add a type/interface, a validation schema, a util/helper, a constant, or are asked where something should live, how to structure the repo, or to organize/refactor file layout.

usenotra 7d14441 3.5 KB Updated Sep 17, 2026

File contents

code-organization

Where each kind of code goes. Apply this every time you create a file or add a type, schema, helper, or constant. Don't inline them next to feature code and don't pile unrelated things into one file.

Layout

Each category gets its own dedicated folder. Files inside a folder are grouped by domain (e.g. user, post), not by individual symbol.

src/
  types/        type & interface definitions        types/user.ts
  schemas/      validation schemas (zod, yup, etc.) schemas/user.ts
  utils/        helper / utility functions          utils/format.ts
  constants/    constant values, enums, config      constants/routes.ts

Rules

One folder per category — types/, schemas/, utils/, constants/. A new type goes in types/, never inline in the file that uses it or alongside a component.
Group files by domain inside a folder. All user-related types live in types/user.ts; all user-related constants in constants/user.ts. Split a file once it covers clearly separate domains — not per symbol.
Functions get their own file. A reusable helper lives in utils/ in a file named for what it does (utils/format.ts, utils/slugify.ts). Keep one focused concern per file; don't accumulate a utils/index.ts junk drawer.
No barrel files. Do not add index.ts re-export barrels. Import directly from the specific file:
```
import { formatDate } from "@/utils/format";   // ✓
import { formatDate } from "@/utils";           // ✗ no barrel
```
This keeps imports explicit and avoids circular-import and tree-shaking surprises.
Types vs schemas are separate concerns. types/ holds pure TypeScript type/interface declarations. schemas/ holds runtime validation schemas. If a type is derived from a schema, infer it in types/ and import the schema — keep the validator in schemas/.

Where does it go?

You're adding…	Folder	Example file
`type` / `interface`	`types/`	`types/user.ts`
validation / parse schema	`schemas/`	`schemas/user.ts`
pure helper function	`utils/`	`utils/format.ts`
constant, enum, config literal	`constants/`	`constants/routes.ts`
React component, route, feature code	feature dir	`user/profile.tsx`

Gotchas

A one-off type still goes in types/. "It's only used here" is not a reason to inline it — consistency is the point. The next person looks in types/ first.
Don't create a barrel to shorten imports. Rule 4 is deliberate; longer import paths are the trade-off, and they're worth it.
utils/ is not a dumping ground. If a helper is specific to one feature and never reused, it can live with that feature — utils/ is for genuinely shared helpers.
Match the existing folder names in the repo if it already has types/ / lib/ / helpers/. Follow what's there rather than introducing a parallel set of folders.

---name: code-organizationdescription: Repo file-organization convention for TypeScript projects. ALWAYS use this when creating new files or deciding where code goes — types, schemas, validation, utility/helper functions, constants, enums, and config literals each belong in their own dedicated folder, not inline next to feature code or dumped in one grab-bag file. Use whenever you add a type/interface, a validation schema, a util/helper, a constant, or are asked where something should live, how to structure the repo, or to organize/refactor file layout.---# code-organizationWhere each kind of code goes. Apply this **every time** you create a file oradd a type, schema, helper, or constant. Don't inline them next to featurecode and don't pile unrelated things into one file.## LayoutEach category gets its **own dedicated folder**. Files inside a folder aregrouped by domain (e.g. `user`, `post`), not by individual symbol.```src/ types/ type & interface definitions types/user.ts schemas/ validation schemas (zod, yup, etc.) schemas/user.ts utils/ helper / utility functions utils/format.ts constants/ constant values, enums, config constants/routes.ts```## Rules1. **One folder per category** — `types/`, `schemas/`, `utils/`, `constants/`. A new type goes in `types/`, never inline in the file that uses it or alongside a component.2. **Group files by domain inside a folder.** All user-related types live in `types/user.ts`; all user-related constants in `constants/user.ts`. Split a file once it covers clearly separate domains — not per symbol.3. **Functions get their own file.** A reusable helper lives in `utils/` in a file named for what it does (`utils/format.ts`, `utils/slugify.ts`). Keep one focused concern per file; don't accumulate a `utils/index.ts` junk drawer.4. **No barrel files.** Do **not** add `index.ts` re-export barrels. Import directly from the specific file: ```ts import { formatDate } from "@/utils/format"; // ✓ import { formatDate } from "@/utils"; // ✗ no barrel ``` This keeps imports explicit and avoids circular-import and tree-shaking surprises.5. **Types vs schemas are separate concerns.** `types/` holds pure TypeScript type/interface declarations. `schemas/` holds runtime validation schemas. If a type is derived from a schema, infer it in `types/` and import the schema — keep the validator in `schemas/`.## Where does it go?| You're adding… | Folder | Example file ||---|---|---|| `type` / `interface` | `types/` | `types/user.ts` || validation / parse schema | `schemas/` | `schemas/user.ts` || pure helper function | `utils/` | `utils/format.ts` || constant, enum, config literal | `constants/` | `constants/routes.ts` || React component, route, feature code | feature dir | `user/profile.tsx` |## Gotchas- **A one-off type still goes in `types/`.** "It's only used here" is not a reason to inline it — consistency is the point. The next person looks in `types/` first.- **Don't create a barrel to shorten imports.** Rule 4 is deliberate; longer import paths are the trade-off, and they're worth it.- **`utils/` is not a dumping ground.** If a helper is specific to one feature and never reused, it can live with that feature — `utils/` is for genuinely shared helpers.- **Match the existing folder names in the repo** if it already has `types/` / `lib/` / `helpers/`. Follow what's there rather than introducing a parallel set of folders.

Frequently asked questions