Workspace Files Organization

SKILL.md

---
name: workspace-files-organization
description: Use before creating or moving any durable workspace files, folders, scripts, project state, monitor state, cron-backed artifacts, outputs, or project-specific documentation. Prevents clutter by keeping each body of work under projects/<name>/ with outputs/state in data/.
homepage: https://github.com/tixastronauta/openclaw-skill-workspace-files-organization
---

# Workspace Files Organization

Organize new work so that project-specific files stay together, reusable utilities stay separate, and outputs live with the work that produced them.

## Mandatory Trigger

Before creating any durable workspace file or folder, stop and classify it:

- If it belongs to a specific topic, goal, monitor, cron job, report, investigation, or automation, create/use `projects/<name>/` first.
- If it is project state, cache, output, downloaded data, generated content, or monitor state, put it under `projects/<name>/data/`.
- Only skip this skill for trivial temporary shell output that is not written to disk, or for clearly workspace-wide files such as `MEMORY.md`, `AGENTS.md`, `USER.md`, `SOUL.md`, or `TOOLS.md`.

A monitor with persistent state is a project. A cron-backed workflow with files is a project. A one-off investigation that creates reusable notes or outputs is usually a project.

## Core Rules

- Put all files that belong to a specific project under `projects/<name>/` when that work has its own topic, goal, or context.
- Treat code, notes, configs, prompts, supporting assets, and outputs for that project as project-local unless there is a strong reason not to.
- Put project outputs under `projects/<name>/data/`.
- Do not create or use a global `data/` directory.
- Use `scripts/` only for genuinely generic, reusable utilities that are not tied to one project.
- Do not put project-specific scripts in `scripts/`.
- Treat every body of work that requires created files as a project from the start.
- Create or choose `projects/<name>/` before generating project-specific files.
- Do not create project files in ad hoc locations with the intention of organizing them later.

## New Project Folder Standard

When creating a new project folder, create:

- `projects/<name>/README.md`

Add a short README immediately. Include:

- what the project is about
- when the project was started
- a brief note about the current purpose or scope

Keep the README short unless the user asks for more detail.

## Recommended Layout

Use this layout by default for project-specific work:

```text
projects/
  <name>/
    README.md
    data/
    ...project files...
```

Possible project files include:

- scripts and code
- notebooks
- prompts
- configuration files
- scraped or downloaded inputs
- generated outputs
- summaries or notes

Only add extra subfolders when they improve clarity.

## Placement Heuristics

Choose locations in this order:

1. When work requires creating durable files, start by creating or choosing `projects/<name>/`.
2. If the file belongs to that project, place it in `projects/<name>/`.
3. If it is state, cache, or output generated by that project, place it in `projects/<name>/data/`.
4. If it is a reusable utility that clearly works across unrelated projects, place it in `scripts/`.
5. If there is ambiguity, prefer creating a new project folder over placing files at the workspace root, a custom top-level folder, or `scripts/`.

## Root Directory Discipline

Avoid placing new project files directly in the workspace root.

Allow root placement only for files that are truly workspace-wide, such as:

- top-level workspace documentation
- shared agent notes
- global configuration expected at the root

## Naming Guidance

- Use short, descriptive project names.
- Prefer lowercase names.
- Use hyphens or underscores consistently within the workspace.
- Name projects by domain or outcome, for example `dges-crawl`, `invoice-reconciliation`, or `travel-planning`.

## Migration Guidance

When you find project-specific files scattered in the root or mixed into `scripts/`:

- group them under a new or existing `projects/<name>/`
- move outputs into `projects/<name>/data/`
- leave only truly generic utilities in `scripts/`
- update references or commands if paths changed
- treat the scattered state as something to fix, not as an acceptable starting pattern

## Decision Standard

Prefer a structure that makes it obvious where a future reader should look first.

When in doubt, create a project folder first and keep everything for that body of work under `projects/<name>/`.