Organize project files and folders for maintainability and scalability. Use when structuring new projects, refactoring folder structure, or establishing conventions. Handles project structure, naming conventions, and file organization best practices.
77
66%
Does it follow best practices?
Impact
98%
1.27xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agent-skills/file-organization/SKILL.mdQuality
Discovery
67%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 competent description that successfully includes both 'what' and 'when' clauses, meeting the completeness requirement. However, it lacks specific concrete actions (what exactly does 'organize' mean?) and could benefit from more natural trigger terms that users would actually say when needing this skill.
Suggestions
Add more specific concrete actions like 'create directory hierarchies', 'suggest folder layouts for different project types', 'rename files to follow conventions', or 'generate .gitkeep files'
Expand trigger terms to include natural phrases like 'directory layout', 'repo structure', 'where should I put this file', 'organize my codebase', 'monorepo structure'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (project files/folders) and some actions (structuring, refactoring, establishing conventions), but lacks specific concrete actions like 'create directory hierarchies', 'rename files according to patterns', or 'generate folder templates'. | 2 / 3 |
Completeness | Clearly answers both what ('Organize project files and folders for maintainability and scalability') and when ('Use when structuring new projects, refactoring folder structure, or establishing conventions') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes relevant terms like 'project structure', 'folder structure', 'naming conventions', 'file organization', but misses common variations users might say like 'directory layout', 'repo structure', 'where should I put', 'organize my codebase', or 'folder hierarchy'. | 2 / 3 |
Distinctiveness Conflict Risk | Reasonably specific to project organization, but could overlap with general code refactoring skills or project scaffolding tools. The focus on 'file organization' and 'folder structure' provides some distinction but isn't highly unique. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides comprehensive, actionable project structure templates with good naming convention examples and concrete code snippets. However, it conflates alternative project structures as 'steps' in a workflow, includes unnecessary metadata/placeholder sections, and could benefit from better progressive disclosure by splitting framework-specific structures into separate reference files.
Suggestions
Rename 'Step 1/2/3' to 'Option A/B/C' or separate sections since these are alternative structures, not sequential steps
Remove empty example placeholders ('<!-- Add example content here -->') and unnecessary metadata section to improve conciseness
Add a validation checklist or verification step (e.g., 'Run eslint to verify import paths resolve correctly') to improve workflow clarity
Consider splitting framework-specific structures (React, Node, Feature-based) into separate reference files with a concise overview in the main skill
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill provides useful structure templates but includes some unnecessary elements like metadata sections, empty example placeholders, and references that don't add actionable value. The core content is reasonably efficient but could be tightened. | 2 / 3 |
Actionability | Provides concrete, copy-paste ready folder structures, specific naming conventions with examples, and executable TypeScript/JSON configurations. The barrel file examples and tsconfig.json are immediately usable. | 3 / 3 |
Workflow Clarity | Steps are labeled but represent different project types rather than a sequential workflow. There's no validation checkpoint for verifying structure correctness, and the 'Steps' framing is misleading since these are alternative structures, not sequential actions. | 2 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, but everything is inline in one large file. The external references at the end are appropriate, but the skill could benefit from splitting detailed structures (React vs Node vs Feature-based) into separate files with a concise overview. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
Total | 10 / 11 Passed | |
c033769
Table of Contents
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.