# self-improving-agent

Teaches an agent to diagnose friction, update project guardrails in AGENTS.md, and turn repeated multi-step workflows into standalone skills.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 513 installs · ★ 3
- Author: Grail-Computer
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Grail-Computer/Self-Improving-Agent/tree/HEAD/skills/self-improving-agent/SKILL.md
- Updated: 2026-02-14
- HTML: https://affpapa.org/en/nevibecode/skills/grail-computer-self-improving-agent

## What it does

The skill initiates a review routine whenever the model finishes a major chore or receives corrections from a developer. It checks whether the agent struggled to find files, then refreshes the codebase map inside `AGENTS.md`. Discovered quirks, broken patterns, or style adjustments land directly into guardrails and repository norms.

Repeated multi-step jobs become distinct assets. If a procedure has predictable outputs, the agent drafts a new playbook under `skills/<skill-name>/SKILL.md` and appends it to the project index. Deterministic validation scripts can live right alongside the instructions. Workflows stay scoped to the current repository until their utility spans across multiple projects.

Once `AGENTS.md` stretches beyond 200 lines, the agent must trim stale notes or relocate detailed sequences into standalone skills. Vague suggestions like writing clean code are prohibited. Only project-specific constraints belong in the file.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/self-improving-agent/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/self-improving-agent/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/self-improving-agent/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/self-improving-agent/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Grail-Computer/Self-Improving-Agent self-improving-agent
```

2. **Manually: put the files in place**
- File: `.github/skills/self-improving-agent/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Grail-Computer/Self-Improving-Agent --path skills/self-improving-agent
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/self-improving-agent/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Grail-Computer/Self-Improving-Agent --skill self-improving-agent -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Grail-Computer/Self-Improving-Agent/tree/HEAD/skills/self-improving-agent/SKILL.md

## When to use it
- record developer feedback and constraints directly into `AGENTS.md`
- turn repetitive development procedures into new modular skills
- refresh outdated directory maps and entry points in project documentation
- prune bloated memory files when documentation exceeds size limits

## Example prompts
- We just finished this refactor. Run self-improving-agent to reflect on the session and update AGENTS.md.
- Extract the migration procedure we just ran into a reusable skill.
- Note my correction about using pnpm instead of npm in the guardrails section.

## Similar
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [ask-matt](https://affpapa.org/en/nevibecode/skills/ask-matt.md) — skill · 766587 installs
- [to-tickets](https://affpapa.org/en/nevibecode/skills/to-tickets.md) — skill · 711230 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [caveman-review](https://affpapa.org/en/nevibecode/skills/caveman-review.md) — skill · 411800 installs
- [caveman-compress](https://affpapa.org/en/nevibecode/skills/caveman-compress.md) — skill · 411500 installs

## Other versions with the same name
- [self-improving-agent · alirezarezvani](https://affpapa.org/en/nevibecode/skills/self-improving-agent.md) — 1078 installs
- [self-improving-agent · zhaono1](https://affpapa.org/en/nevibecode/skills/zhaono1-self-improving-agent.md) — 35100 installs
- [self-improving-agent · pskoett](https://affpapa.org/en/nevibecode/skills/pskoett-self-improving-agent.md) — 353 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md