Reps

Give your computer agents reps.

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

Quick start · Skills · MCP · Contribute

First experiment: chess

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

Explore the chess experiment →

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.

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.

Related MCP server: Skill Shelf

Quick start

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

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 — visual move checks and tactical procedure. example

• Browser — forms, modals, tabs, and confirmation. experimental

• Spreadsheets — protect formulas, sort safely, verify totals. experimental

• Figma — selection, frames, auto layout, and export. experimental

• Blender — editor context, modes, transforms, and rendering. experimental

• Photoshop — layers, dimensions, and transparent export. experimental

• Slides — reuse layouts, align objects, verify exports. experimental

• Terminal — session context, command submission, and completion. experimental

• CRM — identify records, edit fields, verify persistence. experimental

• Research — 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 →

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:

{
  "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:

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 →

Keep the rep

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

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.

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):

~/.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 →

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 · Architecture · Roadmap

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 → · Contribute code

npm run verify

Apache-2.0 licensed. Local-first. Built to work with existing agents.