Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Get Started Free →

Modular Code Organization · vibeeval | DecimalAI

Modular Code

SkillScore87Maintained

modular-code

Modular Code Organization

codingby vibeeval

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Coding pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/modular-code/SKILL.md

decimalai skills pull modular-code --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/modular-code/SKILL.md https://app.decimal.ai/s/modular-code/SKILL.md

Raw file: /s/modular-code/SKILL.md ↗ · machine-readable summary at /s/modular-code.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

23 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 51d ago

Yes — +26% lift+10% tokens0% turns87% of whole cases pass with skill (20/23)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-11	✗→✓	▲ Improved	22%	0%
case-02	✗→✓	▲ Improved	39%	0%
case-03	✗→✓	▲ Improved	-21%	0%
case-05	✗→✓	▲ Improved	-9%	0%
case-13	✗→✓	▲ Improved	2%	0%

Showing 5 of 23 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/1/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

vibeeval / vibecosystem

skills/modular-code/SKILL.md

View on GitHub ↗

License MITImported 8/1/2026Version v2

Skill contents

SKILL.md

Modular Code Organization

Write modular Python code with files sized for maintainability and AI-assisted development.

File Size Guidelines

| Lines | Status | Action | |-------|--------|--------| | 150-500 | Optimal | Sweet spot for AI code editors and human comprehension | | 500-1000 | Large | Look for natural split points | | 1000-2000 | Too large | Refactor into focused modules | | 2000+ | Critical | Must split - causes tooling issues and cognitive overload |

When to Split

Split when ANY of these apply:

File exceeds 500 lines
Multiple unrelated concerns in same file
Scroll fatigue finding functions
Tests for the file are hard to organize
AI tools truncate or miss context

How to Split

Natural Split Points

By domain concept: auth.py → auth/login.py, auth/tokens.py, auth/permissions.py
By abstraction layer: Separate interface from implementation
By data type: Group operations on related data structures
By I/O boundary: Isolate database, API, file operations

Package Structure

feature/
├── __init__.py      # Keep minimal, just exports
├── core.py          # Main logic (under 500 lines)
├── models.py        # Data structures
├── handlers.py      # I/O and side effects
└── utils.py         # Pure helper functions

DO

Use meaningful module names (data_storage.py not utils2.py)
Keep __init__.py files minimal or empty
Group related functions together
Isolate pure functions from side effects
Use snake_case for module names

DON'T

Split files arbitrarily by line count alone
Create single-function modules
Over-modularize into "package hell"
Use dots or special characters in module names
Hide dependencies with "magic" imports

Refactoring Large Files

When splitting an existing large file:

Identify clusters: Find groups of related functions
Extract incrementally: Move one cluster at a time
Update imports: Fix all import statements
Run tests: Verify nothing broke after each move
Document: Update any references to old locations

Current Codebase Candidates

Files over 2000 lines that need attention:

Math compute modules (scipy, mpmath, numpy) - domain-specific, may be acceptable
patterns.py - consider splitting by pattern type
memory_backfill.py - consider splitting by operation type

Sources

Illustrative Want to see what modular-code would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/2/2026, 19:23 UTC · 23 cases

Lift

+26%

87% vs 61%

Agent turns

0%

1.0 vs 1.0

Tokens

+10%

2,311.48 vs 2,094.52

fail → pass · 7pass → pass · 13fail → fail · 2pass → fail · 1

