Skip to main content
skill CX Codex

retro · phuryn/product-engineering — Claude Code skill: what it does, how to install

The retro Claude Code skill reviews session friction and turns verified causes into changes to the agent setup. Start it by name at the end of a session.

MIT ★ 741 updated 2026-11-14

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add phuryn/product-engineering
/plugin install agent-harness@product-engineering
Open on GitHub

What retro does

retro examines what slowed a session down or went wrong, then traces each incident to its cause. It updates the relevant instruction, reading route, hook, or script and checks the change where it takes effect. A one-off incident can end with no setup change.

The skill prefers code fixes, then edits to existing instructions, and new rules last. A new rule gets a date and the incident behind it. Checks cover reversible repository changes; the skill does not test a fix by running an irreversible action. It proposes exact text for changes outside the repository and waits for the owner’s approval before making them.

What it helps with

  • trace a repeated agent error to its cause
  • repair an instruction the agent failed to follow
  • add a check for a broken script or hook
  • record a one-off incident without adding a rule

Example prompts for the agent

  • Find why the agent ran the tests against the wrong server twice, then fix the setup.
  • Identify the rule the agent missed in this session and verify the change.
  • Review this session’s friction, explain its causes, and report whether the setup needs a change.

How to install retro

1Plugin marketplace

/plugin marketplace add phuryn/product-engineering
/plugin install agent-harness@product-engineering

This installs the whole agent-harness plugin with all its skills

2Skills CLI (Vercel)

npx skills add phuryn/product-engineering --skill retro -a claude-code

3Manually: put the files in place

~/.claude/skills/retro/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/retro/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about retro

How do I install retro in Claude Code?

In Claude Code, run /plugin marketplace add phuryn/product-engineering, then /plugin install agent-harness@product-engineering. Alternatively, install the skill with npx skills add phuryn/product-engineering --skill retro -a claude-code.

What does retro do?

It traces session failures and delays to their causes, then updates relevant agent instructions, routes, hooks, or scripts. It checks each change where it applies.

Does retro change global settings?

No. It drafts exact text for changes outside the repository and makes them only after the owner approves.

Source text

SKILL.md · MIT
---
name: retro
description: "Build a session's learnings into the setup: its friction, what went wrong and why, then an improved instruction, route, hook or script, verified, or 'no setup change warranted'. Started by name only: /agent-harness:retro in Claude Code, $agent-harness:retro in Codex."
argument-hint: "<optional: the friction you noticed>"
disable-model-invocation: true
---

# Retro — a session's learnings, built into your setup

**Build the session's learnings into the setup before its context goes.** At the end of a session, find what slowed it down or went wrong, why, and what setup change stops it happening again. The output is fixes made and checked, not a list of lessons.

## Invocation

```
/agent-harness:retro                             Claude Code, plugin installed
/agent-harness:retro it ran the tests against the wrong server twice
$agent-harness:retro                             Codex, plugin installed
/retro   ·   $retro                              the skill folder copied into a repository
```

## Steps

### 1. List what actually happened

**List only this session's friction, with the moment each item happened.**

- the owner corrected the agent (quote the correction);
- the agent missed a rule it had;
- work was done twice, or undone;
- an assumption turned out wrong;
- a tool, script or command failed, or needed a workaround;
- the owner waited on something the agent could have done.

**Leave out successes and guesses about the future.** List evidence, not new rules: an item with no moment behind it is not one.

### 2. Find the cause of each

| Cause | What it looks like | The fix goes in |
|---|---|---|
| Missing | nothing told the agent | the entry file when every session needs it; otherwise the file the agent reads at the moment the rule must change a decision, with a router row for that moment (§ 3) |
| Present but not met | the rule existed and the agent didn't apply it when it mattered | the route to it (the instructions' index of what to read when), or code |
| A tool gap | a script, check or wrapper was missing or wrong | the tool |
| A skill's advice | a skill from a plugin or a collection said something wrong, or left a step out | the project's own agent instructions, naming the skill and what to do instead (§ 3) |
| A one-off | it won't recur | nowhere: say so |

### 3. Fix it, code first

**Prefer code, then an improved instruction or route, then a new rule.** Use this order:

1. **Hold the fix in code wherever code can hold it.** Use a script, hook, validation, required argument or test. Prose loses when compliance depends on an agent remembering a sentence at the moment it matters. Apply the `guardrail-hooks` skill for hooks and permission rules.
2. **Improve an existing instruction or route before adding another rule.** Reword the misread rule, or move it where the agent will see it when it applies. Replace or tighten before adding. Removing a rule's text is the owner's decision. Tighten wording without dropping a condition, exception or receipt, or move the rule to its fire point with a pointer left behind. A move is not a removal. You can also add the test or hook that holds it, and propose removal. Apply the `agent-instructions` skill for how instruction files are shaped.
3. **Add a new rule only when this session gave it a receipt.** Include the date and what happened.

