project-structure · tartinerlabs — Claude Code skill: what it does, how to install
Audits directory layouts, flags file organisation anti-patterns, and safely moves code using git mv with automated import updates.
npx skills add tartinerlabs/skills --skill project-structure -a claude-codeWhat project-structure does
The skill evaluates project layouts and defaults to read-only auditing. It groups findings into HIGH, MEDIUM, and LOW tiers alongside violation counts. For UI-heavy projects like React or Next.js, it prioritises feature-based grouping; for backends built on FastAPI, Express, Django, or Go, it suggests layer-based layouts. Monorepos get a hybrid structure. Specific framework conventions activate solely when Next.js or Expo is detected.
Files remain untouched until you explicitly instruct a fix. During reorganisations, the skill runs mkdir -p before git mv so Git does not abort on missing directories, updates dependent import statements, and confirms no unresolved imports remain. It advises keeping code next to its sole caller and promoting it to shared folders only when a second caller emerges.
What it helps with
- audit repository file organisation and detect directory anti-patterns
- determine the right folder placement for new components or services
- relocate files with
git mvwhile automatically rewriting import paths - apply feature-based or layer-based grouping to an existing codebase
Example prompts for the agent
- Audit our repository layout and list any structure anti-patterns.
- Where should I place the new payment webhook handler?
- Apply the suggested folder structure fixes and rewrite imports.
How to install project-structure
1Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill project-structure -a claude-code2Manually: put the files in place
~/.claude/skills/project-structure/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/project-structure/
1Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill project-structure -a codex2Manually: put the files in place
.agents/skills/project-structure/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill project-structure -a cursor2Manually: put the files in place
.cursor/skills/project-structure/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install tartinerlabs/skills project-structure2Manually: put the files in place
.github/skills/project-structure/SKILL.md1Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill project-structure -a gemini-cli2Platform CLI
gemini skills install https://github.com/tartinerlabs/skills --path plugins/quality/skills/project-structureManually: put the files in place
.devin/skills/project-structure/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add tartinerlabs/skills --skill project-structure -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about project-structure
How to install project-structure in Claude Code?
Run npx skills add tartinerlabs/skills --skill project-structure -a claude-code in your terminal.
What does project-structure do?
It scans repository directories against grouping and colocation rules, generates an audit report, and applies file relocations upon request.
Does project-structure move files automatically without asking?
No. The skill defaults to reporting findings; it executes git mv and rewrites imports only when explicitly asked to reorganize or fix issues.
Source text
SKILL.md · MIT
--- name: project-structure description: Use when deciding where code should live, organising files, or auditing project structure. Checks colocation, grouping, and directory anti-patterns. license: MIT allowed-tools: Read Glob Grep Edit Bash(git:*) Bash(mkdir:*) model: haiku effort: medium compatibility: Any language project; framework-specific structure rules apply only when that framework is detected metadata: short-description: Project structure and file organisation. --- You are a project structure expert. Audit and report by default; move files only when the user asks you to fix, reorganise, or apply something. When the ask is unclear, report first and offer to apply the fixes. ## Rules Overview | Rule | Impact | File | |------|--------|------| | Colocation | HIGH | `rules/colocation.md` | | Anti-patterns | HIGH | `rules/anti-patterns.md` | | Feature-based grouping | MEDIUM | `rules/feature-based.md` | | Layer-based grouping | MEDIUM | `rules/layer-based.md` | | Framework structure | MEDIUM | `rules/framework-structure.md` (only when a supported framework is detected) | ## Workflow ### Step 1: Detect Project Type Scan for project indicators to determine the appropriate organisation approach: - Feature-heavy app (SPA, Next.js/React, or any UI-driven codebase) → feature-based - Service / API (Express, Fastify, Hono, Django, FastAPI, Go, Rails, …) → layer-based - Monorepo (`apps/` + `packages/`, or workspace manifests) → hybrid - Existing structure → respect and extend current patterns Load `rules/framework-structure.md` **only when a framework it covers is detected** (currently Next.js / Expo); otherwise the language-neutral colocation and grouping rules apply on their own. ### Step 2: Audit Check the existing structure against all rules. Report each finding as `path` — what is wrong → the fix, grouped under `### HIGH` / `### MEDIUM` / `### LOW`, and close with a per-rule violation count. ### Step 3: Recommend Based on project type and existing patterns, recommend where new code should live. Default to placing new code next to its only consumer; promote it to a shared location when a second consumer appears. Extend the structure the project already has rather than introducing a second one alongside it. ### Step 4: Fix Apply fixes for each violation: 1. Create the destination directory first if it does not exist (`mkdir -p <dest>`) — `git mv` fails when the target directory is missing 2. Move files to their correct location with `git mv` 3. Update all import paths in dependent files 4. Verify no broken imports remain after moves
© tartinerlabs · MIT · tartinerlabs/skills
Similar skills
All skills for Code review and refactoring →project-structure by other authors comes first.
