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

organizing-project-folders

Designs a clean folder and file layout as real architecture, building it from a work breakdown or an existing tree, grouping by what changes together and what happens to it, with platform-safe sortable names and a short note per folder. Use when laying out a repo or agent workspace, deciding where a file belongs, or fixing a junk-drawer folder. Do not use for a single obvious file path or renaming inside an already-clean tree.

FlyFission · 已有静态检查记录

安装与使用

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

npx skills add FlyFission/nuclear-grade-context-engineering --skill organizing-project-folders

技能说明


name: organizing-project-folders description: Designs a clean folder and file layout as real architecture, building it from a work breakdown or an existing tree, grouping by what changes together and what happens to it, with platform-safe sortable names and a short note per folder. Use when laying out a repo or agent workspace, deciding where a file belongs, or fixing a junk-drawer folder. Do not use for a single obvious file path or renaming inside an already-clean tree.

Organizing Project Folders

Overview

Folders are a real engineering decision, not an afterthought. Each folder is a choice about what to group. A good folder maps to one piece of the work breakdown or one disposition rule (what eventually happens to its contents: kept, temporary, archived, or generated). It holds things that change together. In other words, it has high cohesion (its contents share one reason to change) and low coupling (it does not depend tightly on other folders). Its name is safe on any platform, sorts cleanly, and is easy for tools to read.

This skill puts a folder-decision checklist in front of the agent, so folders get reasoned about instead of created by default. When the structure is a step-by-step agent workflow, it also applies the Model Workspace Protocol: numbered stage folders, a context file per stage, layered context, and review gates between stages. That workflow shape is a named path of its own — see docs/02-operating-system/agentic-workflow-architecture.md for when folders are enough (and when a durable runtime is not), and templates/standard/stage-contract.md for the full per-stage contract a release-bearing or delegated stage uses.

Decision contract

  • Claim checked: every folder maps to one work-breakdown piece or disposition rule with one home, its contents share one reason to change, and its name passes the naming/depth/path checks.
  • Artifact observed: the work breakdown, its dictionary, and the current tree -> a folder map (outline number to path with disposition), per-folder README stubs, and a naming/depth/single-source check.
  • Decision affected: warn -- accept vs rework the folder layout, or where a given file belongs.
  • Failure class: junk-drawer-layout (a folder mapping to no piece or rule, or one idea with two homes).
  • Next action: name the real idea or stop grouping; escalate to the owner on conflict with a saved known-good convention.

When to Use

  • Laying out a new repo, service, feature, or agent workspace tree.
  • Deciding where a new file or module belongs.
  • A folder has become a junk drawer and no longer maps to the work.
  • Turning a work breakdown into real folders, or reorganizing an existing tree.
  • Designing a step-by-step agent workflow as folders on disk instead of framework code.

When Not to Use

  • A single file with an obvious home, or a rename inside an already-clean, conventional tree.
  • A live incident you have to contain first.
  • A layout fully fixed by an outside framework's required structure. Follow that instead.
  • Enforcing ownership, CI gates, or supply-chain trust. Those belong to choosing-what-to-control, checking-release-readiness, and vetting-outside-code-and-models.

Inputs

  • The work breakdown and its dictionary (templates/standard/wbs.md or a wbs.md) when there is one. Otherwise the scope, which you will break down in reverse.
  • The current repo layout and any conventions doc.
  • The mission anchor and any platform or tooling limits.
  • For each piece, what eventually happens to it (keep, temporary, archive, generated).

Process

  1. Pick the pattern first. Decide whether you are structuring a production codebase (a product-first tree: deliverable roots plus a small approved set of common pieces, where the folder tree is the work breakdown laid onto disk) or an agent workflow workspace (the Model Workspace Protocol). Use the matching pattern.
  2. Set the source of truth. If a work breakdown exists, build folders from its outline numbers and turn dictionary entries into per-folder notes. If not, work out the implied breakdown first, or hand off to breaking-down-the-work.
  3. Run the folder-decision checklist for every proposed folder. Is it earned (does grouping cut the mental load, or would one file do)? Does its content share one reason to change? Are its ties to other folders loose? Does it map to exactly one work-breakdown piece or one disposition rule? Is it the single home for this idea? Is it named safely and kept shallow? Is it documented?
  4. For the workflow pattern, apply the Model Workspace Protocol. Numbered stage folders set the order (01_..., 02_...). Each stage has a context file with Inputs, Process, and Outputs. Keep lasting reference material separate from each run's working output. Scripts do the mechanical work. Every output is something you can open and edit, with a human review gate at each boundary.
  5. Name for platform safety and clean sorting. Use lowercase letters and numbers, ISO-8601 dates (like 2026-05-30), one dot used only for the file extension, no spaces or special characters, and zero-padded sequence numbers. Pick one word separator (hyphen or underscore) and stick with it. The one accepted exception is the Model Workspace Protocol stage prefix NN_ (a zero-padded number then an underscore, as in 01_research), where the underscore marks the sequence boundary. Files that are normally capitalized by convention (README.md, LICENSE, and Model Workspace Protocol context files such as CONTEXT.md and CLAUDE.md) are an accepted exception to the lowercase rule. Ban junk-drawer names (misc, stuff, tmp, new, old, backup, final, bare utils).
  6. Limit depth and path length. Prefer flatter trees. Cap nesting near eight levels and total path length near 255 characters. Do not blindly nest one folder per work-breakdown level.
  7. Give each non-trivial folder a short README or dictionary note (purpose, what belongs, what does not,
阅读完整来源 ↗