Skill: darinrowe/multi-agent-filesystem-governance (version 1.0.1)

--- name: multi-agent-filesystem-governance description: Govern filesystem organization and file-operation decisions in multi-agent environments. Use when deciding where files should live across agent-private workspaces, shared resources, archives, downloads, scripts, notes, knowledge vaults, and code project folders; when defining directory conventions; when triaging downloads; when preventing cross-agent overwrites; or when standardizing file placement and lifecycle rules for reusable agent setups. --- # Multi-Agent Filesystem Governance Use this skill to make safe, consistent filesystem decisions in environments where multiple agents may create, edit, move, download, organize, or archive files. This skill governs **ownership, placement, lifecycle, and write boundaries**. It is not tied to a specific product, path layout, operating system, or note-taking tool. ## Core objective Ensure that every file has: 1. a clear ownership scope 2. a clear storage location 3. a clear lifecycle state 4. a clear modification rule When uncertain, choose the narrowest safe scope and the least shared location. ## Scope model Classify every file, folder, and file operation into exactly one of these scopes: - **agent-private**: used by one agent only - **shared**: intentionally reusable or accessible by multiple agents - **archive**: inactive, historical, completed, frozen, or retained for reference If scope is unclear, default to **agent-private**. ## Storage model Use three top-level storage categories conceptually, even if local directory names differ: - **agent areas**: private per-agent working locations - **shared areas**: common reusable resources - **archive areas**: inactive or historical materials Do not depend on any single hard-coded path. Preserve conceptual boundaries even when adapting to local layouts. ## Required decision order Before creating, editing, moving, renaming, or deleting files, determine the following in order: 1. What is the artifact? 2. Is it temporary, active, reusable, frozen, or historical? 3. Is it private to one agent or shared by multiple agents? 4. What is the narrowest valid location? 5. Will this action affect other agents or shared workflows? If any answer is unclear, choose a private non-destructive location first. ## Default rules ### Prefer private over shared If a file does not clearly require cross-agent reuse, place it in an agent-private location. ### Do not write across agent boundaries by default Do not create, edit, move, or overwrite files belonging to another agent unless the task explicitly requires it. ### Treat shared locations as high-impact Writing to a shared location is a wider-scope action. Use shared locations only when reuse, collaboration, or standardization is intended. ### Keep archive separate from active work Archived material is not an active workspace. Do not continue editing files in archive locations. Restore or copy them into an active or private area first. ### Treat temporary locations as disposable Do not keep the only important copy of a file in a temp or scratch location. ## Content-type placement guidance Apply these rules regardless of exact local path names. ### Skills - Put reusable multi-agent skills in a shared skills location. - Put experimental, agent-specific, or override skills in an agent-private skills location. - If the same skill exists in both shared and private locations, prefer the more specific private version for that agent. ### Workspaces - Put active working files, drafts, and intermediate artifacts in the current agent’s private workspace unless they are intentionally shared. - Do not move private task files into shared locations prematurely. ### Scripts - Put reusable utility scripts in a shared scripts location. - Put task-specific or agent-specific scripts in a private scripts location or within the relevant project. - Do not scatter unrelated scripts across arbitrary folders. ### Downloads - Route newly downloaded files into a dedicated intake location first. - Classify and move them later into proper long-term locations. - Do not leave downloads scattered across project folders, knowledge vaults, or temp directories without intent. ### Knowledge notes and vaults - Put durable reference notes and curated knowledge into a designated knowledge base or vault location. - Keep rough task notes private until they are worth preserving or sharing. - Do not use the knowledge base as a dumping ground for arbitrary transient files. ### Code projects - Store code projects in designated project locations. - For durable, long-lived repositories, prefer a dedicated project root such as `~/projects/<repo>`. - Use `/tmp/...` for temporary reproduction, validation, or throwaway clones, then promote ongoing work into `~/projects/<repo>`. - Separate experimental, active, frozen, and archived projects when practical. - Do not mix project source trees with general downloads, archives, note repositories, or agent runtime/config trees. - Read `references/project-directory-best-practices.md` when the question is specifically about where formal repositories should live versus where temporary repo work should happen. ### Archives - Move inactive, completed, superseded, or retained materials into archive locations. - Keep archive structure stable and low-churn. - Prefer append-only archival behavior unless explicit cleanup is required. ## File lifecycle model Classify files into one of these lifecycle states: - **temporary**: scratch, disposable, rebuildable - **active**: currently being edited or used - **shared**: actively reused by multiple agents - **frozen**: paused but potentially resumable - **archived**: historical, completed, or retained for record When lifecycle changes, move the file or justify keeping it in place. ## Safety rules for file operations ### Create Create files in the narrowest valid scope first. ### Edit Edit in place only when ownership and scope are clear. ### Move Move files when ownership or lifecycle changes. ### Copy Copy instead of move when preserving history or minimizing disruption matters. ### Delete Delete only when the file is clearly temporary, redundant, or explicitly approved for removal. ### Rename Rename to improve clarity, ownership, lifecycle visibility, or discoverability — not for cosmetic churn alone. ## Collision and precedence rules When equivalent resources exist in multiple scopes, prefer the most specific valid source: 1. agent-private 2. shared 3. bundled, default, or global Use overrides intentionally. Do not create duplicate variants without reason. ## What to avoid Avoid these patterns: - dumping everything into one shared root - using archive as a live workspace - downloading directly into long-term storage without triage - scattering scripts across unrelated folders - mixing code projects with note-vault content - placing durable knowledge only in temporary notes - editing another agent’s private area without explicit need - using shared locations by default “just in case” ## Recommended behavior when uncertain If the correct location is unclear: 1. choose agent-private 2. choose non-destructive actions 3. preserve reversibility 4. avoid shared writes 5. ask for clarification only when the ambiguity materially affects future organization or other agents ## Decision template When deciding where something should go, return: - **Scope**: - **Lifecycle**: - **Recommended location type**: - **Reason**: - **Shared-impact note**: ## Output expectations When applying this skill: - make scope explicit - make lifecycle explicit - recommend the narrowest valid location - state whether other agents are affected - prefer durable rules over ad hoc path guesses

