Can 3 Files Solve AI’s Agent Portability Problem? GitAgent Thinks So

Every major AI framework has its own way of defining agents. Claude Code uses CLAUDE.md. OpenAI’s Codex reads AGENTS.md. CrewAI has its YAML configs. Google ADK does its own thing. If you’ve built an agent for one platform and wanted to move it to another, you already know the answer: start over.

GitAgent is a new open standard that proposes a different approach — define your AI agent as files in a Git repo, and export it anywhere. Three files. Any framework. Version-controlled from day one.

The project surfaced on Hacker News as a Show HN post this week, pulling in 109 points and sparking a genuinely interesting debate about whether the AI ecosystem needs yet another standard, or whether this is the one that could actually stick.

The Three-File Spec

GitAgent boils an AI agent definition down to three core files:

agent.yaml is the manifest. It declares the agent’s name, version, model preferences, available skills, tools, and compliance requirements. This is the only file with strict schema validation — everything else is deliberately flexible.

SOUL.md captures the agent’s identity. Think of it as the personality layer: communication style, values, decision-making principles, guardrails. It’s a markdown file, readable by humans and machines alike.

SKILL.md defines what the agent can actually do. Each skill lives in a skills/ directory, paired with an executable script. A code review skill, for example, would have a review.sh alongside its SKILL.md definition.

Drop these three files into any Git repo, and according to the spec, that repo is the agent. Everything that makes Git useful — branching, diffing, pull requests, merge reviews — now applies to your agent’s configuration, personality, and capabilities.

The project currently sits at 248 GitHub stars with 20 forks, MIT licensed, and actively maintained with 26 commits on main.

Why Git? Because the Infrastructure Already Exists

The clever bit isn’t the file format — it’s the decision to treat Git as the runtime backbone.

Version control is the obvious win. When your agent’s behavior changes, you get a clean diff showing exactly what shifted. You can tag releases, roll back to previous versions, and use branches to test experimental personality tweaks without touching production. Teams can submit skill additions through pull requests, with the same review process they already use for code.

But GitAgent pushes this further with a few patterns that caught the community’s attention. There’s a concept of “branch-based environment promotion” — your agent starts on a dev branch, gets promoted to staging, then production, just like application code. There’s a memory/runtime/ directory for live agent state. And there’s a human-in-the-loop learning pattern where new skills get proposed as PRs, reviewed by humans, and merged into the agent’s capability set.

For teams already drowning in agentic engineering patterns, this is an appealing pitch: stop building custom infrastructure for agent management and use the tooling you already have.

The Compliance Angle Nobody Expected

Here’s where GitAgent gets unexpectedly specific. The spec includes first-class support for regulatory compliance — FINRA Rule 3110 (supervision), Rule 4511 (recordkeeping), Federal Reserve SR 11-7 (model risk management), and SEC regulations.

There’s a DUTIES.md file for segregation of duties, with role-based permissions and conflict matrices that prevent a single agent from controlling both sides of a critical process. Every change is tracked in Git’s immutable commit history, which doubles as an audit trail.

This is a sharp move. Most open-source agent tools are built by developers for developers — compliance is an afterthought, if it’s thought about at all. GitAgent is explicitly targeting regulated industries (finance, healthcare, government) where “we used Git commits as our audit log” might actually satisfy an auditor.

Whether this is genuine product-market fit or premature optimization for a spec with 248 stars is an open question. But if you work in fintech and you’re evaluating agent frameworks, this is worth knowing about.

Framework Adapters: Where the Rubber Meets the Road

GitAgent ships with export adapters for Claude Code, OpenAI Agents SDK, CrewAI, Lyzr Studio, Google ADK, LangChain, GitHub Actions, and a generic system-prompt format. The CLI makes this straightforward:

npm install -g gitagent
gitagent init --template standard
gitagent validate
gitagent export --format openai

The promise is write-once, run-anywhere for agent definitions. But Hacker News commenters were quick to poke at the abstraction layer. One developer raised a legitimate concern: “If I define a SKILL.md that relies on tool-use patterns CrewAI supports but Claude Code doesn’t… does the export silently drop it?”

This is the fundamental tension in any portability standard. The more capable frameworks can do things that simpler ones can’t, and no amount of YAML abstraction will bridge that gap completely. GitAgent’s answer seems to be adapter-level flexibility — each adapter can map the spec to its target framework’s capabilities — but the documentation doesn’t yet address how gracefully degradation works in practice.

How GitAgent Stacks Up Against CLAUDE.md and AGENTS.md