Per-case results (23)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-11 To make our codebase clean, a developer proposed creating a separate directory and module for every single function in our project, resulting in 100 separate single-function files. Why should this strategy be rejected?	fail→pass	14,390	12,080	-16%	1	1	0%	2,270	2,780	+22%	0	0	—
case-01 We are designing a new payment processing feature in Python that handles database operations, external API integration, data models, and business rules. How should we layout the files and directories for this feature to keep it maintainable and easy for AI tools to work with?	fail→fail	15,719	15,879	+1%	1	1	0%	2,943	3,305	+12%	0	0	—
case-02 I'm reviewing our Python repository and noticed several files are becoming bloated. What guidelines should we use to decide if a file needs to be split, and what process should we follow when refactoring a large module?	fail→pass	13,706	16,307	+19%	1	1	0%	2,377	3,296	+39%	0	0	—
case-03 We are establishing Python repository linting rules. Our team lead suggests setting a strict target file size range of 50 to 100 lines per file so functions stay microscopic. What specific line count range is considered optimal for AI code editors and developer comprehension?	fail→pass	14,351	6,470	-55%	1	1	0%	2,399	1,901	-21%	0	0	—
case-04 Our Python data processing service has a legacy script that just reached 2,100 lines of code. The team wants to leave it as a single file because 'it works fine.' What critical classification applies to files over 2,000 lines, and what action is mandatory?	pass→pass	10,146	3,491	-66%	1	1	0%	1,728	1,426	-17%	0	0	—
case-05 We have a 450-line Python module that strictly handles user authentication logic with related helper methods. Should we immediately split this file into separate 100-line files purely to reduce line count?	fail→pass	10,776	4,376	-59%	1	1	0%	1,701	1,543	-9%	0	0	—
case-06 A developer on our team created a module named `user.management-v2.py` and another named `utils2.py`. How should these module files be renamed according to Python module naming standard practices?	pass→pass	9,235	6,655	-28%	1	1	0%	1,587	2,033	+28%	0	0	—
case-07 When setting up Python package directories, our new developer wants to put all business logic and function implementations directly inside `__init__.py` to avoid creating extra files. What role should `__init__.py` serve?	pass→pass	11,350	9,113	-20%	1	1	0%	1,985	2,445	+23%	0	0	—
case-08 In our data pipeline module, database queries and HTTP requests are mixed directly into pure mathematical calculation functions. What architectural separation principle should be applied here when splitting the module?	pass→pass	13,878	7,700	-45%	1	1	0%	2,156	2,227	+3%	0	0	—
case-09 Our legacy `auth.py` file has grown to 800 lines and contains user login flows, JWT token generation, and role-based permissions logic. How should this single file be split by domain concept?	pass→pass	14,559	8,363	-43%	1	1	0%	2,696	2,414	-10%	0	0	—
case-10 While working with AI code assistants on a 650-line Python file, developers report that the AI frequently misses function definitions and hallucinates parameters. Is this a valid indicator to split the file?	pass→pass	11,349	5,535	-51%	1	1	0%	1,977	1,700	-14%	0	0	—
case-12 To simplify import statements across our Python project, a teammate suggested writing custom import hooks that dynamically inject dependency modules into the global namespace without explicit `import` statements. Why is this practice discouraged?	pass→pass	12,603	11,742	-7%	1	1	0%	2,039	2,741	+34%	0	0	—
case-13 A core Python module in our system currently stands at 750 lines. It isn't causing critical tool crashes yet. What action status applies to files between 500 and 1,000 lines?	fail→pass	6,991	2,552	-63%	1	1	0%	1,186	1,205	+2%	0	0	—
case-14 An internal report identified three Python files ranging between 1,200 and 1,800 lines. What status applies to this line range and what specific action should be scheduled?	pass→pass	7,233	2,093	-71%	1	1	0%	1,298	1,134	-13%	0	0	—
case-15 We are starting to refactor a massive 1,500 line Python file. Before changing any code or imports, what are the first two steps in the refactoring process?	fail→pass	7,145	5,068	-29%	1	1	0%	1,166	1,671	+43%	0	0	—
case-16 We have extracted a cluster of functions from a large legacy module into a new module file. What remaining steps must be completed to finalize this refactoring step safely?	fail→fail	11,233	5,273	-53%	1	1	0%	1,789	1,667	-7%	0	0	—
case-17 In our payment system, high-level checkout orchestrations and raw low-level socket protocol parsing are written side-by-side in one 600-line file. What natural split point strategy should be used to reorganize this code?	pass→pass	13,202	7,008	-47%	1	1	0%	2,242	2,000	-11%	0	0	—
case-18 A 700-line module mixes file parsing, SQL query building, and local data structure transformations. How should natural split points be applied regarding I/O operations?	pass→pass	14,645	10,366	-29%	1	1	0%	2,599	2,648	+2%	0	0	—
case-19 Our QA team reports that writing unit tests for `order_processor.py` requires setting up 15 unrelated mocks across database, email, payment, and analytics services, making test suites unmanageable. Is this an indicator that the source file should be split?	fail→pass	12,922	9,600	-26%	1	1	0%	2,152	2,489	+16%	0	0	—
case-20 We need to standardise docstrings in our Python codebase. Should we use Google style or Sphinx reStructuredText docstrings for function parameters, and how should multiline summary lines be formatted?	pass→pass	14,727	10,875	-26%	1	1	0%	2,613	2,613	0%	0	0	—
case-21 We are designing custom exceptions for our Python library. Should custom exceptions inherit from `Exception` or `BaseException`, and how should exception hierarchies be structured for library error handling?	pass→pass	12,328	13,268	+8%	1	1	0%	2,317	3,286	+42%	0	0	—
case-22 In our pytest suite, we want to know whether database connection setup should use `scope='session'` or `scope='function'`, and how autouse fixtures affect test execution order.	pass→pass	13,530	14,315	+6%	1	1	0%	2,543	3,429	+35%	0	0	—
case-23 We have a slow Python loop processing millions of dictionary items. Should we use list comprehensions, `map()`, or vectorized NumPy operations to improve runtime execution speed?	pass→fail	14,345	14,782	+3%	1	1	0%	2,411	3,211	+33%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 23 cases were attempted. The headline lift of +26 percentage points is the difference between those two pass rates over the 23 comparable cases. 1 case got worse with the skill loaded, and it is included in that figure.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 60.9%
Pass rate with the skill: 87%
Cases attempted: 23
Cases counted toward lift: 23
Cases that regressed: 1
Skill version measured: v2
Run completed: 8/2/2026, 19:23 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-11

Prompt

To make our codebase clean, a developer proposed creating a separate directory and module for every single function in our project, resulting in 100 separate single-function files. Why should this strategy be rejected?

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run87

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+8% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 50 days ago

Model	Method	Date	Lift
gemini-3.6-flash	verified	7/29/2026	+20%

Other measured skills in the registry, with their headline benchmark lift.