GitAgent proposes an open standard to define AI agents using files within a Git repository. This approach allows for version control, branching, PR-driven human-in-the-loop workflows, and auditing of agent behavior. It aims to solve the problem of agent definition fragmentation across different AI frameworks by providing a portable specification and a CLI for execution and validation.
A starter prompt for Claude Code, what you'll need, and how to reach them.
You are an expert software engineer. I need to build a proof-of-concept for GitAgent, an open standard for defining AI agents in Git repositories. The core idea is to define agents using three files: `agent.yaml` (config), `SOUL.md` (personality/instructions), and `SKILL.md` (capabilities). This POC should demonstrate version control benefits and execution. Here's the plan: 1. **Project Setup**: Create a Next.js 16 App Router project (using React 19, Tailwind v4, and AI SDK v6 with Gemini). This will be a small web UI + API backend. 2. **GitAgent Core Files**: Implement a simple file parser in Node.js/TypeScript that can read and interpret `agent.yaml`, `SOUL.md`, and `SKILL.md` from a local directory representing a Git repo. 3. **Agent Definition**: Define a very basic 'hello world' agent using these three files (e.g., an agent that takes a user query and responds with a greeting based on its SOUL.md and can perform a simple 'echo' skill). 4. **Local 'Repo'**: Simulate a Git repository by creating a local directory structure with these agent files. Demonstrate a 'version' by having a `v1` and `v2` directory or branch simulation in a single local dir, showing how changing `SOUL.md` alters behavior. 5. **Execution Logic**: In the Next.js API route, expose an endpoint `/api/run-agent` that takes a `repoPath` (local directory) and `agentName` (e.g., 'hello-agent'). This endpoint should load the agent definition, use the AI SDK with Gemini to execute a prompt incorporating `SOUL.md` and `SKILL.md`, and return the agent's response. 6. **Web UI**: Create a simple React front-end page (`/`) with a text input for a query and a button to 'Run Agent'. Display the agent's response. Include a selector for 'agent version' (e.g., `v1` or `v2` of the local agent definition). 7. **MVP Goal**: The MVP is a working web UI that can run a simple, versioned local GitAgent definition, showing how changes in the `SOUL.md` or `SKILL.md` files (simulating different Git commits/branches) affect the agent's output. Focus on clarity and simplicity over full Git integration at this stage. **Build Gate**: A user can navigate to the web UI, select an 'agent version', input a query, and see a tailored response from the agent that clearly reflects the `SOUL.md` and `SKILL.md` for that version.
The GitAgent audience, primarily developers and AI engineers, are prime candidates for tools like forge-kit for automating their dev loop, mcp-kit for building AI tools, agent-eval-lab for agent testing, and repo-gardener for maintaining their agent repos.
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
Reply in the Hacker News thread to the original poster.
“I've built a prototype demonstrating your GitAgent concept with versioned agent definitions and execution via a simple web UI. Happy to share a demo and discuss how to integrate actual Git functionality and further adapters.”
Open the original ↗