The AI agent configuration space is getting crowded. Here’s how the main approaches compare:

AGENTS.md started at Sourcegraph and now has backing from OpenAI and Google. It’s a single markdown file that gives coding agents project-specific context — repository conventions, build instructions, testing preferences. Lightweight and broadly supported, but limited in scope. It tells an agent about your project, not how to be an agent.

CLAUDE.md is Anthropic’s native configuration for Claude Code. It’s more powerful — hierarchical loading, skills integration, MCP server config — but locked to Claude’s ecosystem. Great if you’re all-in on Claude, limiting if you’re not.

GitAgent is the most ambitious of the three. It doesn’t just configure an existing agent; it defines the entire agent as a portable, versionable entity. The trade-off is complexity: three files plus a skills directory versus a single markdown file.

The practical question is whether full agent portability matters to most teams. If you’re using Claude Code and happy with it, CLAUDE.md gives you everything you need. If you’re building multi-framework agent systems, or you work in a regulated industry where agent definitions need formal version control and audit trails, GitAgent addresses problems the other approaches don’t even acknowledge.

Projects like Memento have explored the intersection of Git and AI agents from a different angle — recording coding sessions into Git history. GitAgent takes the inverse approach: using Git as the source of truth for what the agent is, not what it did.

Community Reception: Excitement With Sharp Edges

The Hacker News thread (109 points, 17 comments) reveals a community that’s intrigued but not uncritical.

On the positive side, developers appreciate the clean separation of concerns across the three files. Several mentioned building similar solutions independently, which suggests GitAgent is scratching a real itch. The Git-native approach resonates with teams already comfortable with infrastructure-as-code patterns.

The criticisms are worth taking seriously, though. Security-focused commenters flagged the .env/.gitignore approach to secrets management as “hope-based security” — plaintext secrets on disk, protected only by a gitignore rule that one misconfigured CI pipeline could bypass. The project defenders pointed to the dotenv convention being standard since 2012, which is true but doesn’t make it more secure.

Others questioned the naming. “SOUL.md” drew particular flak — some found it overblown for what amounts to a system prompt config file. Whether this is a real problem or just aesthetic preference probably depends on your tolerance for branding in technical specifications.

The most substantive critique came from a search service operator who argued that the bottleneck in the agent ecosystem isn’t defining agents — it’s discovering them. “The portability win only kicks in once there’s a discovery layer,” they wrote. Fair point. A perfectly portable agent definition doesn’t help much if nobody can find the agent they need.

What to Watch For

GitAgent is still early — 248 stars, 26 commits, no major corporate backing yet. But the timing is interesting. The agent ecosystem is fragmenting fast, with every major AI company pushing its own framework and configuration format. The teams building agents today are making lock-in decisions they may not realize, and a portable standard — even an imperfect one — has obvious appeal.

The questions that will determine GitAgent’s trajectory: Can the adapter layer keep up as frameworks evolve? Will any major platform officially support the spec? And can a three-file standard remain simple enough to be approachable while handling the edge cases that production deployments demand?

If you’re building agent infrastructure or evaluating how to manage agents at scale, GitAgent is worth adding to your radar — not because it’s the definitive answer, but because the questions it’s asking are the right ones.

FAQ

Is GitAgent free and open source?
Yes. GitAgent is MIT licensed and fully open source. The CLI, spec, and all adapters are free to use. There’s no paid tier or commercial version at this time.

What frameworks does GitAgent support?
GitAgent currently has export adapters for Claude Code, OpenAI Agents SDK, CrewAI, Lyzr Studio, Google ADK, LangChain, GitHub Actions, and a generic system-prompt format. New adapters can be contributed by the community.

How does GitAgent compare to AGENTS.md or CLAUDE.md?
AGENTS.md and CLAUDE.md configure how an existing AI agent behaves in your project. GitAgent goes further — it defines the agent itself as a portable, versionable entity with identity, skills, and compliance built in. They can coexist: you might use GitAgent to define your agent and CLAUDE.md for Claude-specific optimizations.

Can GitAgent handle regulatory compliance requirements?
Yes. The spec includes built-in support for FINRA, SEC, and Federal Reserve compliance requirements, with segregation of duties enforcement, role-based permissions, and Git-based audit trails. This is one of its most distinctive features compared to alternatives.

Do I need to rewrite my existing agents to use GitAgent?
No. GitAgent provides templates (minimal, standard, and full) to get started. For existing agents, you can incrementally adopt the spec by adding the three core files to your repo and using the CLI to validate and export. The minimal template requires only agent.yaml and SOUL.md to get started.

Top AI Product