**Put each learning where it must change a decision.** The entry file (`AGENTS.md`, or the project's own name) holds what every session needs. Put the rest at its fire point, not its topic home, usually in the file for the area that task touches. Add an entry-file index line saying when to read it.

**Re-read an area's file at the start of every task touching it.** The index must require this, not once a session. After compaction or a long session, the earlier read is gone. If the router doesn't yet say to re-read at every task, add that sentence. Each file stays within its word budget, and the rule carries its receipt and a review date (`agent-instructions`, budgets).

**Make reversible repository fixes and verify each where it applies.** Pipe a sample payload that must trigger into a hook, and one that must not; for a new or rewired hook, also run its canary in a live session where it has one (the `guardrail-hooks` templates do); otherwise report the wiring unchecked. Never run a real one-way door to test it. Open the route where the agent will read it; run the script. Report an unchecked fix as unchecked. Propose changes outside the repository with exact text; don't make them unless the owner says so. This includes the user's own settings and global instructions.

**Keep a skill's correction in the project's own agent instructions.** Put it where the agent reads it while that skill is in use. Use the router row for when the skill runs, or the entry file if it can fire in any task. An installed plugin copy sits outside the repository; a copied skill is overwritten by its next update, so edits to either are lost.

**Draft skill corrections for the source repository for the owner to file.** Use the repository its plugin or copy came from. Include what the skill says, what happened (the receipt), and replacement text, for the owner to file as an issue there. Follow that repository's skill style: name the product by kind. Include no session names, ids, hostnames, paths, account names or values, since the repository is usually public.

### 4. Report

**Report each item's incident, cause, fix and verification in one line.** When nothing deserves a change, "no setup change warranted" is valid and better than a rule that will never fire.

**Don't gate what the owner wouldn't want to click for.** A guard that asks too often trains a reflexive yes.

Each rule's origin, the case that taught it, is in `receipts.md` beside this file; read it when a rule's edge is unclear.

## How you can tell it worked

Each fix names the moment it came from and was checked where it applies, and the next session doesn't hit the same friction.

© Paweł Huryn · MIT · phuryn/product-engineering

Similar skills

All skills for Agent setup: memory, context, orchestration →

retro by other authors comes first.

retro Matt Pocock retro reviews a coding session and suggests changes to the agent environment for later runs. Use it after mistakes, slow repository navigation, or costly tool calls. CX Codex +1 276,027installs retro phuryn Facilitates structured sprint retrospectives, analyzes team performance, and turns feedback into prioritized action items with assigned owners and deadlines. CX Codex +1 2,900installs retro typeui.sh retro sets up a vintage design system with high-contrast palettes, Macondo typography, and WCAG 2.2 AA accessible component guidelines. CX Codex +1 2,800installs retro Necmttn retro runs a guided session over the ax agent-experience graph. Shows open proposals, pending verdicts, and hook effectiveness signals. CX Codex +1 ★ 124repo stars retro rainmanjam retro guides post-incident code analysis to identify structural weaknesses and prevent entire classes of failures. CX Codex +1 ★ 26repo stars session-review awrshift This skill for Claude Code runs an adversarial review of a coding session’s work. Invoke it with /session-review or ask the agent to review the session. CX Codex +1 ★ 33repo stars pr-retro ulpi-io The pr-retro skill measures a feature branch against its base and reports merge-readiness with recommendations. Run it before reviewing a PR. CX Codex +1 150installs printing-press-retro mvanhorn printing-press-retro runs a structured retrospective after a Printing Press CLI generation run, redacts sensitive data, and drafts GitHub issues for core tool defects. CX Codex +1 6,800installs retro-marimo-pair marimo-team retro-marimo-pair — a skill that runs a retrospective on a marimo pairing session, finds the friction and turns it into something the team can act on. CX Codex +1 5,600installs om-pipeline-retro open-mercato om-pipeline-retro classifies finished pipeline runs, detects rerun causes, and calculates wall-clock hours lost to rework. Useful for team retrospectives. CX Codex +1 3,100installs launch-retro-analyzer aaron-he-zhu The launch-retro-analyzer skill compares launch results with channel targets, investigates the largest miss, and prepares decisions for the next launch. It handles D1, W1, and M1 retrospectives. CX Codex +1 1,100installs

From the same set51

The whole set →
value-proposition This Claude Code skill shapes a value proposition with a six-part JTBD structure. It covers a customer segment, its task, the current approach and alternatives. CX Codex +1 ★ 741repo stars competitor-analysis competitor-analysis — a Claude Code skill for mapping market rivals and product substitutes. It analyzes five direct competitors, flags functional gaps, and highlights strategic differentiation points. CX Codex +1 ★ 741repo stars growth-loops This Claude Code skill evaluates product growth loops. Ask it to compare viral sharing, referrals, collaboration, or user-generated content and map out an implementation plan. CX Codex +1 ★ 741repo stars beachhead-segment The beachhead-segment Claude Code skill scores candidate customer segments and selects a first market to pursue. It weighs customer pain, willingness to pay, winnable share and referral potential. CX Codex +1 ★ 741repo stars value-curve This Claude Code skill maps a product’s value curve for one customer segment. It compares key needs, competing offers and relative price. CX Codex +1 ★ 741repo stars document-app The document-app Claude Code skill documents an app from its code or checks whether existing docs match the implementation. It runs on requests to document an app or verify its system documentation. CX Codex +1 ★ 741repo stars uptime-monitoring The uptime-monitoring Claude Code skill sets up external app checks and alert delivery. It activates when an app goes live, a /health endpoint or cron job is added, or monitoring is requested. CX Codex +1 ★ 741repo stars performance-audit-static The performance-audit-static Claude Code skill statically reviews code for performance issues such as N+1 queries, excess data fetching, index gaps, and caching. It runs when a performance audit is requested. CX Codex +1 ★ 741repo stars

Project sponsors

Companies that keep this analytics open