workspace-structure

Maintain a clean workspace file structure. Use when deciding where files and folders belong in a workspace, choosing temporary vs. durable storage, or distinguishing projects, installed apps, tools, scripts, data stores, user files, reports, sources, reference material, and entertainment.

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.
• An application's development project and its installed instance are distinct entities; keeping them in separate locations is a justified separation.
• 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.
• apps/ — operational application installations, whether being set up or already in use.
• 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/ — standalone or shared durable structured data stores and their supporting files that are not owned by a particular application.
• scripts/ — standalone reusable scripts.
• tools/ — reusable helper binaries, portable utilities, 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, installed applications, 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, except for artifacts belonging to an application's operational installation, whether planned or already in use. Another 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:

• an application's operational installation or files intended to form part of it;
• independent 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;
• standalone or shared 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, subject to the development/operation distinction above;
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/, apps/, user-files/, entertainment/, data/, and tools/. 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.