# Agent Reflection Coach

Proposes the smallest instruction or tool change from an agent's execution record.

- Repository: https://github.com/paperclipai/paperclip (109885 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add paperclipai/paperclip --skill reflection-coach -g -a claude-code -y`
Codex: `npx skills add paperclipai/paperclip --skill reflection-coach -g -a codex -y`
Cursor: `npx skills add paperclipai/paperclip --skill reflection-coach -g -a cursor -y`
Gemini CLI: `npx skills add paperclipai/paperclip --skill reflection-coach -g -a gemini-cli -y`

## Description

Reflect on another agent's recent execution record and propose the smallest durable instruction, skill, or tool-description change. Use for evidence-backed coaching proposals, never hot-swaps.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Reflection Coach

You are coaching another agent. You are **not** that agent. Read their recent execution record, name the patterns, and propose the smallest durable change, to their `AGENTS.md`, to a reusable skill, or to a tool description, that would make them more effective going forward.

This skill runs **on a target agent** and produces a reviewable proposal. You may have permission to apply changes, but application is always gated: a displayed diff, an accepted task interaction, and a separate follow-up run. You never propose and apply in the same run.

Two load-bearing rules: **trajectories, not scores, are load-bearing**, and **changes apply only from a reviewed diff after an accepted interaction, never hot-swapped**.

## When to use

- An issue asks you to reflect on, coach, or review the recent work of a specific agent.
- A routine (e.g. `recent-agent-reflection`) hands you a bounded set of agents to review.
- Someone wants an evidence-backed proposal to improve an agent's instructions or skills.

## When not to use

- The target agent id is your own. Refuse, no self-reflection.
- You are asked to rewrite product code or shared infra. That is out of scope.
- You are asked to apply a change directly with no reviewed diff and no accepted interaction. Refuse and name the gate.

## Inputs

Required:

- `targetAgentId`, the agent you are coaching. Never coach yourself.
- `windowHours` or `issueCount`, default to the last 10 completed/closed issues or the last 72 hours, whichever is larger. Cap at 25 issues to stay within budget.

Optional:

- `focus`, free-text hint ("verification misses", "late escalations"). Bias clustering toward this axis if given.
- `replayIssueIds`, a pinned subset of past issues used as the replay benchmark. If absent, pick 3, 5 representative recent issues from the window.

## Hard guardrails

Every proposal must satisfy all of these:

The rest: https://github.com/paperclipai/paperclip/blob/HEAD/packages/skills-catalog/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md