{"skill":{"slug":"workspace-files-organization","displayName":"Workspace Files Organization","summary":"Use before creating or moving any durable workspace files, folders, scripts, project state, monitor state, cron-backed artifacts, outputs, or project-specifi...","description":"---\nname: workspace-files-organization\ndescription: 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// with outputs/state in data/.\nhomepage: https://github.com/tixastronauta/openclaw-skill-workspace-files-organization\n---\n\n# Workspace Files Organization\n\nOrganize new work so that project-specific files stay together, reusable utilities stay separate, and outputs live with the work that produced them.\n\n## Mandatory Trigger\n\nBefore creating any durable workspace file or folder, stop and classify it:\n\n- If it belongs to a specific topic, goal, monitor, cron job, report, investigation, or automation, create/use `projects//` first.\n- If it is project state, cache, output, downloaded data, generated content, or monitor state, put it under `projects//data/`.\n- 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`.\n\nA 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.\n\n## Core Rules\n\n- Put all files that belong to a specific project under `projects//` when that work has its own topic, goal, or context.\n- Treat code, notes, configs, prompts, supporting assets, and outputs for that project as project-local unless there is a strong reason not to.\n- Put project outputs under `projects//data/`.\n- Do not create or use a global `data/` directory.\n- Use `scripts/` only for genuinely generic, reusable utilities that are not tied to one project.\n- Do not put project-specific scripts in `scripts/`.\n- Treat every body of work that requires created files as a project from the start.\n- Create or choose `projects//` before generating project-specific files.\n- Do not create project files in ad hoc locations with the intention of organizing them later.\n\n## New Project Folder Standard\n\nWhen creating a new project folder, create:\n\n- `projects//README.md`\n\nAdd a short README immediately. Include:\n\n- what the project is about\n- when the project was started\n- a brief note about the current purpose or scope\n\nKeep the README short unless the user asks for more detail.\n\n## Recommended Layout\n\nUse this layout by default for project-specific work:\n\n```text\nprojects/\n /\n README.md\n data/\n ...project files...\n```\n\nPossible project files include:\n\n- scripts and code\n- notebooks\n- prompts\n- configuration files\n- scraped or downloaded inputs\n- generated outputs\n- summaries or notes\n\nOnly add extra subfolders when they improve clarity.\n\n## Placement Heuristics\n\nChoose locations in this order:\n\n1. When work requires creating durable files, start by creating or choosing `projects//`.\n2. If the file belongs to that project, place it in `projects//`.\n3. If it is state, cache, or output generated by that project, place it in `projects//data/`.\n4. If it is a reusable utility that clearly works across unrelated projects, place it in `scripts/`.\n5. If there is ambiguity, prefer creating a new project folder over placing files at the workspace root, a custom top-level folder, or `scripts/`.\n\n## Root Directory Discipline\n\nAvoid placing new project files directly in the workspace root.\n\nAllow root placement only for files that are truly workspace-wide, such as:\n\n- top-level workspace documentation\n- shared agent notes\n- global configuration expected at the root\n\n## Naming Guidance\n\n- Use short, descriptive project names.\n- Prefer lowercase names.\n- Use hyphens or underscores consistently within the workspace.\n- Name projects by domain or outcome, for example `dges-crawl`, `invoice-reconciliation`, or `travel-planning`.\n\n## Migration Guidance\n\nWhen you find project-specific files scattered in the root or mixed into `scripts/`:\n\n- group them under a new or existing `projects//`\n- move outputs into `projects//data/`\n- leave only truly generic utilities in `scripts/`\n- update references or commands if paths changed\n- treat the scattered state as something to fix, not as an acceptable starting pattern\n\n## Decision Standard\n\nPrefer a structure that makes it obvious where a future reader should look first.\n\nWhen in doubt, create a project folder first and keep everything for that body of work under `projects//`.\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":377,"installsAllTime":1,"installsCurrent":1,"stars":1,"versions":1},"createdAt":1777725672876,"updatedAt":1778492830283},"latestVersion":{"version":"1.0.0","createdAt":1777725672876,"changelog":"- Initial release of the workspace-files-organization skill.\n- Enforces strict project-based file and folder organization under `projects//` with outputs/state in `data/`.\n- Provides clear classification and placement rules for new workspace files, folders, scripts, or documentation.\n- Prohibits ad hoc and root-level dumping of project assets and outputs.\n- Includes a mandatory README.md for every project, with concise project information.\n- Offers guidance on scripts, naming, migration, and maintaining clarity for future readers.","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"tixastronauta","userId":"s17504s9peqs3gnjmkbsb58a5d83mvf0","displayName":"Tiago 'Tix' Carvalho","image":"https://avatars.githubusercontent.com/u/402726?v=4"},"moderation":null}