path: references/anti-patterns.md
content: # Anti-Patterns

Use this file to recognize and avoid filesystem behaviors that create confusion, duplication, or cross-agent risk.

## 1. Shared-by-default placement

Anti-pattern:
Putting new files into shared locations before their reuse value is clear.

Why it is harmful:
This increases clutter, raises cross-agent risk, and makes ownership unclear.

Prefer instead:
Start in the narrowest private location. Promote to shared only when reuse is intentional.

---

## 2. Archive as live workspace

Anti-pattern:
Continuing to edit files directly inside archive locations.

Why it is harmful:
Archive loses its meaning as a historical or frozen state and becomes impossible to trust.

Prefer instead:
Restore or copy materials back into an active or private workspace before editing.

---

## 3. Permanent download pile

Anti-pattern:
Letting download intake locations become long-term storage.

Why it is harmful:
Downloaded files remain unclassified, hard to search, and disconnected from their real purpose.

Prefer instead:
Use a dedicated intake area, then sort files into projects, references, knowledge, private workspaces, or archive.

---

## 4. Script sprawl

Anti-pattern:
Scattering reusable scripts across random folders, project roots, temp directories, and note locations.

Why it is harmful:
Scripts become hard to find, duplicate unnecessarily, and lose ownership context.

Prefer instead:
Place reusable scripts in a shared scripts area and keep project-specific scripts inside the relevant project.

---

## 5. Knowledge vault as junk drawer

Anti-pattern:
Using the knowledge vault as a generic dump for exports, binaries, random downloads, and transient files.

Why it is harmful:
Knowledge quality collapses and the vault stops serving as durable reference.

Prefer instead:
Store only curated notes, durable references, and intentionally preserved knowledge artifacts in the knowledge location.

---

## 6. Mixing source trees with unrelated files

Anti-pattern:
Putting downloads, ad hoc notes, media exports, or unrelated utilities directly into code project roots.

Why it is harmful:
Project boundaries blur, automation becomes brittle, and cleanup gets harder.

Prefer instead:
Keep project roots focused on project content, with clearly scoped subdirectories where necessary.

---

## 7. Cross-agent overwrite without intent

Anti-pattern:
Editing or reorganizing another agent’s private files without explicit need.

Why it is harmful:
This breaks ownership expectations and can destroy structure that only the owning agent understands.

