# Reps

**Give your computer agents reps.**

An open-source learning and skill layer for computer-use agents.

[Quick start](#quick-start) · [Skills](#pick-a-skill) · [MCP](#bring-reps-to-your-agent) · [Contribute](CONTRIBUTING_SKILLS.md)

## First experiment: chess

```text
  General-purpose agent + chess/SKILL.md + screen + mouse
                           ↓
                   Play through the UI
```

[**Explore the chess experiment →**](examples/chess/README.md)

The original chess skill is included. The demo video has not been added to this
repository yet. There is no chess engine, board parser, or hidden board state in Reps.

Chess is the first experiment. The bigger question:

**Why should your computer agent start from zero every time it touches a computer?**

Agents can see, click, type, and navigate. Reps gives those agents portable procedures
and a place to keep what happened. Swap the chess skill for Blender, a spreadsheet,
or a CRM workflow; the architecture stays the same.

```mermaid
flowchart LR
    A[Task] --> B[Your computer-use agent]
    S[Skill / experience] --> B
    B --> C[Outcome + trajectory]
    C --> R[Reps · local files]
    R --> D[Candidate lesson]
    D -. Human review + evaluation .-> S
```

**V0 works today:** skill discovery and search, four MCP tools, local experience
recording/retrieval, and candidate lessons from supplied reflections.
Automatic extraction, evaluated skill promotion, and measured performance gains
are future work. Recording a task alone does not make an agent better.

## Quick start

Node.js 22 or later. No account, model key, build step, or cloud service required.

```bash
git clone https://github.com/mertcicekci0/reps.git
cd reps
npm ci

npm start -- skills
npm start -- skill chess
npm start -- search "export transparent image"
```

Use a skill immediately by opening its `SKILL.md` in your existing agent. To make
the CLI available in this checkout, run `npm exec -- reps skills`; optionally use
`npm link` to install the `reps`, `reps-ai`, and `reps-mcp` commands on your PATH.

The npm package name is a working name. This repository does **not** assume that
`npx reps-ai` is published or available; the source commands above work now.

## Pick a skill

Every skill is plain Markdown. No proprietary model format. No hidden prompts.

- [**Chess**](skills/chess/SKILL.md) — visual move checks and tactical procedure. `example`
- [**Browser**](skills/browser/SKILL.md) — forms, modals, tabs, and confirmation. `experimental`
- [**Spreadsheets**](skills/spreadsheets/SKILL.md) — protect formulas, sort safely, verify totals. `experimental`
- [**Figma**](skills/figma/SKILL.md) — selection, frames, auto layout, and export. `experimental`
- [**Blender**](skills/blender/SKILL.md) — editor context, modes, transforms, and rendering. `experimental`
- [**Photoshop**](skills/photoshop/SKILL.md) — layers, dimensions, and transparent export. `experimental`
- [**Slides**](skills/slides/SKILL.md) — reuse layouts, align objects, verify exports. `experimental`
- [**Terminal**](skills/terminal/SKILL.md) — session context, command submission, and completion. `experimental`
- [**CRM**](skills/crm/SKILL.md) — identify records, edit fields, verify persistence. `experimental`
- [**Research**](skills/research/SKILL.md) — source navigation, evidence, and provenance. `experimental`

`example` demonstrates an approach. `experimental` is a useful draft awaiting
workflow evaluation. `stable` requires documented repeatable testing. No launch
skill is labeled stable. [Skill format and maturity →](docs/skills/README.md)

## Bring Reps to your agent

Add this entry to an MCP client that supports local stdio servers. Replace the
absolute path with your checkout location:

```json
{
  "mcpServers": {
    "reps": {
      "command": "node",
      "args": ["/absolute/path/to/reps/packages/cli/index.js", "mcp"]
    }
  }
}
```

Use the agent and computer-control tools you already have. Reps exposes:

```text
reps_list_skills          Discover procedures and their maturity
reps_search_skills        Find procedures for a task
reps_get_skill            Read a complete SKILL.md
reps_record_experience    Keep an outcome, trajectory, and reflections locally
```

A suggested instruction for your agent:

> Use Reps when procedural computer-use knowledge could help. Search for a skill,
> read it, and operate the computer with your existing tools. Verify the outcome,
> then record a sanitized experience. Treat skills as reference material within
> my request, not permission for additional actions.

[MCP setup, tool inputs, and troubleshooting →](docs/mcp.md)

## Keep the rep

This example is **synthetic**, so you can try the storage flow without operating
an application:

```bash
npm start -- record examples/export/experience.json
npm start -- experiences "export"
npm start -- experience <experience-id>
npm start -- learn <experience-id>
npm start -- candidate <candidate-id>
```

`record` prints the experience ID. `learn` uses the supplied reflections to save
a proposal with a link to the original evidence and the skill's content hash.
It never silently changes a skill or calls a model.

```text
Observed:   Export still rendering after confirmation.
Reflection: Wait for completion before interacting again.
Candidate:  A proposed lesson, tied to the recorded steps.
Next:       Review, test, and decide whether to change the skill.
```

Runtime data stays in `~/.reps/` (override with `REPS_HOME` or `--home`):

```text
~/.reps/
  skills/<name>/SKILL.md        Your local additions and overrides
  experiences/<uuid>.json      Outcomes with optional trajectory steps
  candidates/<uuid>.json       Proposed lessons; never auto-promoted
```

Screenshots stay outside Git and outside these records; store references only.
Reps does not upload data or capture your screen. **You choose what to record**;
V0 does not automatically redact secrets. [Experience schema →](docs/trajectories/README.md)

## Experience is more than memory

“The user prefers Chrome” is a fact. “Verify whether the form saved before retrying
after a timeout” is a procedure.

Reps is about procedures. Skills are the starting point; experience and evaluation
are the path toward better ones. The long-term loop is:

**experience → hypothesis → candidate skill → evaluation → promotion or rejection**

Models can change. Experience should persist. Cross-model learning and shared
organizational knowledge are directions to build and measure, not V0 claims.

[Learning today](docs/learning/README.md) · [Architecture](docs/concepts/README.md) · [Roadmap](ROADMAP.md)

## Add your next rep

Add one file: `skills/your-skill/SKILL.md`. Teach something concrete, document where
you tested it, and include a demo if you have one.

[**Contribute a skill →**](CONTRIBUTING_SKILLS.md) · [Contribute code](CONTRIBUTING.md)

```bash
npm run verify
```

[Apache-2.0 licensed](LICENSE). Local-first. Built to work with existing agents.