How do I install the Reflect skill?

Run npx skillmds@latest add tuyv/reflect in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Reflect safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Reflect?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Reflect free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Reflect?

tuyv (@tuyv) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Reflect by tuyv — Agent Skill

Name: Reflect
Author: tuyv

File contents

Reflect: Per-Project Self-Improvement

You are performing a reflection - turning the signal this project has captured into durable improvements. Nothing is applied without the developer's approval.

Phase 1 - Orient (gather signal)

Run the stats script over the ledger: ~/.claude/hooks/harness-ledger-stats.sh --ledger .harness/ledger.jsonl --min-recurr 3 If that path doesn't exist, the hooks aren't installed at ~/.claude/hooks/ - run the copy from wherever this project keeps them. If the script prints all zeros there is no ledger yet (no signal captured) - stop; there is nothing to reflect on.
Read the current project rules in CLAUDE.md so you improve them rather than duplicate.
Read recent feedback-type memory files - these are the developer's explicit corrections and are the highest-value signal. Locate the memory directory first (it sits next to MEMORY.md; find . -name MEMORY.md if unsure), then grep -l 'type: feedback' <memory-dir>/*.md.
Read the most recent .harness/reflections/*.md report (if any) to recall the last metric snapshot and what was already changed.

Phase 2 - Cluster

From the stats output and feedback memories, identify recurring problems:

Each recurring <rule> <prefix> <count> line is a friction cluster - the same check keeps firing in the same area.
Group related feedback corrections by theme.
Ignore one-off events; focus on what repeats.

Phase 3 - Propose (one candidate per cluster)

For each cluster, draft exactly one proposed change, choosing the fitting type:

Type	When	Where it lands
Project rule	a convention would stop the repeat	append to `CLAUDE.md` project-specific section
Threshold change	a guardrail is too strict/loose	a diff to `.claude/settings.json` or the hook - shown, never auto-applied
Lint rule	the mistake is mechanically catchable	a diff to `eslint.config.mjs` / `biome.jsonc`
ADR / knowledge	durable "why" worth keeping	a new memory file or `docs/adr/` note

Present all proposals together as a numbered list with the concrete change for each.

Phase 4 - Gate & Record

Ask the developer to approve, edit, or reject each proposal (like /remember).
Apply only the approved ones, then commit them (use /commit).
Create .harness/reflections/ if needed (mkdir -p .harness/reflections), then write a reflection report to .harness/reflections/YYYY-MM-DD.md containing:
- the full stats output (the metric snapshot, so the next reflection can compare),
- the clusters you found,
- which proposals were approved / rejected and why.

The report is committed; the raw .harness/ledger.jsonl stays gitignored. Signal is private; wisdom is shared.

Measuring success

The headline metric is recurring_events from the stats output. Compare it to the value in the previous reflection report. If a rule you promoted last time worked, the cluster it targeted should have shrunk. Note the trend explicitly in the new report.

---name: reflectdescription: Per-project self-improvement - reads the .harness ledger and feedback memories, then proposes gated rule/threshold/ADR changes so the project stops repeating mistakes. Run periodically.---# Reflect: Per-Project Self-ImprovementYou are performing a reflection - turning the signal this project has capturedinto durable improvements. Nothing is applied without the developer's approval.## Phase 1 - Orient (gather signal)- Run the stats script over the ledger: `~/.claude/hooks/harness-ledger-stats.sh --ledger .harness/ledger.jsonl --min-recurr 3` If that path doesn't exist, the hooks aren't installed at `~/.claude/hooks/` - run the copy from wherever this project keeps them. If the script prints all zeros there is no ledger yet (no signal captured) - stop; there is nothing to reflect on.- Read the current project rules in `CLAUDE.md` so you improve them rather than duplicate.- Read recent `feedback`-type memory files - these are the developer's explicit corrections and are the highest-value signal. Locate the memory directory first (it sits next to `MEMORY.md`; `find . -name MEMORY.md` if unsure), then `grep -l 'type: feedback' <memory-dir>/*.md`.- Read the most recent `.harness/reflections/*.md` report (if any) to recall the last metric snapshot and what was already changed.## Phase 2 - ClusterFrom the stats output and feedback memories, identify recurring problems:- Each `recurring <rule> <prefix> <count>` line is a friction cluster - the same check keeps firing in the same area.- Group related feedback corrections by theme.- Ignore one-off events; focus on what repeats.## Phase 3 - Propose (one candidate per cluster)For each cluster, draft exactly one proposed change, choosing the fitting type:| Type | When | Where it lands ||------|------|----------------|| **Project rule** | a convention would stop the repeat | append to `CLAUDE.md` project-specific section || **Threshold change** | a guardrail is too strict/loose | a diff to `.claude/settings.json` or the hook - **shown, never auto-applied** || **Lint rule** | the mistake is mechanically catchable | a diff to `eslint.config.mjs` / `biome.jsonc` || **ADR / knowledge** | durable "why" worth keeping | a new memory file or `docs/adr/` note |Present all proposals together as a numbered list with the concrete change for each.## Phase 4 - Gate & Record- Ask the developer to approve, edit, or reject each proposal (like `/remember`).- Apply only the approved ones, then commit them (use `/commit`).- Create `.harness/reflections/` if needed (`mkdir -p .harness/reflections`), then write a reflection report to `.harness/reflections/YYYY-MM-DD.md` containing: - the full stats output (the **metric snapshot**, so the next reflection can compare), - the clusters you found, - which proposals were approved / rejected and why.The report is committed; the raw `.harness/ledger.jsonl` stays gitignored. Signal isprivate; wisdom is shared.## Measuring successThe headline metric is `recurring_events` from the stats output. Compare it to the valuein the previous reflection report. If a rule you promoted last time worked, the cluster ittargeted should have shrunk. Note the trend explicitly in the new report.

Frequently asked questions

Reflect