After a year of building these for clients, I've basically settled on: an agent is just a folder of markdown files

Reddit r/AI_Agents Tools
ai-agents markdown-files harness portability development architecture

Summary

The author argues that an AI agent is best understood as a folder of markdown files containing business knowledge and instructions, separate from the model and harness, enabling portability between rapidly improving harnesses.

Not the model, not the harness. Just a folder. That's where I've landed and it made the whole thing a lot simpler to think about. Quick context on how I got here. A year ago if someone said they built an agent they usually meant an n8n workflow or some custom-coded scaffolding, the stuff we'd now call a harness. Those were kind of a pain to set up, they worked all right, and honestly at this point they're more or less obsolete. What changed for me was Claude Code and OpenClaw showing how good and how general-purpose a harness could be, and then Codex catching up once OpenAI realized they were behind. The harnesses are improving so fast that building your own doesn't really make sense anymore. And since they keep leapfrogging each other, I want whatever I build to be portable enough to move from one to the next. Which kind of forces the question: if it's not the model and not the harness, what's actually the part that's *mine*? For me the answer is the folder. The harness already handles the capabilities, tools, file access, the loop, all of it. What it doesn't have is knowledge about a specific business and clear instructions on what to do with it. Give it enough of both and it's honestly surprising how much it'll handle, pretty much anything that gets done on a computer for the business. The thing that made it click for me is that a website is also just a folder, mostly html. The difference is we don't have an agreed-on way to arrange the agent files yet the way we do for a site. Google's Open Knowledge Format might end up being that, not sure yet, so for now I just structure it myself. One practical note: at the agency I run we build this folder before we do any real work for a client now, because everything else we've got sits on top of it. If the folder isn't there we can't really start. Still figuring out the best way to organize the inside of it, which is the part I don't think anyone's nailed down yet.
Original Article

Similar Articles

What Is a Harness?

Hacker News Top

The article explains the concept of AI agent harnesses by comparing them to climbing harnesses, detailing components like system prompts and tools that enable AI models to function as agents.

Own the Loop: A Field Guide to Agent Harnesses (5 minute read)

TLDR AI

As AI coding models become commoditized, the agent harness—the control loop managing tools and workflows—emerges as the key differentiator. This guide maps the field of harnesses, weighing vendor-native performance against the portability of model-agnostic workflows.