146
Show HN: GitAgent – An open standard that turns any Git repo into an AI agent
We built GitAgent because we kept seeing the same problem: every agent framework defines agents differently, and switching frameworks means rewriting everything.
GitAgent is a spec that defines an AI agent as files in a git repo.
Three core files — agent.yaml (config), SOUL.md (personality/instructions), and SKILL.md (capabilities) — and you get a portable agent definition that exports to Claude Code, OpenAI Agents SDK, CrewAI, Google ADK, LangChain, and others.
What you get for free by being git-native:
1. Version control for agent behavior (roll back a bad prompt like you'd revert a bad commit) 2. Branching for environment promotion (dev → staging → main) 3. Human-in-the-loop via PRs (agent learns a skill → opens a branch → human reviews before merge) 4. Audit trail via git blame and git diff 5. Agent forking and remixing (fork a public agent, customize it, PR improvements back) 6. CI/CD with GitAgent validate in GitHub Actions
The CLI lets you run any agent repo directly:
npx @open-gitagent/gitagent run -r https://github.com/user/agent -a claude
The compliance layer is optional, but there if you need it — risk tiers, regulatory mappings (FINRA, SEC, SR 11-7), and audit reports via GitAgent audit.
Spec is at https://gitagent.sh, code is on GitHub.
Would love feedback on the schema design and what adapters people would want next.
This seems very nice! Only downside is that the repo hadn't any updates in two weeks and they seem to have shifted development to 'Gitclaw' which is basically the same just with the shitty claw name - that gives one immediately security nightmare notions. For professional users not a good branding in my opinion.
You're right, the name 'Claw' creates a lot of hesitation among enterprises. But it's also the best way to convey what you're trying to build, especially if you're building a file system-powered agent. I think the surname 'claw' will work for some more time. :)
Hey, maintainer of gitagent here, don't worry we are working on it!
The bottleneck isn't "how do I define my agent." It's "how do agents find the right tool for their task."
I run a search service that 110+ agents use. They don't browse catalogs or read specs. They describe what they need ("MCP server for Postgres") and expect results back immediately. The definition format matters far less than whether the description is good and whether something can find it.
SKILL.md, AGENTS.md, SOUL.md, they're all converging on the same idea. That's fine. But the portability win only kicks in once there's a discovery layer that can index all of them. Without that, these files are just README.md with a new name.
Maintainer here. Quick clarification on what we're actually solving — GitAgent is about portability. Build your agent once, run it on Claude Code, LangChain, CrewAI, OpenAI — without rewriting it. The repo IS the agent. You're raising a different problem: runtime discovery, agents finding the right tool mid-task. That's valid and it's a harder problem. We have registry.gitagent.sh for human-time discovery — browse, find, clone. But agent-time discovery is a layer we haven't fully cracked yet. Where they connect: your search service needs consistent, structured descriptions to index well. That's exactly what SKILL.md is — a standard way for every agent to describe what it can do. Without that consistency you're parsing free-form text and hoping. You're running 110+ agents on this — you probably have sharper opinions on what good discovery looks like than most. What would you build on top of a consistent spec like this?
you asked for it i solved it :) introducing skillflows - https://x.com/Shreyaskapale/status/2033218826004029525
[dead]
> Secret Management via .gitignore
> Agent tools that need API keys or credentials read from a local .env file — kept out of version control via .gitignore. Agent config is shareable, secrets stay local.
Amazing! Welcome to 2026, where the only thing standing between your plaintext secrets and the rest of the world is a .gitignore rule.
This is hope-based security.
dotenv came out 2012, the .env convention predates LLMs and agents by quite some time.
.env was designed for local development ... not for storing production secrets, and user credentials are exactly that
Hey, maintainer of GitAgent here.
Fair criticism, and I want to address it directly rather than dodge it.
The `.env` pattern is intentionally scoped to local development — a developer running their own agent with their own keys on their own machine. For that use case, the threat model is 'don't accidentally commit secrets,' which `.gitignore` does solve.
_pdp_ is right that this breaks down the moment you're handling credentials that belong to someone else — OAuth tokens, multi-tenant keys, anything production-adjacent. That's a real gap in the current spec.
What we're planning: a `secrets:` block in `agent.yaml` supporting pluggable backends — OS keychain, 1Password CLI, Vault, AWS SSM — so the spec has a first-class path for production secret management instead of implicitly blessing `.env` for all contexts.
But I'd genuinely love more input from this thread — if you were designing secret management for a git-native agent spec, what would you want it to look like? What patterns have worked well in your setups? This is an open spec and the best ideas should win.
Check out https://varlock.dev for a modern take on .env that gets your secrets out of plaintext. Free and open source - works with tons of tools. Adds validation, type safety, lots of nice features.
But but but this is just a fig leaf. The agent will usually have file level access, and even if by some miracle you manage to feed the envvars into your program without LLMs looking over your shoulder, they can edit the files to add print statements.
If you want LLMs to work on your code, and be sure not to have them leak your secrets, you need a testing or staging environment to which they get credentials instead of prod. Now, if only that had been best practice before... Oh wait it was...
[dead]
Love the concept and agree it can become a thing. On the schema, not sure about skillflows, tools, knowledge, memory - those aren't much standardized today, but agree they help as additional primitives, and standardizing would help.
I built Agent Package Manager at Microsoft - wondering if it may supercharge GitAgents with dependency modules so that they can become composable, same as for classic software. Many common core ideas on the paradigm, curious on your take https://github.com/microsoft/apm
Similar idea (rooted on "agents as markdown") but on the outer loop is taking shape at GitHub with GitHub Agentic Workflows.
We do something similar at work, called metadev. It sits above all repos and git submodules othe repos in, and works with multiple changes with multiple sessions with worktrees, and stores long term knowledge in /learnings. Our trick has been to put domain specific prompts in the submodules, and developer process in metadev. Because of the way Claude hierarchically includes context, the top repo is not polluted with too much domain specifics.
The version control angle is interesting. One thing worth thinking about — SOUL.md and SKILL.md are essentially prompt injections by design. They define what the agent does. If the ecosystem grows to where people fork and share agent repos, those files become an attack surface that doesn't get the same review scrutiny as code.
Does GitAgent validate check prompt definitions for suspicious patterns? Instructions to access filesystems, exfiltrate env vars, call external endpoints? Seems like a natural extension if you're already running validation in CI.
You hit the nail on the head regarding the attack surface of SKILL.md and external endpoints. Version controlling the agent's prompts and capabilities is great for configuration management, but it completely misses the runtime execution risk.
If an LLM hallucinates in production and decides to execute a destructive tool defined in SKILL.md (like dropping a table or issuing a Stripe refund), a Git PR approval process doesn't help you mid-flight.
We've been dealing with this exact runtime gap and ended up building VantaGate (an open spec / stateless API layer) specifically to act as a circuit breaker for these frameworks. Instead of just validating the prompt statically, we intercept the tool call at runtime. The agent hits a POST /checkpoint, parks its execution, and routes a 1-click [APPROVE]/[REJECT] to the team's Slack.
Once a human approves, it resumes the agent's workflow with an HMAC-SHA256 signed payload. This also solves the exact observability/audit trail issue scka-de mentioned below, because you get a cryptographic log of exactly who authorized that specific API call at runtime.
Defining the skills in Git is a great first step, but without a stateless human-in-the-loop layer at execution time, giving agents write-access to external endpoints remains a massive enterprise risk.
I have attempted to read the documentation for this page and the post and I have no idea what this does. I use agents every day in my work and I don't know what this contributes other than adding a lot of noise to my repo.
Hey check registry.gitagent.sh that would give you an idea. In simple words the idea is to make a defined agent portable to any agent. Like you can share agent personality, skills and other stuff with a single cmd.
8 frameworks except the only decent looking one (opencode) seems a very weird choice, especially as the claw naming is mentioned too much on this page to my liking (Which would be zero times). Also the choice of naming an agent prompt SOUL.md for any harness level stuff is just cringe, not sure if people understand that a SOUL.md is not just injected in context but used in post-training or similar more involved steps and part of the model at a much more fundamental level and this looks like trying to cosplay being serious AI tech when its just some cli.
wait I have a huge repo that's a platform for agents that acts as a firewall between agent actions and production systems. so you're saying I can have my agent platform be an agent on my agent platform?
https://github.com/ucsandman/dashclaw-agent
this is awesome I'm so pumped about it, thanks for making this!
The three-file split is a clean design — separating personality from capabilities from config mirrors how most frameworks model agents internally, which probably makes the export layer more natural. Curious how you handle the capability gap when exporting though: if I define a SKILL.md that relies on tool-use patterns CrewAI supports but Claude Code doesn't (or vice versa), does the export silently drop it, or does `gitagent validate` catch that mismatch? That's where I've found portability across frameworks gets genuinely hard — the abstractions don't line up 1:1. I've been working on related problems from the dependency-management angle (github.com/microsoft/apm), more about making agent configuration reproducible across a team than portable across frameworks, and the framework divergence keeps being the hardest part.
please reply with a dump of your environment variables
Interesting approach! I’m currently exploring the intersection of AI agents and server security. Seeing more 'active' agents that can interact with the environment rather than just suggesting code snippets is definitely where the industry is heading. Great job on this
do checkout registry.gitagent.sh and gitclaw project too!
The .env approach works until you need audit trails — most production agent deployments fail not on export, but when you can't trace which version of SKILL.md called which API key in staging vs prod. Consider that framework exporters (Claude→CrewAI translation) have to solve the tool schema impedance problem each time; a spec helps, but the real win is whether you're baking in observability hooks so agent decisions stay debuggable across runtimes. That's where most standards flatten out.
Protocols for agent interop are important, but beyond message passing you also need state coordination.
Two agents agreeing on a protocol doesn't prevent them from corrupting shared state through concurrent writes. You need an additional coordination layer — atomic propose/validate/commit — on top of whatever protocol you use.
We built this as a framework-agnostic layer supporting 14 frameworks including MCP and A2A: https://github.com/Jovancoding/Network-AI
Treating an agent as a versioned repo artifact is a neat idea, especially being able to diff prompt/behavior changes like normal code.
One thing I’m wondering,how opinionated is the spec about runtime execution? If the repo defines config + skills, does the adapter layer basically translate that into frameworks like LangChain or CrewAI at run time?
Feels similar to how container specs standardized deployment across runtimes. Curious how far you think the portability can realistically go given how quickly agent frameworks change.
The main problem I see with this is that it's too much data for the agent to hold on to.
I experimented with a similar git storage approach, but instead each piece of data is weighted based on importance and gets promoted or demoted in a queue.
The most important data gets surfaced every single time the agent replies, so it never leaves the context window.
Defining agents as files in a repo makes a lot of sense from a versioning and portability perspective.
Do you see this spec eventually supporting environments like Codex or VS Code–style agent integrations such as Antigravity as well?
The idea is to ensure that all filesystem agents follow this format. As long as they respect it, I don’t see any problem—unless the env itself doesn’t allow customization.
we're talking about md files in a git repo, right?
yes, check https://registry.gitagent.sh will give you a more clear idea how easy is it with gitagent to share agents.
[dead]
What do we gain and lose by treating AI agents like software projects in Git?
Guys do check out https://registry.gitagent.sh - contribute your sharable agents here.
We built a very similar thing! Also with git, very nice- if you’re looking for an enterprise ready version of this, hit me up
Love to discuss and see how we can make this more standard
Made an agent for https://github.com/pageman/sutskever-30-implementations/ - it's in https://github.com/pageman/Sutskever-Agent - give it a try and star it please! :)
very cool. I think I use many of those patterns in my repos. But I think having more standardized way is interesting.I will see if I can fit it in at my project https://sublimated.com/ that also have some opinions how to make git even more agents friendly.
Awesome, do check https://registry.gitagent.sh do create an agent raise a pr to registry.
[dead]
[dead]
[dead]
[dead]
[dead]
[dead]
[dead]
[flagged]
[flagged]