folder.md

Deterministic folder structure for agents.

The Problem

Agents Without Structure Drift

SOUL.md tells agents who they are. AGENTS.md tells them how to work. But nothing tells them where to put things. Without filesystem rules, chaos emerges.

Duplicate Projects

Agent creates /my-app, /MyApp, /my_app — three copies of the same thing.

Root Pollution

Files scattered across /, /home, /tmp, /Users. No canonical workspace.

Name Drift

project-v2, project-new, project-final, project-final-v2, project-FINAL.

Lost Context

Agent forgets where it put things. Asks you to find files it created.

466 open-source AI agent projects analyzed — 0 had standardized filesystem conventions.

MSR 2026 · arXiv:2510.21413

Reference Architecture

A Complete Agent Workspace

folder.md defines the canonical structure for agent filesystems. Compatible with OpenClaw, Cursor, Claude Code, and any SOUL.md-aware agent.

~/.agent/

folder.md compliant

~/.agent/
├── soul.json           # Agent manifest
├── SOUL.md             # Core personality
├── IDENTITY.md         # Who you are
├── AGENTS.md           # How you work
├── TOOLS.md            # Available capabilities
├── MEMORY.md           # Persistent context
├── HEARTBEAT.md        # Autonomous check-in
│
├── folder.md           # ← Filesystem rules
│
├── projects/           # All project work
│   ├── acme-api/
│   │   ├── project.md
│   │   ├── tasks.md
│   │   ├── context/
│   │   │   ├── requirements.md
│   │   │   └── decisions.md
│   │   └── folder.md   # Project-specific overrides
│   │
│   └── personal-site/
│       ├── project.md
│       ├── tasks.md
│       └── research/
│
├── knowledge/          # Reusable reference material
│   ├── domains/
│   │   ├── typescript.md
│   │   └── nextjs.md
│   └── patterns/
│       ├── auth.md
│       └── api-design.md
│
├── memories/           # Long-term memory store
│   ├── 2026-02/
│   │   ├── 2026-02-25.md
│   │   └── 2026-02-26.md
│   └── summaries/
│       └── q1-2026.md
│
├── sessions/           # Session-specific data
│   └── current.md
│
├── skills/             # Installed capabilities
│   ├── folder.md
│   ├── deploy.md
│   └── code-review.md
│
└── temp/               # Ephemeral scratch space

projects/

Active work. Each project has its own context, tasks, and optional folder.md overrides.

knowledge/

Reusable reference material. Domain expertise, patterns, best practices.

memories/

Daily logs and summaries. Searchable via memory_search tool, not injected.

The Specification

folder.md Rules

A complete set of rules for deterministic agent filesystem behavior. Inject these into your agent's system prompt or install as a skill.

Root Rules

All agent work MUST be written to ~/projects/ or the configured workspace root.
System directories (/, /etc, /var) are read-only.
User home directories are protected by default.
Workspace root MUST be configurable via agents.defaults.workspace.

Project Structure

Each project lives in its own directory under /projects/.
project.md is REQUIRED — contains name, description, status, and goals.
tasks.md is REQUIRED — tracks active, blocked, and completed tasks.
folder.md is OPTIONAL — overrides global rules for this project.
context/ directory for project-specific knowledge and decisions.

Naming Conventions

Use lowercase with hyphens: my-project, api-server, landing-page.
Underscores, spaces, or mixed case: my_project, My Project, MyProject.
Names must be unique within /projects/.
Version suffixes are discouraged: my-project-v2, my-project-final.

Anti-Duplication Rules

Before creating, check for exact match in existing directories.
Check for fuzzy matches: api-server vs api_server vs apiServer.
Check for semantic equivalents: landing-page vs homepage vs website.
If match found, use existing directory — do not create new.
If uncertain, ASK the user before creating.

Write Boundaries

ALWAYS resolve to canonical project path before writing.
CREATE new directory only after checking for existing match.
NEVER write to root / directory.
NEVER create duplicate structures.
NEVER scatter files across unrelated directories.

Knowledge Layer

/knowledge/ stores reusable, project-agnostic reference material.
/knowledge/domains/ for technology-specific knowledge.
/knowledge/patterns/ for architectural patterns and best practices.
Knowledge files are read-only by default — agents should not modify.

Memory System

/memories/ stores daily logs and periodic summaries.
Daily files use ISO format: YYYY-MM-DD.md.
Memory files are NOT injected — accessed via memory_search tool.
Summaries aggregate daily logs: weekly, monthly, quarterly.

Skills Directory

/skills/ contains installed agent skills.
Each skill is a single SKILL.md file with metadata and instructions.
Skills are loaded on-demand based on context, not injected.
Compatible with skills.sh and the Vercel AI SDK bash-tool.

Use Cases

Structure for Any Domain

folder.md adapts to your workflow. Software, ops, research, content — the same rules create coherent structure everywhere.

Software Projects

APIs, web apps, libraries. Each gets a project.md, tasks.md, and context/ for decisions.

/projects/acme-api/

project.mdtasks.mdcontext/

Business Operations

Company processes, SOPs, team workflows. Living documentation that evolves.

/projects/ops-handbook/

processes/sops/team/

Personal Context

Preferences, communication style, recurring tasks. USER.md with folder.md structure.

/knowledge/personal/

preferences.mdroutines.md

Client Work

Isolated contexts per client. Each client gets their own project with scoped knowledge.

/projects/client-acme/

briefs/deliverables/comms/

Research & Learning

Domain knowledge, learning paths, notes. Organized under /knowledge/ for reuse.

/knowledge/domains/

typescript.mdnextjs.mdai-sdk.md

Content & Writing

Blog posts, documentation, newsletters. Projects with drafts/, published/, and assets/.

/projects/blog/

drafts/published/assets/

Installation

Add to Your Agent

folder.md works with any AI agent. Install via skills.sh, add to OpenClaw, or inject directly into your system prompt.

skills.sh

Install via the skills CLI — works with 18+ AI agents.

npx skills add houstongolden/folder-md

Adds folder.md as an agent skill. Auto-loads when filesystem operations are detected.

OpenClaw

Add to your OpenClaw workspace skills folder.

cp folder.md ~/.openclaw/workspace/skills/

OpenClaw will auto-discover and load the skill on startup.

System Prompt

Inject directly into your agent's system prompt.

# Copy folder.md contents to your system prompt

Works with any LLM. Add to AGENTS.md or your custom prompt file.

SKILL.mdfolder

Full skill definition with all rules and compatibility info.

Click "View Full Skill" to see the complete SKILL.md content.

Works with Vercel AI SDK

As of January 2026, skills work directly inside the bash-tool runtime. Your AI SDK agent can discover, download, and execute folder.md alongside filesystem context.

import { generateText } from 'ai'
import { createSavoir } from '@savoir/sdk'

const savoir = createSavoir({
  apiUrl: process.env.SAVOIR_API_URL!,
  apiKey: process.env.SAVOIR_API_KEY,
})

// folder.md rules are auto-loaded via skills
const { text } = await generateText({
  model: yourModel,
  tools: savoir.tools, // includes bash, bash_batch
  maxSteps: 10,
  prompt: 'Create a new project called acme-api',
})

Philosophy

Structure creates clarity.

Clarity prevents drift.

Drift kills intelligence.