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

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a high-quality architectural guidance skill with excellent actionability — the decision test, heuristics, and quick-reference table give Claude precise, concrete guidance for code organization decisions. The main weakness is moderate verbosity: the philosophical framing and some explanatory passages could be trimmed since Claude already understands concepts like context windows and cross-file dependencies. The content would also benefit from splitting the detailed placement calls into separate files for better progressive disclosure.

Suggestions

Trim the 'core shift' and 'limitation to design around' sections to ~2-3 sentences each — Claude already understands context windows and cross-file navigation limitations; state the conclusion directly.

Consider extracting the three detailed placement calls (barrel files, types, tests) into a separate reference file, keeping only one-line summaries in the main SKILL.md with a link.

DimensionReasoningScore

Conciseness

The skill is well-written and mostly efficient, but it includes some philosophical framing and motivational context ('a third reader', 'the core shift') that Claude doesn't need. The 'When this applies' section restates the description. Several paragraphs could be tightened — e.g., the barrel files section explains tree-shaking and circular import costs that Claude already knows. However, the content is not egregiously verbose and most paragraphs carry useful signal.

2 / 3

Actionability

The skill provides highly concrete, specific guidance: a clear decision test ('can this concern be understood in isolation?'), specific line-count thresholds (~300 lines), named heuristics with rationale, three specific placement calls (barrel files, types, tests) with direct recommendations, and a quick-reference table. While there's no executable code, this is an instruction/architecture skill where code examples aren't the right medium — the guidance is precise and actionable.

3 / 3

Workflow Clarity

The 'Applying this skill' section provides clear workflows for three common scenarios (deciding to split, reviewing organization, structuring something new). The decision test is a single unambiguous question. The quick reference table serves as a decision checklist. For an architecture/decision skill (not a destructive/batch operation), this level of workflow clarity is excellent — no validation gaps exist for the type of task being described.

3 / 3

Progressive Disclosure

The content is well-structured with clear headers and a logical flow from principles to specifics to quick reference. However, at ~200+ lines of prose, some sections (particularly the three placement calls) could be split into separate reference files to keep the main SKILL.md leaner. There are no bundle files or external references, so everything is inline. The organization is good but the skill would benefit from splitting detailed guidance into referenced files.

2 / 3

Total

10

/

12

Passed

Description

92%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a strong description with excellent specificity and trigger term coverage. It clearly communicates both what the skill does and when to use it, with highly natural user phrases. The main weakness is the broad catch-all at the end which could cause conflicts with general refactoring or architecture skills, though the AI-assisted codebase niche does help differentiate it somewhat.

DimensionReasoningScore

Specificity

Lists multiple specific concrete actions: splitting/merging files, drawing module boundaries, file size decisions, separating logic from rendering/styles/data, barrel/index re-export files, type file placement, test file placement. Very comprehensive enumeration of capabilities.

3 / 3

Completeness

Clearly answers both 'what' (organising code in AI-assisted codebases across multiple specific dimensions) and 'when' with an explicit 'Use when' clause at the start plus extensive trigger phrases and a broad catch-all at the end for implicit triggers like 'refactor this'.

3 / 3

Trigger Term Quality

Excellent coverage of natural user phrases: 'should I split this file', 'this file is getting too big', 'separate concerns', 'where should this code live', 'are barrel files worth it', 'colocate tests or a tests folder', 'refactor this', 'clean up the structure'. These are highly natural phrases users would actually say.

3 / 3

Distinctiveness Conflict Risk

While the AI-assisted codebase angle is distinctive, the broad catch-all of 'refactor this' or 'clean up the structure' could easily overlap with general refactoring or code quality skills. The description tries to claim any structural refactoring where an LLM is involved, which is quite broad and could conflict with other architecture or refactoring skills.

2 / 3

Total

11

/

12

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Reviewed

Table of Contents