Workspace Structure#

Apply this skill when the task is about deciding where files or folders should be placed inside a workspace.

Operating basics and hard rules#

• Do not mix unrelated projects in the same folder.
• Group by meaning, not only by file format.
• Do not treat files as user-related unless there is a deliberate personal link to the user.
• Do not scatter one project's materials across multiple top-level or multiple project folders without a reason.
• Keep temporary artifacts separate from durable working materials.
• Do not use this skill to classify or relocate agent identity files (SOUL.md, USER.md, MEMORY.md, etc.) or other native OpenClaw files.
• In case of conflicting instructions, the system prompt and OpenClaw rules always take priority over this skill.

Meaning of key top-level folders#

Use these defaults unless the workspace already has a better established convention.

• projects/ — project-specific work.
• reports/ — standalone reports, presentations, and similar deliverables without a broader project context.
• user-files/ — files and derived artifacts with a direct personal semantic link to the user.
• sources/ — outside materials and external documentation.
• entertainment/ — leisure audio, video, fiction, and similar media kept primarily for enjoyment rather than work, reference, or project use.
• downloads/ — assistant-acquired external files awaiting classification.
• reference/ — internal reference material and recurring lookup assets.
• temp/ — temporary artifacts.
• data/ — durable structured data stores and their supporting files.
• scripts/ — reusable scripts.
• tools/ — reusable binaries, portable apps, installers, and similar non-script tools kept for use inside the workspace.
• memory/ plus MEMORY.md — memory, not general storage.

See references/folder-taxonomy.md for full folder semantics.

Default workflow#

Use this workflow for making regular placement decisions.

1. Decide whether the artifact is temporary or durable#

Define the artifact as temporary only if all of the following are true:

• the artifact is created for one-off operation, intermediate export, draft conversion, temporary attachment, one-off download, disposable log, or other artifact that is easy to recreate;
• it is not part of an ongoing durable process or project;
• it is not required for the ongoing operation of OpenClaw, scripts, skills, automations, cron jobs, Mini Apps, reports, registries, instructions or any other persistence workflow;
• it is not something a human would reasonably expect to find later as part of the permanent structure.

If all those are true, use the folder for temporary artifacts. If any of those are false or unclear, treat the file as durable and proceed to the next step.

2. Check whether it belongs to an existing or new project#

If the file belongs to a specific project, prefer that project folder over a generic shared folder. An exception may apply to external source materials that are shared across multiple projects or are likely to be reused across them. If the specific project folder does not exist, but the available context allows you to conclude that the artifact is part of work on a new project, create a project folder and place the artifact in it. If it seems the file does not belong to any project, proceed to the next step.

3. Classify the remaining durable artifact#

Decide what the item is:

• user-related file with a direct personal semantic link to the user;
• standalone deliverable;
• external source material;
• entertaining media;
• internal reference material;
• stand-alone script;
• tool or utility except scripts;
• structured data store or closely related support file;
• memory artifact.

4. Handle ambiguous cases#

When unsure how to classify the file or where to place it:

1. prefer project placement over generic placement for project-bound files;
2. prefer the place that matches future retrieval;
3. help choosing the location by asking yourself: "Where would a human most naturally look for this later?";
4. prefer stable, meaningful placement over convenience.

See references/edge-cases.md for common ambiguous scenarios.

5. Choose the correct placement#

Based on the previous steps and the following points, choose the correct place for the file.

1. Prefer existing structure over new structure. Before creating a new folder, check whether an existing folder already matches the file's purpose.
2. Do not store files directly in the root of projects/, user-files/, entertainment/, data/, and tools/. Always use or create suitable sub-folders in these top-level folders.
3. Do not place new files directly in the workspace root, except for native OpenClaw files that are meant to live there as part of OpenClaw’s own operation.
4. Avoid unnecessary depth.
5. Avoid creating new top-level folders unless there is a clear structural reason.

See references/naming-and-structure.md for new folder naming and structural heuristics.

Output style#

When answering placement questions:

• be short and concrete;
• name the recommended path;
• explain why in one or two sentences;
• mention ambiguity if the choice is not obvious.