Prefer instead:
Treat private agent areas as protected by default. Use shared or coordinated areas for collaboration.

---

## 8. Duplicate variants without purpose

Anti-pattern:
Keeping multiple copies of the same skill, script, template, or note across private, shared, and project locations without clear precedence.

Why it is harmful:
It becomes unclear which version is authoritative and updates drift apart.

Prefer instead:
Keep one authoritative version whenever possible. Use overrides intentionally and document the reason.

---

## 9. Temp-only critical files

Anti-pattern:
Keeping the only important copy of a file in a temp or scratch location.

Why it is harmful:
Temporary storage is disposable and may be cleaned up or ignored.

Prefer instead:
Move or copy important artifacts into an active private, shared, project, or archival location as soon as they matter.

---

## 10. Flat shared root chaos

Anti-pattern:
Putting all shared files into one undifferentiated shared directory.

Why it is harmful:
The shared area becomes hard to search, hard to automate, and risky to modify.

Prefer instead:
Separate shared content by type, such as skills, scripts, downloads, projects, templates, assets, or references.

---

## 11. No lifecycle distinction

Anti-pattern:
Treating temporary, active, frozen, and archived files as if they belong in the same places.

Why it is harmful:
Agents cannot tell what is safe to modify, ignore, clean up, or preserve.

Prefer instead:
Use different areas or clear conventions for lifecycle states.

---

## 12. Cosmetic reorganization churn

Anti-pattern:
Renaming and moving files frequently without improving ownership, lifecycle clarity, or discoverability.

Why it is harmful:
Path churn breaks links, scripts, habits, and recovery efforts while adding little value.

Prefer instead:
Reorganize only when it clarifies scope, lifecycle, or future automation.


path: references/examples.md
content: # Examples

Use these examples to map common file operations to the correct scope, lifecycle, and storage location.

## Example 1: Newly downloaded document

A PDF, ZIP, image, or export file has just been downloaded and has not yet been reviewed.

- Scope: agent-private unless multiple agents will need it soon
- Lifecycle: temporary intake
- Recommended location type: download intake area
- Reason: newly downloaded files should be triaged before they are treated as durable knowledge, project assets, or archival material

Do not place new downloads directly into archives, knowledge vaults, or unrelated project folders unless the final destination is already certain.

## Example 2: Agent-specific scratch note

An agent creates a rough note during analysis, debugging, planning, or execution.

- Scope: agent-private
- Lifecycle: temporary or active
- Recommended location type: private workspace or private notes area
- Reason: rough notes are usually intermediate artifacts and should remain private until curated

Promote the note into a shared knowledge location only after it becomes useful beyond the current task or current agent.

## Example 3: Shared operating procedure

A procedure, workflow note, or policy is intended to guide multiple agents in repeated tasks.

- Scope: shared
- Lifecycle: shared active reference
- Recommended location type: shared knowledge base, shared notes area, or governance location
- Reason: operational guidance should be discoverable and stable when multiple agents depend on it

Do not keep shared procedure documents only in one agent’s private folder.

## Example 4: Reusable utility script

A script helps with repeated tasks such as cleanup, organization, export handling, archive rotation, or project initialization.

- Scope: shared if multiple agents use it; otherwise agent-private
- Lifecycle: active reusable utility
- Recommended location type: shared scripts area or private scripts area
- Reason: reusable scripts should be separated from ad hoc task outputs and given a predictable home

If the script is tightly tied to one project, keep it inside that project instead of a generic shared scripts area.

## Example 5: Project-specific helper script

A script exists only for one repository, one build flow, or one deployment workflow.

- Scope: project-local or agent-private
- Lifecycle: active
- Recommended location type: inside the project tree or the owning agent’s private area
- Reason: project-specific logic should remain near the project it serves

Do not move project-specific scripts into a global shared scripts area unless they have been intentionally generalized.

## Example 6: New code project

A new software project, automation tool, prototype, or repository is being created.

- Scope: shared if it is a multi-agent or team asset; otherwise agent-private
- Lifecycle: active or incubating
- Recommended location type: designated project area
- Reason: project roots should stay stable and distinct from downloads and notes

Do not start code projects inside temporary download folders or knowledge vaults.

## Example 7: Paused or inactive code project

A project is no longer active but may be resumed later.

