# example-skill

Adopt this skill: https://proskills.md/skills/other/open-gitagent-gitagent-skills-example-skill

Page: https://proskills.md/skills/other/open-gitagent-gitagent-skills-example-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/example-skill/SKILL.md
size: 343
upstream: https://github.com/open-gitagent/gitagent/blob/main/skills/example-skill/SKILL.md

````text
---
name: example-skill
description: Example skill that demonstrates the gitagent skills system. Use this to test skill loading and script execution.
---

# Example Skill

This is a demo skill showing how gitagent skills work.

## Usage

Run the hello script:
```bash
bash scripts/hello.sh
```

Scripts are relative to this skill's directory.
````

## File: README.md
upstream: https://github.com/open-gitagent/gitagent/blob/main/README.md

````text
<p align="center">
  <img src="./gitagent-logo.png" alt="gitagent" width="180" />
</p>

<h1 align="center">gitagent</h1>

<p align="center">
  <strong>The agent that lives in a git repository.</strong><br/>
  One static binary. Its identity, rules, memory, skills, tools and schedules are files you commit.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Terminal--Bench_2.1-93.03%25_%C2%B10.8-e05a44?style=flat-square" alt="Terminal-Bench 2.1: 93.03% ±0.8" />
  <img src="https://img.shields.io/badge/version-3.0.0-2a1f18?style=flat-square" alt="version 3.0.0" />
  <img src="https://img.shields.io/badge/built_with-Rust-2a1f18?style=flat-square" alt="Rust" />
  <img src="https://img.shields.io/github/license/open-gitagent/gitagent?style=flat-square&color=2a1f18" alt="license" />
</p>

<p align="center">
  <a href="#why-gitagent">Why</a> &bull;
  <a href="#install">Install</a> &bull;
  <a href="#use">Use</a> &bull;
  <a href="#cli-options">CLI</a> &bull;
  <a href="#results">Results</a> &bull;
  <a href="#how-gitagent-works">How it works</a> &bull;
  <a href="#architecture">Architecture</a> &bull;
  <a href="#sdks-any-language-over-ipc">SDKs</a> &bull;
  <a href="#troubleshooting">Troubleshooting</a>
</p>

<p align="center">
  <img src="./docs/media/console.gif" alt="A gitagent session in the terminal" width="820" />
</p>

**Terminal-Bench 2.1: 93.03% ±0.8** with Claude Opus 5.5, all 89 tasks, five runs each, code frozen at the published commit; the ± is the run-to-run variation, as on the official leaderboard. The published harnesses on the same benchmark: Terminus 2 with the same model 87.6%, Codex CLI with GPT-6 Astra 87.4%, Claude Code with Claude Fable 5 83.8%, and the highest published entry, Artificial Analysis's own harness with Claude Fable 5.1 at maximum effort, 91.4%. The numbers are under [Results](#results); the reason is under [How gitagent works](#how-gitagent-works).

## Why gitagent

Most agent frameworks treat the agent as code scattered across your application. gitagent flips this: **your agent is a git repository**.

- **`agent.yaml`**: model, tools, runtime settings, compliance
- **`SOUL.md`**: who the agent is
- **`RULES.md`**: what it must never do
- **`memory/`**: what it remembers, committed to git with full history
- **`skills/`**: instructions it can follow on demand
- **`tools/`**: tools declared in YAML, backed by any script
- **`hooks/`**: scripts that check or change every action
- **`schedules/`**, **`workflows/`**, **`agents/`**: when it works on its own, step-by-step procedures, sub-agents it delegates to

Fork an agent. Branch a personality. `git log` its memory. Diff its rules. Review a change to its behaviour like a code change. Every result traces back to a commit.

