Guide · Agent skill
How to use the Reflection Coach agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Reflection Coach is an agent skill that lets one AI agent review another agent's recent work on the Paperclip platform and propose a small, evidence-based change to its instructions, a reusable skill, or a tool description. It is for teams running several agents on Paperclip who want periodic tuning without silent prompt edits. After this guide you will know what the skill does, how to install it, how to trigger it, what it needs, and which safety gates apply.
Reflection Coachpaperclipai/paperclip · MIT Download the skill Quick start
- 1Download and unzip. Download the reflection-coach ZIP from this page and unzip it so the reflection-coach folder containing SKILL.md is in ~/.claude/skills/ or a project's .claude/skills/.
- 2Or upload in the Claude apps. In the Claude apps, open Settings, go to Capabilities, choose Skills and upload the skill.
- 3Confirm your Paperclip environment. Make sure PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID and PAPERCLIP_AGENT_ID are set for the agent that will act as coach.
- 4Ask for a reflection. Request a review of a specific agent by its id, optionally with a focus hint or a routine-style bounded set.
- 5Review the proposal. Read each cluster's evidence quotes and the diff, and check the replay issues listed.
- 6Accept through an interaction. Accept or reject the proposal through an accepted interaction, then let a separate follow-up run apply any approved change.
What the Reflection Coach skill makes the agent do
The skill turns an agent into a coach for a different agent. The coach is told it is not the target and reads that agent's recent execution record: issues, comments, reviewer feedback, status transitions, blocker reasons, approval outcomes, human corrections and PR-link comments.
It groups repeated failures into named clusters such as verifier-miss, avoidable-rework, instruction-miss, late-escalation and tool-misuse. A cluster only survives if it has at least two pieces of evidence. The output is a proposal document, not a change to the agent.
- Named failure clusters from a fixed taxonomy, each with issue and comment references.
- A minimal proposed diff to the target's AGENTS.md, a full draft SKILL.md, or a tool description of 500 characters or fewer.
- A list of past issues the change must still resolve, used as a replay benchmark.
Install the Reflection Coach skill
Download the ZIP for the reflection-coach skill from this page. The package contains a single file, SKILL.md. Unzip it so the folder named reflection-coach sits in one of the skills locations below.
For a personal setup, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/reflection-coach/
- Project install: .claude/skills/reflection-coach/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
You do not need a special command. Ask in plain language for a review of a specific agent. The skill's triggers in the source are an issue asking the agent to reflect on, coach or review another agent's recent work, a routine that hands over a bounded set of agents, or a request for an evidence-backed proposal to improve an agent's instructions or skills.
Always name the target agent. The skill needs a target agent id, and it refuses if the target is the agent running it.
- Reflect on the recent work of agent <targetAgentId> and propose instruction changes.
- Coach the agent with focus on verification misses.
- Review the last 10 closed issues for agent <targetAgentId> and draft a skill update.
Understand the inputs and the review gate
The required input is targetAgentId. You can also give windowHours or issueCount; by default the skill uses the last 10 completed or closed issues or the last 72 hours, whichever is larger, capped at 25 issues. An optional focus hint biases clustering, and replayIssueIds pins the benchmark issues.
Nothing is applied in the same run that proposes it. The coach produces a diff and an assignment plan, a human or the board accepts it through an interaction, and a separate follow-up run applies it.
- targetAgentId: required, never the coach itself.
- focus: optional free text such as late escalations.
- replayIssueIds: optional pinned benchmark; otherwise 3 to 5 representative issues are chosen.
Read the proposal before accepting it
Each cluster in the proposal lists a one-sentence pattern, a root cause hypothesis, at least two evidence quotes with issue links, the target surface, the diff, and the replay issues expected to still pass. Read the evidence first. A rule with weak or misquoted evidence should be rejected.
Size caps are enforced by the skill: skills at 15KB or less, tool descriptions at 500 characters or less, and AGENTS.md growing by no more than 20 percent per proposal.
- Check every quote against the linked issue.
- Confirm the replay issues would still succeed under the change.
- Split large proposals rather than accepting an oversized diff.
What people use it for
- A manager agent reviews a fixed set of coder agents every week and posts a diff for each one.
- An operator checks whether an agent keeps missing verification steps and drafts a rule that cites the issues where that happened.
- A team turns a repeated multi-step procedure that several issues got wrong into a reusable skill draft.
- A coordinator notices an agent stays blocked without escalating and proposes a clearer escalation trigger in its AGENTS.md.
Frequently asked questions
Is the Reflection Coach skill free and what is its licence?
The item is listed under the MIT licence. The source does not state any price, so check the page for pricing details before assuming anything.
What do I need to use the Reflection Coach skill?
You need a Paperclip deployment with the PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID and PAPERCLIP_AGENT_ID environment variables, plus access to the Paperclip REST API for agents, issues, comments and skills. It is not useful on its own outside a Paperclip company.
How do I install the reflection-coach skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills.
Does the skill change another agent's instructions automatically?
No. The skill produces a reviewable diff. Application happens only after an accepted interaction and in a separate follow-up run, and the skill never proposes and applies in the same run.
Does the skill run scripts or use the network?
It runs no scripts but uses the network, because it calls the Paperclip REST API to read agents, issues, comments and skills.
What are alternatives to Reflection Coach?
The source does not name alternatives or compare this skill with others, so this guide cannot make that comparison. The skill is specific to reviewing agents on Paperclip.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Reflection Coach suits teams running several agents on Paperclip who want periodic, evidence-based tuning and reviewable diffs instead of silent prompt changes. It is a poor fit for anyone wanting a general coding or writing helper, or for setups where agents should change each other's configuration without human review.
Download the skill