folder.md

The boring default folder contract for AI agent workspaces.

Agents know who they are (SOUL.md) and how to work (AGENTS.md). But nothing tells them where to put things. folder.md fixes that.

Quick Start

Drop a FOLDER.md file in your workspace root. That's it.

Terminal

# Using clawhub
clawhub install folder-md

# Or using skills.sh
npx skills add folder-md

Installation

Option 1: clawhub

clawhub install folder-md

Option 2: skills.sh

npx skills add folder-md

Option 3: Manual

Copy the FOLDER.md template below into your workspace root.

Folder Structure

The default layout for any agent workspace:

FOLDER.md

./
├── FOLDER.md            # You are here
├── PROJECT.md           # Project brief, goals, status
├── /prompt/             # Agent prompt & config files
│   ├── SOUL.md          # Core personality & behavior
│   ├── IDENTITY.md      # Role & capabilities
│   ├── USER.md          # Facts about the user
│   ├── RULES.md         # Hard constraints
│   └── MEMORY.md        # Curated long-term notes
├── /notes/              # Human + agent notes
│   ├── daily/           # Daily logs: YYYY-MM-DD.md
│   └── topics/          # Topic-specific docs
├── /drafts/             # WIP — agent can overwrite
├── /final/              # Approved — do not overwrite
└── /skills/             # Workspace-specific skills

Rules

Write only to listed directories. Do not create new top-level folders without asking.
Use lowercase-kebab-case. For all new files and directories.
Check before creating. Look for existing exact, fuzzy, and semantic matches.
No version suffixes. No -v2, -final, -new, -copy. One directory, one name.
drafts/ is scratch space. Write freely, iterate, overwrite.
final/ is locked. Only write here when user says "finalize" or "ship it."
prompt/ is read-only. Unless user explicitly asks to update.
notes/ is append-only. Add new notes, don't overwrite existing ones.
Create missing dirs. If a directory doesn't exist yet, create it before writing.

Write Boundaries

Directory	Permission	Notes
drafts/	Read/Write	Your scratch space
final/	Write on "finalize"	Locked until approved
notes/	Append-only	Add new, don't overwrite
prompt/	Read-only	Unless explicitly asked
skills/	Read/Write	Workspace-specific skills

Base Template

The minimal FOLDER.md for any workspace:

FOLDER.md

# FOLDER.md

> The folder contract for this workspace. Agents: read this before any file operation.

## Layout

./
├── FOLDER.md            # You are here
├── PROJECT.md           # Project brief, goals, status
├── /prompt/             # Agent prompt & config files
│   ├── SOUL.md
│   ├── IDENTITY.md
│   ├── USER.md
│   ├── RULES.md
│   └── MEMORY.md
├── /notes/
│   ├── daily/
│   └── topics/
├── /drafts/
├── /final/
└── /skills/

## Rules

- Write only to directories listed above.
- Use lowercase-kebab-case for all new files.
- Check before creating (exact, fuzzy, semantic match).
- No version suffixes (-v2, -final, -new).
- drafts/ is your scratch space.
- final/ is locked until user says "finalize."
- prompt/ is read-only unless explicitly asked.
- notes/ is append-only.
- Create missing dirs before writing.

Developer Template

Extended layout for coding projects:

FOLDER.md (Developer)

## Layout (Extended)

./
├── /src/                # Source code
├── /tests/              # Test files
├── /docs/               # Documentation
├── /scripts/            # Build/deploy scripts
└── /config/             # Configuration files

Founder Template

Extended layout for founders and operators:

FOLDER.md (Founder)

## Layout (Extended)

./
├── /strategy/           # Vision, planning, OKRs
├── /meetings/           # Meeting notes & agendas
├── /decisions/          # Decision logs (ADRs)
├── /metrics/            # KPIs and dashboards
└── /comms/              # Internal/external comms

Content Creator Template

Extended layout for content and marketing:

FOLDER.md (Content Creator)

## Layout (Extended)

./
├── /content/            # Blog posts, articles
├── /social/             # Social media drafts
├── /assets/             # Images, videos, graphics
├── /calendar/           # Content calendar
└── /analytics/          # Performance tracking

Agency Template

Extended layout for client work:

FOLDER.md (Agency)

## Layout (Extended)

./
├── /clients/
│   └── {client-name}/   # One folder per client
│       ├── brief.md
│       ├── /deliverables/
│       └── /feedback/
├── /templates/          # Reusable templates
└── /internal/           # Internal docs

SKILL.md

The full skill definition for OpenClaw/skills.sh:

SKILL.md

---
name: folder-md
version: 0.1.0
description: Deterministic folder structure for AI agent workspaces
author: Houston Golden
license: MIT
tags: [filesystem, organization, workspace, agent]
---

# folder-md

The boring default folder contract for AI agent workspaces.

## Rules

1. Write only to directories listed in FOLDER.md
2. Use lowercase-kebab-case for all new files
3. Check before creating (exact, fuzzy, semantic match)
4. No version suffixes (-v2, -final, -new)
5. drafts/ is scratch space
6. final/ is locked until "finalize"
7. prompt/ is read-only unless asked
8. notes/ is append-only
9. Create missing dirs before writing

Extending

folder.md is a starting point. Extend it for your use case:

Add domain-specific directories to the Layout section
Add custom rules for your workflow
Keep the base rules - they prevent drift
Document any changes in the FOLDER.md itself

FAQ

Why not just use .gitignore patterns?

.gitignore tells git what to ignore. FOLDER.md tells agents where to write. Different concerns.

Does this work with Claude/GPT/etc?

Yes. It's just a markdown file. Any agent that can read files can follow FOLDER.md.

What if I need different structures for different projects?

Each workspace gets its own FOLDER.md. Extend the base template for your needs.

How does this relate to SOUL.md?

SOUL.md defines who the agent is. FOLDER.md defines where it puts things. They're complementary.