CtrlK
BlogDocsLog inGet started
Tessl Logo

mcclowes/ai-aware-code-structure

Use when deciding how to organise code in an AI-assisted codebase — whether to split or merge a file, where to draw module boundaries, how big a file should get, whether to separate logic from rendering/styles/data, whether to use barrel/index re-export files, or where types and test files should live. Triggers on "should I split this file", "this file is getting too big", "separate concerns", "where should this code live", "are barrel files worth it", "central types file or co-locate", "colocate tests or a tests folder", reviewing or refactoring file/module organisation, structuring a new component or feature, or any architecture decision where part of the audience is an AI coding agent. Apply this whenever someone is choosing how to lay code out across files and an LLM will be reading or editing it, even if they only say "refactor this" or "clean up the structure" without mentioning AI.

83

1.54x
Quality

87%

Does it follow best practices?

Impact

82%

1.54x

Average score across 9 eval scenarios

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

AI-aware code structure

How to organise code across files when an AI coding agent is one of the readers. Splits, file size, and co-location decisions, recalibrated for the fact that agents are reluctant to read adjacent files.

Structure

  • SKILL.md - Main skill instructions: the three-reader framing, the "understood in isolation?" test, and the core heuristics
  • evals/evals.json - Test prompts for verifying the skill triggers and gives the right guidance

Usage

This skill is automatically discovered by Claude when relevant to the task.

Workspace
mcclowes
Visibility
Public
Created
Last updated
Publish Source
CLI
Badge
mcclowes/ai-aware-code-structure badge