skills.rest
alkofu
alkofuCOMMUNITY
Explore all skills by this author →
GitHub

file-organization

Guide file organization with one-responsibility-per-file and 3–5 files per feature.

3|Updated Mar 20, 2026
Search Tags:#organize#refactor#best-practices#software-engineering#code-structure#modular-design#file-organization
One-click install
npx skills add https://github.com/alkofu/ai-tpk --skill file-organization-alkofu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: file-organization
Source: https://github.com/alkofu/ai-tpk/tree/main/claude/skills/file-organization
Command: npx skills add https://github.com/alkofu/ai-tpk --skill file-organization-alkofu

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Provides guidance for sensible file and module organization to prevent both overly large, tangled files and excessive fragmentation, leading to cleaner, more maintainable codebases.

Core Features & Use Cases

  • One responsibility per file to keep concerns isolated and readable.
  • Favor a compact set of cohesive files (typically 3–5) per feature to preserve context.
  • Create a separate file only when the code has a distinct responsibility, will be reused, or is independently testable; otherwise, keep related logic together.
  • Explain why each file exists and why further splitting isn't needed after changes to prevent over-engineering.

Quick Start

Sketch the proposed file structure for a new feature before adding or refactoring code.

Frequently Asked Questions about file-organization

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is the best way to organize code files to prevent tangled modules?▼

You should refactor code into a separate file only when the code has a distinct responsibility, will be reused, or is independently testable. Otherwise, keep related logic together within the same file to avoid over-engineering and excessive fragmentation.

How do I split files in a feature without causing excessive fragmentation?▼

You should refactor code into a separate file only when the code has a distinct responsibility, will be reused, or is independently testable. Otherwise, keep related logic together within the same file to avoid over-engineering and excessive fragmentation.

When do I need to create a separate file for my code?▼

To structure a new feature, sketch the proposed file structure and module boundaries before adding or refactoring code. Aim for 3–5 files per feature, ensuring one responsibility per file to improve readability and maintainability.

How do I structure code files for a new feature before refactoring?▼

To structure a new feature, sketch the proposed file structure and module boundaries before adding or refactoring code. Aim for 3–5 files per feature, ensuring one responsibility per file to improve readability and maintainability.

Why does my codebase need explicit justification for file splitting?▼

Your codebase needs explicit justification for file splitting to explain why each file exists and why further splitting is not needed. Documenting these decisions prevents over-engineering and maintains cohesive, readable module boundaries.

Related Skills

Explore More Software Engineering Skills→
j5ik2oj5ik2o
81

refactoring-packages

Analyze package structures to detect cycles and generate migration plans.

Community
Advanced
thechandanbhagatthechandanbhagat
8

test

Generate pytest and Jest unit tests, integration tests, and mock data.

Community
Basic
Destynova2Destynova2
5

cli-audit-tangle

Analyze codebases for god functions, circular dependencies, dead code, and module boundaries.

Community
Advanced
012e012e
1

nx-generate

Generate code scaffolding and migrations using Nx generators in a monorepo.

Community
Advanced