playbooks

home / skills / oimiragieo / agent-studio / file-organization

file-organization skill

/.claude/skills/_archive/dead/file-organization

This skill helps organize TypeScript projects by modularizing code, separating concerns, and using index files to simplify imports.

npx playbooks add skill oimiragieo/agent-studio --skill file-organization

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.5 KB
---
name: file-organization
description: Defines the file organization structure for TypeScript projects, emphasizing modularity and separation of concerns.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: '**/*.ts'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# File Organization Skill

<identity>
You are a coding standards expert specializing in file organization.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- Group related functionality into modules
- Use index files to simplify imports
- Separate concerns: keep business logic, UI components, and utilities in different directories
  </instructions>

<examples>
Example usage:
```
User: "Review this code for file organization compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill defines a practical file organization structure for TypeScript projects, emphasizing modularity and clear separation of concerns. It provides concrete guidelines to group related code, simplify imports, and make projects easier to navigate, maintain, and scale. It is written for teams and solo developers aiming for consistent, predictable repo layouts.

How this skill works

The skill inspects project directories and TypeScript files to verify grouping of related functionality, presence and use of index files, and separation between business logic, UI components, and utilities. It flags anti-patterns such as mixed responsibilities in single folders, deep import paths, and missing barrel exports, then suggests refactors and concrete folder layouts. It can also generate example directory templates and recommended index exports.

When to use it

  • Starting a new TypeScript project or repo
  • Refactoring an existing codebase to improve maintainability
  • Onboarding teams to a shared project layout standard
  • Preparing a project for scaling, modularization, or package extraction

Best practices

  • Group related code into feature or domain modules rather than by file type alone (e.g., features/<feature>/*).
  • Use index.ts barrel files to expose public APIs for a folder and simplify imports across the codebase.
  • Keep concerns separate: business logic, UI components, hooks, and utilities should live in different directories or clear subfolders.
  • Prefer flat, predictable folder structures and avoid excessive nesting; cap nesting depth where practical.
  • Name files and folders consistently and use clear boundaries between public API and internal implementation.

Example use cases

  • Review a monolithic repo and recommend reorganizing into feature modules with shared utils.
  • Convert scattered utility functions into a centralized utilities package with clear exports.
  • Generate a starter TypeScript project layout with src/, features/, components/, hooks/, and lib/ directories and sample index.ts files.
  • Audit UI components to ensure they contain presentation only and move data logic into services or hooks.

FAQ

Should I always use index.ts barrels?

Use barrel files to simplify imports and expose stable public APIs, but avoid barrels that re-export large trees unnecessarily as they can hide dependencies and increase bundle size if not tree-shakeable.

How granular should feature folders be?

Balance granularity with usability: group cohesive functionality into a single feature folder, but split when a feature grows complex or needs to be published separately as its own package.