Yesterday, a deep-dive on the anatomy of the .claude/ folder hit Hacker News number two. Two hundred sixty-one points, 134 comments. Developers who have been using Claude Code for months were suddenly arguing about what actually belongs in that folder, what a good AGENTS.md looks like, and whether installing third-party skills is safe.
One comment thread landed on a clear conclusion: "never install any skill you didn't create yourself — you blow up your context window." That's the distillation of a real problem. When you dump too much into a workspace config without understanding each line, your agent's context window fills up with junk before the first meaningful task begins.
The good news: if you use OpenClaw, your workspace files are already structured to avoid exactly this. And if you haven't built your AGENTS.md yet, the OpenAgents.mom wizard generates a clean, scoped version for you in minutes.
What AGENTS.md Actually Does
In an OpenClaw workspace setup, each workspace file has a distinct job. SOUL.md is your agent's personality and values. USER.md is context about the human it serves. HEARTBEAT.md is the schedule for recurring tasks.
AGENTS.md is the operating manual. It tells the agent how to behave across sessions: how to use memory, when to ask for approval before acting, how to scope tool access, what communication cadence to follow, and what the session workflow looks like start-to-finish.
Think of it as the difference between "who you are" (SOUL.md) and "how you work" (AGENTS.md). A sales agent and a DevOps watchdog might share similar values — no lying, no overreach — but their operating manuals are completely different.
Why the .claude/ Folder Conversation Matters
Claude Code introduced a .claude/ directory that serves the same purpose as OpenClaw's workspace folder. You drop an AGENTS.md file in there, and the model reads it before every session. It works. Developers have been doing it for a while.
But the HN thread exposed the gap between "it works" and "it works well." People were:
- Stacking every available skill without reading what they actually inject
- Writing AGENTS.md files that contradict SOUL.md because the two files were created independently
- Granting tool access by habit instead of by explicit need
The result is an agent with a bloated context window, unclear priorities, and tool permissions wider than the tasks actually require. It still talks. It just isn't reliable.
The Context Window Tax You're Not Thinking About
Every line in your workspace files burns context tokens at the start of every session. For a conversational exchange, that's fine. For an agent running hundreds of scheduled tasks per week, it compounds fast.
The MCP context bloat problem got a lot of attention when Apideck showed that loading tool schemas could consume 72% of a context window before a single task ran. The same problem hits AGENTS.md files that accumulate cruft — skills nobody uses, commented-out old instructions, and tool permissions that were "just in case" additions months ago.
A lean AGENTS.md is not about stripping features. It's about knowing exactly what each line is for and removing everything that isn't.
What a Well-Structured AGENTS.md Looks Like
A clean AGENTS.md has four sections, and that's enough:
Session lifecycle — what the agent reads at the start of a session, how it initializes memory, and what it writes at the end.
Workflow rules — the specific sequence for the agent's primary job. A content agent reads the backlog, picks a topic, drafts, generates images, uploads, shares. Every step explicit.
Memory protocol — how and when to write to daily memory files vs. long-term MEMORY.md. When to update the topic backlog status. What counts as worth remembering.
Boundaries — what the agent should never do without human approval. What files it writes vs. reads. Whether it can execute shell commands or only file operations.
That's it. No skills section unless you've consciously added a specific skill with a known context cost. No feature flags. No commented-out instructions from six iterations ago.
The Skill Trust Problem
The HN comment about skills was blunt for a reason. Skills in a Claude Code workspace are executable scripts that inject instructions and, sometimes, tool definitions into your session. A skill you don't fully understand is a blind spot in your agent's behavior.
The same principle applies to OpenClaw's skill system. OpenClaw's security-first approach puts this plainly: grant the minimum tool access required for the actual job. If your content agent needs to run gog drive upload, that's a shell exec permission with a specific command. Not "full exec access to everything."
Installing an unread, untrusted skill into your workspace is the agent equivalent of running sudo pip install from a GitHub README you skimmed. It might be fine. It might not. And you won't know until something goes wrong.
Common Mistakes
- Installing every available skill. Each skill injects instructions and often tool definitions. Unread skills are unreviewed permissions — and every one burns context tokens before your agent does anything.
- Letting AGENTS.md grow without pruning. Instructions accumulate over time. Run a quarterly review: if a section no longer matches your agent's actual job, delete it.
- Granting blanket exec access. "Allow exec" is not the same as "allow exec for this one command." Scope shell permissions to specific commands and directories.
- Copying someone else's AGENTS.md without reading it. A config that works for someone else's workflow will silently conflict with yours. Read every line before you deploy it.
- Splitting identity and operating logic across files inconsistently. If SOUL.md says "never send emails without approval" and AGENTS.md has a workflow step that sends emails automatically, you have a conflict that will surface at the worst moment.
Security Guardrails
- Review every skill before install. Read the SKILL.md, check what tools it declares, and understand what it injects into your session context before enabling it.
- No secrets in workspace files. API keys, tokens, passwords — these belong in environment variables, not in AGENTS.md or SOUL.md. Workspace files are readable text files; treat them accordingly.
- Version-control your workspace. Store your workspace folder in a private git repo. Every change is diffable, every mistake is reversible, and you have an audit trail if something goes wrong.
- Keep approval gates for destructive actions. Any AGENTS.md workflow step that writes to external systems, sends messages to real people, or modifies files outside the workspace should require explicit human confirmation.
Own It, Edit It, Version It
This is where the .claude/ folder comparison reveals the real difference. When you build your AGENTS.md inside Claude's managed environment, you're working inside Anthropic's system. When you build it for OpenClaw, you own plain markdown files that live on your infrastructure.
Your files survive platform decisions. If Anthropic changes how .claude/ works, your workflow changes with it. If your OpenClaw workspace files stop working on one host, you move them to another. The config is yours.
That's not a philosophical point — it's a practical one. Developers who've built reliable agents on OpenClaw have git repos with two years of AGENTS.md commit history. They know exactly when they changed a permission, added a workflow step, or removed a broken integration. That audit trail is not available in a managed workspace.
The Fastest Path to a Clean Config
Building a well-structured AGENTS.md from scratch takes time, especially your first time. You need to understand the session lifecycle, know which memory protocols to set up, and think through the permission boundaries before you write a single line.
The OpenAgents.mom wizard handles this. You answer questions about your agent's job — what it does, what channels it uses, what tools it needs, when it should ask for approval. The wizard generates a complete workspace bundle: SOUL.md, AGENTS.md, HEARTBEAT.md, USER.md, TOOLS.md, MEMORY.md, and a config snippet. Every file consistent with every other. Every permission scoped to your stated workflow.
No junk-drawer skills. No permissions you didn't ask for. No context window tax from features you're not using.
You download the ZIP, review the files — they're readable markdown, this takes 10 minutes — and deploy to your OpenClaw server.
Generate Your Clean AGENTS.md Workspace Bundle
Answer 10 minutes of questions about your agent's job and get a complete, scoped workspace bundle — SOUL.md, AGENTS.md, HEARTBEAT.md, and the rest. No junk skills, no over-broad permissions, no surprises.