**gitagent 3** is the Rust rewrite: one static binary with no runtime to install, the harness that scored 93.03% on Terminal-Bench 2.1, a console in your terminal, parallel sub-agents with a live task board, and SDKs for Python, TypeScript and any other language over a simple line protocol. Agents, hooks, schedules and SDK code written for the TypeScript gitagent (1.x and 2.x) run unchanged, and agent folders in the OpenGAP format load too. See [Coming from the TypeScript gitagent](#coming-from-the-typescript-gitagent).

## Install

```sh
curl -fsSL https://raw.githubusercontent.com/open-gitagent/gitagent/main/scripts/install.sh | sh
```

Or with npm, which also gives you the TypeScript SDK:

```sh
npm install -g @open-gitagent/gitagent
```

Either way you get the same binary for your system (Linux x86_64/arm64, macOS arm64/x86_64). The script puts it in `~/.local/bin` (set `INSTALL_DIR` to change that); npm installs the package for your platform, `@open-gitagent/gitagent-<os>-<cpu>`, and a `gitagent` command that runs it. To build from source you need Rust (the version is pinned in `rust-toolchain.toml`):

```sh
cargo build --release            # ./target/release/gitagent
scripts/build-release.sh         # static Linux binaries (needs cargo-zigbuild on macOS)
```

## Use

Set the key for your model provider, then:

```sh
export ANTHROPIC_API_KEY=...

# One task in a folder; prints the agent's summary when done
gitagent -p "fix the failing test" --dir ./project --model anthropic:claude-opus-5-5

# Interactive: type tasks one per line; each continues the same session
gitagent --dir ./project --model anthropic:claude-opus-5-5

# Work in a fresh clone on a new branch, commit when done, push
GITHUB_TOKEN=... gitagent --repo https://github.com/org/app.git -p "fix the failing test" --push
```

In interactive mode, Ctrl-C stops the current task and Ctrl-D or `exit` quits.

### CLI options

`gitagent [OPTIONS] [PROMPT]`. Without a prompt it opens the console in `--dir`.

| Option | What it does |
|---|---|
| `[PROMPT]`, `-p, --prompt <text>` | The task, as plain words; runs it once and exits |
| `--instruction-file <file>` | Read the task from a file |
| `-d, --dir <dir>` | The agent folder to work in (default: the current directory) |
| `-m, --model <provider:model>` | The model; overrides `gitagent.yaml` |
| `-e, --env <name>` | Apply the agent's `config/<name>.yaml` (default: `GITAGENT_ENV`) |
| `--profile <name or path>` | `auto`, a built-in profile, or a profile file |
| `--config <file>` | A `gitagent.yaml` to use; its `prompts/` and `profiles/` override the built-ins |
| `--conversation` | A plain reply ends the run, instead of `task_complete` (always on in the console) |
| `--max-turns <n>` | Stop after this many model calls |
| `--timeout-s <seconds>` | Time limit for the run. Without one, the console has no limit and `-p` runs stop after 30 minutes |
| `--allowed-tools <a,b>`, `--disallowed-tools <a,b>` | Offer only these tools, or never these |
| `--append-system-prompt <text>` | Text added after the system prompt |
| `--workflow <name>`, `--input key=value` | Run one of the agent's workflows instead of a task |
| `-r, --repo <url>` | Work in a clone of the repository on a new branch, and commit the result |
| `--base <branch>`, `--branch <name>`, `--session <name>` | Repo mode: the branch to start from, or an existing branch to resume |
| `--push`, `--pat <token>` | Repo mode: push the branch after committing; the token to use (default: `GITAGENT_GIT_TOKEN`, `GITHUB_TOKEN` or `GIT_TOKEN`) |
| `--out-dir <dir>` | Where the trajectory, counters and logs go (default: `/tmp/gitagent`) |
| `--session-id <id>` | Session id recorded in the trajectory |
| `--events jsonl` | Print every step as a JSON object per line |
| `--output-format text \| stream-json` | Print the summary, or the SDK's messages one per line |
| `--ipc` | Serve the IPC protocol for a client library (see [SDKs](#sdks-any-language-over-ipc)) |
| `--bench` | Benchmark mode: built-in configuration only, no memory, no git commits |
| `--linger` | Keep the shells, and anything running in them, open after the run |
| `-V, --version`, `-h, --help` | Version and help |

Subcommands, each with its own `--help`:

| Command | What it does |
|---|---|
| `gitagent init [dir]` | Create an agent folder: `agent.yaml`, `SOUL.md`, `memory/`, a git repository |
| `gitagent validate [dir] [--compliance]` | Check an agent folder against the format, with file and line for every problem |
| `gitagent install [dir]` | Fetch the agent's `extends` parent and its `dependencies` |
| `gitagent plugin install\|list\|enable\|disable\|remove\|init` | Manage the agent's plugins |
| `gitagent schedule list\|add\|run\|start\|enable\|disable\|remove` | Manage and run the agent's schedules |
| `gitagent learn --from <runs>` | Learn lessons from finished runs |

In the console, `/help` lists the session's commands, and typing `/` shows them as you type.

### Models

`--model provider:model`, or `model:` in `gitagent.yaml`.

| Provider | Example | Key |
|---|---|---|
| Anthropic | `anthropic:claude-opus-5-5` | `ANTHROPIC_API_KEY` |
| OpenAI (Responses API) | `openai:<model>` | `OPENAI_API_KEY` |
| Google Gemini
````
