跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

improve-file-structure

Assess project file organization and prepare a behavior-preserving migration plan for /implement when reorganization is justified.

svyatov · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add svyatov/supermatt --skill improve-file-structure

技能说明


name: improve-file-structure description: "Assess project file organization and prepare a behavior-preserving migration plan for /implement when reorganization is justified." argument-hint: "[path or pain point]" disable-model-invocation: true license: MIT

Improve File Structure

Find where file placement makes a project hard to navigate or change. Design the smallest useful reorganization, grounded in the project's language, framework, and existing conventions. End with a plan for /implement; this skill changes no project files. Present the plan in the conversation unless the user requests a saved artifact.

File placement is the scope. Moves, descriptive path names, and the import or configuration updates they require belong here. Changes to responsibilities, interfaces, or dependency direction belong in /improve-architecture in Claude linked installs or Cursor, /supermatt:improve-architecture from the Claude plugin, $improve-architecture in Codex, or /skill:improve-architecture in OMP. Code-level cleanup belongs in /refactor, /supermatt:refactor, $refactor, or /skill:refactor, respectively. Identify those needs without adding them to a relocation plan.

Principles

  • Friction before folders. A crowded directory is a clue, not a finding. Cite the navigation or maintenance problem and the files that cause it. A small flat project can be healthy; file-count limits and aesthetic symmetry do not justify moves.
  • Locality with ownership. Group files that implement the same concept and are understood or changed together. Imports and change history support that judgment; neither proves it alone. Prefer feature/domain grouping when it solves the observed problem, and keep an established layout when it works.
  • Paths can be contracts. Runtime discovery, package visibility, public imports, and published artifacts can depend on a path. Preserve those contracts by default; folder moves do not grant permission to change them.
  • Every directory earns its place. Give it a clear responsibility and a rule for what belongs there. Keep feature-specific helpers, types, tests, and assets near their owner where tooling permits. Create shared areas only for demonstrated shared use, with a specific purpose rather than a new catch-all.

Process

Step 1: Map the area

Use the user's path or pain point as the scope. Otherwise inventory the repository at a high level and inspect likely trouble spots first. Read project instructions, glossary terms, and relevant architecture decisions before choosing a convention.

Identify languages, frameworks, applications versus libraries, workspace/package boundaries, entry points, and the commands used to build, test, and package them. Separate authored source, tests, resources, tooling, generated output, and vendored code. Generated and vendored files are not relocation candidates; inspect their producers when paths matter.

Use CodeGraph first when the repository is indexed, or existing symbol-aware tools when available. Otherwise use file search and read the source. Map each directory's role, related file clusters, dependencies crossing the proposed scope, and path-based discovery. Inspect available git history for files that change together, discounting bulk moves and formatting commits. Mark text-search or dynamic-reference gaps; do not claim an exhaustive dependency graph from filename matches.

Read only the language references used in this area:

AreaReference
TypeScript/JavaScript apps, libraries, or workspacesTypeScript
Go packages and commandsGo
Python packages and applicationsPython
Ruby gems and applications, including RailsRuby

These references distinguish source-backed constraints from this skill's recommendations. For another language or an uncertain framework/version rule, consult its primary documentation. Try the site's root llms.txt or llms-full.txt first, then the relevant HTML page. Record the source and its scope; do not present one framework's preferences as language requirements. No general web research pass is needed when the supplied guidance resolves the question.

Done when: the scoped inventory accounts for the directories reviewed, their roles and constraints, and any exclusions or unknowns that limit the assessment.

Step 2: Assess

Look for mixed concerns in one folder, one feature scattered across unrelated folders, ambiguous catch-all locations, redundant nesting, and inconsistent placement that makes the next file's home unclear. Read the implicated files before reporting a finding.

For each finding, cite concrete paths, explain a real navigation/change task made harder, and explain how a placement change would help. Rank benefit against churn and compatibility risk. A cycle that needs interface redesign is an architecture finding; moving it into prettier folders does not fix it.

VerdictAction
HealthyExplain why the current layout works and stop.
LocalizedPresent the affected clusters and recommend the smallest useful reorganization.
SystemicRank independent candidates and propose an incremental starting area.

Keep unresolved inspection gaps visible alongside the verdict. For a recently reorganized area, require new evidence before proposing another layout. If the same problem remains, explain why the previous move failed. Honor a specific user request on healthy code, but distinguish that preference from a defect. Assess the existing layout separately from a requested move: a move that violates a path contract does not make the current layout defective. Report the conflict and keep that candidate pending.

Done when: every candidate has evidence, a placement-level remedy, and a benefit that justifies the migration.

Step 3: Choose and design

Present candidates with stable IDs, a

阅读完整来源 ↗