- Scope: same ownership as before
- Lifecycle: frozen
- Recommended location type: frozen projects area or archive-ready holding area
- Reason: inactive projects should leave active work zones without losing resumability

If future work is unlikely, move the project into archive instead.

## Example 8: Completed project

A project has been delivered, replaced, or intentionally retired.

- Scope: usually shared if it served shared goals; otherwise private
- Lifecycle: archived
- Recommended location type: archive area
- Reason: completed work should leave active project areas to reduce clutter and ambiguity

Preserve recovery notes or build instructions before archival if future reopening may matter.

## Example 9: Curated reference note

A rough note has been cleaned up and is now useful as durable reference material.

- Scope: shared if broadly useful; otherwise private
- Lifecycle: durable reference
- Recommended location type: knowledge vault or reference area
- Reason: durable knowledge should live where it can be found and maintained

Do not leave long-term knowledge trapped in temporary folders or buried inside unrelated project trees.

## Example 10: Export generated from a project

A report, CSV export, rendered media file, or build artifact was created by a project.

- Scope: depends on intended consumers
- Lifecycle: temporary, active deliverable, or archival
- Recommended location type: project output area first, then shared delivery or archive area if needed
- Reason: outputs should stay traceable to the project until their final role is clear

Do not immediately scatter generated outputs into unrelated top-level directories.

## Example 11: Imported external reference material

A dataset, vendor document, API spec, or whitepaper is imported to support work across multiple tasks.

- Scope: shared if broadly reusable; otherwise private
- Lifecycle: active reference or archive
- Recommended location type: shared reference area, project-local docs area, or curated knowledge location
- Reason: imported references should be stored intentionally based on reuse level

Do not leave external references permanently mixed into raw download intake.

## Example 12: Agent handoff material

One agent prepares files that another agent will consume.

- Scope: shared unless the handoff is tightly scoped and temporary
- Lifecycle: active handoff
- Recommended location type: shared staging or designated handoff area
- Reason: cross-agent handoffs should not depend on one agent’s private workspace structure

Avoid hiding handoff materials in private temp directories.


path: references/project-directory-best-practices.md
content: # Project Directory Best Practices

Use this file when deciding where long-lived code repositories should live versus where temporary verification work should happen.

## Core rule

Use a dedicated long-term project root for real code repositories.

Default recommendation:

- `~/projects/<repo>` for active, durable code projects

Use temporary locations only for short-lived validation, reproduction, or one-off experiments.

## Recommended split

### Long-lived project repositories

Put active repositories that may be maintained, tested, released, or revisited into:

- `~/projects/<repo>`

Why:

- stable path for repeated work
- separate from agent runtime/config directories
- separate from temp cleanup risk
- easier to back up, monitor, and document

### Temporary verification work

Put throwaway clones, fast reproduction attempts, and one-off debugging into:

- `/tmp/...`

Why:

- easy to discard
- low commitment
- useful for isolated experiments before deciding a repo deserves a durable home

Do not leave the only important copy of a project in `/tmp`.

## What to avoid for long-term repositories

Do not keep formal project repositories long-term in:

- agent runtime/config trees such as `~/.openclaw/...`
- skill directories
- download folders
- note or knowledge-vault directories
- generic temp/scratch directories

These locations are better suited to runtime state, skills, intake, notes, or disposable work—not stable project ownership.

## Promotion rule

A good default workflow is:

1. use `/tmp/...` for quick reproduction or trial edits
2. once the work becomes ongoing, move or re-clone into `~/projects/<repo>`
3. keep future testing, release work, and maintenance in the durable project root

## Multi-agent guidance

For multi-agent environments:

- use `~/projects/<repo>` as the stable project root when a repository is meant to persist
- keep agent-private scratch files in private workspaces, not mixed into the project root unless they are project-relevant
- use temp clones for risky or disposable experiments when you do not want to disturb the durable repository

## Fast decision table

- **Need a real home for an active repo** -> `~/projects/<repo>`
- **Just reproducing or testing quickly** -> `/tmp/...`
- **Agent runtime/config/state** -> keep in runtime/config directories, not project roots
- **Downloaded but untriaged archive or zip** -> intake/download area first, not `~/projects` yet

## One-line rule

Use `~/projects` for durable code projects and `/tmp` for temporary experiments.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)