Not in the top 1,000 by GitHub stars
Thomaszhou22/self-refine-skill
Systematic self-reflection for AI agents. GENERATE → CRITIQUE → REFINE → CHECK. Based on peer-reviewed research. Zero API cost. Works with Claude Code, Cursor, Copilot, Codex CLI, and 10+ more platforms.
History
Review weekly changes to SKILL.md before updating. Dates mark the weeks in which we observed each version; checks apply to the recorded commits.
View weekly changes
SKILL.md
Week of Nov 2, 2026 · +0 / −0 lines
Before Network or broad shell → After Network or broad shell
225fc93410e6 → 225fc93410e6
Week of Oct 26, 2026 · Line counts unavailable
Before Not checked yet → After Network or broad shell
First observation → 225fc93410e6
No earlier version was observed for comparison.
View on GitHubAdd to my skills
Verified commit 225fc93410e6905573052744dcf53f05625aa63b
git clone --filter=blob:none --no-checkout https://github.com/Thomaszhou22/self-refine-skill.git .hotskills/thomaszhou22-self-refine-skill && git -C .hotskills/thomaszhou22-self-refine-skill checkout --detach 225fc93410e6905573052744dcf53f05625aa63b
# Copy each selected skill directory from .hotskills/thomaszhou22-self-refine-skill into .claude/skills/<skill-name>/git clone --filter=blob:none --no-checkout https://github.com/Thomaszhou22/self-refine-skill.git .hotskills/thomaszhou22-self-refine-skill && git -C .hotskills/thomaszhou22-self-refine-skill checkout --detach 225fc93410e6905573052744dcf53f05625aa63b
# Copy each selected skill directory from .hotskills/thomaszhou22-self-refine-skill into .gemini/skills/<skill-name>/12GitHub stars
1star in 7 days
1skill in this repository
2commits in 30 days
Heat
2.7- Star growth, last 7 daysNot available
- Star growth, last 24 hoursNot available
- Rank movement, last 7 daysNot available
- Commits, last 30 daysNot available
- Accounts asking about it through MCP, last 7 daysNot available
- Hot votes this weekNot available
Heat never changes the order by stars, and sponsorship never touches it. How heat works
Stars over time
30-day change not yet available: not enough history.
Individual skills in this repository
How it works
self-refine-reflection
When your agent uses it
Systematic self-reflection and iterative output refinement for AI agents. Based on Madaan et al. (2023) Self-Refine, Shinn et al. (2023) Reflexion, and Andrew Ng's Reflection pattern. Use when outputs need multi-round critique-and-improve cycles, when initial quality is insufficient, or when complex tasks benefit from self-correction.
What it loads into context
Frontmatter
108 tokensAlways available to the agent
SKILL.md
2,571 tokensWhen the skill is activated
Reference documents
16,194 tokensLoaded on request
Token counts are estimates. Scripts run separately; they are not counted as reference context.
The playbook
- Platform Auto-Detection
- Inline Reflection Templates (for environments without file access)
- When to Activate
- Core Loop: GENERATE → CRITIQUE → REFINE → CHECK
- Reflection Dimensions
- Reflection Depth Levels
- Convergence Rules
- Cost Control Strategy
- Trigger Conditions Summary
- Output Format
- Reflexion Memory (Cross-Session Learning)
- Relationship to Other Reflection Techniques
- Quick Reference Card
Files
.claude-plugin/.claude-plugin/marketplace.jsonasset631 bytes.claude-plugin/.claude-plugin/plugin.jsonasset458 bytes.claude-plugin/marketplace.jsonasset631 bytes.claude-plugin/plugin.jsonasset458 bytes.github/ISSUE_TEMPLATE/bug_report.mddoc437 bytes.github/ISSUE_TEMPLATE/feature_request.mddoc406 bytes.github/PULL_REQUEST_TEMPLATE.mddoc451 bytes.gitignoreasset40 bytesBENCHMARK.mddoc36,616 bytesCHANGELOG.mddoc1,588 bytesCLAUDE.mddoc227 bytesCONTRIBUTING.mddoc1,574 bytesGEMINI.mddoc157 bytesLICENSEasset1,068 bytesREADME.mddoc11,998 bytesSKILL.mdcore10,809 bytesreferences/reflection-templates.mddoc3,557 bytesreferences/sources.mddoc2,927 bytes
Read SKILL.md
# Self-Refine Reflection Skill
> An AI agent skill for systematic self-reflection and iterative output refinement.
> Based on Madaan et al. (2023), Shinn et al. (2023), and Andrew Ng's Reflection design pattern.
## Platform Auto-Detection
At skill load time, detect your runtime environment and adjust capabilities:
| Capability | How to Check | Fallback
|-----------|-------------|----------|
| File system | Can you read `references/reflection-templates.md`? | Use the inline templates below instead
| Persistent memory | Can you write to `memory/`? | Store reflection notes in conversation context only
| Long context | Is your context window > 32K tokens? | Cap at Level 2 (skip adversarial review)Skills included
- self-refine-reflection
Repository facts
- License
- MIT
- Created
- May 19, 2026
- Last pushed
- Nov 3, 2026
- Forks
- 0
- Open issues
- 0
- Project activity
- Active
Before you install
Network or broad shellAutomated signals, not a guarantee
Checked Nov 4, 2026
- No broad tool permissions
- 1 dangerous shell commandin 1 file: BENCHMARK.md:727
- 58 network referencesin 6 files: references/sources.md:6 BENCHMARK.md:309 README.md:9 and 3 more
- No hidden or obfuscated text
- No instruction overrides
- No executable scripts
- 1 reference to secretsin 1 file: .gitignore:4
- No requests to vote in Hot
Show all 60 signals by file
.claude-plugin/.claude-plugin/plugin.json
- Network accessline 6
"name": "Thomas Zhou" }, "homepage": "https://github.com/Thomaszhou22/self-refine-skill", - Network accessline 7
}, "homepage": "https://github.com/Thomaszhou22/self-refine-skill", "repository": "https://github.com/Thomaszhou22/self-refine-skill", - Network accessline 8
"homepage": "https://github.com/Thomaszhou22/self-refine-skill", - Network accessline 9
"repository": "https://github.com/Thomaszhou22/self-refine-skill",
.claude-plugin/plugin.json
- Network accessline 6
"name": "Thomas Zhou" }, "homepage": "https://github.com/Thomaszhou22/self-refine-skill", - Network accessline 7
}, "homepage": "https://github.com/Thomaszhou22/self-refine-skill", "repository": "https://github.com/Thomaszhou22/self-refine-skill", - Network accessline 8
"homepage": "https://github.com/Thomaszhou22/self-refine-skill", - Network accessline 9
"repository": "https://github.com/Thomaszhou22/self-refine-skill",
.gitignore
- Access to secretsline 4
[Credential-related source omitted]
BENCHMARK.md
- Network accessline 309
> ```jsx > // ❌ Triggers loop: { page: 1 } !== { page: 1 } > useEffect(() => { fetch(filters); }, [filters]); - Network accessline 310
> // ❌ Triggers loop: { page: 1 } !== { page: 1 } > useEffect(() => { fetch(filters); }, [filters]); > - Network accessline 311
> useEffect(() => { fetch(filters); }, [filters]); - Network accessline 312
> > // ✅ Use primitive deps > useEffect(() => { fetch(filters); }, [filters.page, filters.sort]); - Network accessline 313
> // ✅ Use primitive deps > useEffect(() => { fetch(filters); }, [filters.page, filters.sort]); > ``` - Network accessline 314
> useEffect(() => { fetch(filters); }, [filters.page, filters.sort]); - Network accessline 690
> listen 80; > location / { > proxy_pass http://localhost:3000; - Network accessline 691
> location / { > proxy_pass http://localhost:3000; > } - Network accessline 692
> proxy_pass http://localhost:3000; - Network accessline 703
> listen 80; > server_name example.com; > return 301 https://$host$request_uri; # force HTTPS - Network accessline 704
> server_name example.com; > return 301 https://$host$request_uri; # force HTTPS > } - Network accessline 705
> return 301 https://$host$request_uri; # force HTTPS - Network accessline 714
> > location / { > proxy_pass http://127.0.0.1:3000; - Network accessline 715
> location / { > proxy_pass http://127.0.0.1:3000; > proxy_http_version 1.1; - Network accessline 716
> proxy_pass http://127.0.0.1:3000; - Dangerous shell operationline 727
> **Key:** The `X-Forwarded-*` headers let your Node app know the real client IP and protocol. Without them, `req.ip` is `127.0.0.1`. SSL via certbot: `sudo certbot --nginx -d example.com`.
CONTRIBUTING.md
- Network accessline 9
- Open an [Issue](https://github.com/Thomaszhou22/self-refine-skill/issues)
README.md
- Network accessline 9
[](LICENSE) - Network accessline 10
[](https://openclaw.ai) - Network accessline 11
[](https://claude.ai) - Network accessline 12
[](https://cursor.sh) - Network accessline 13
[](https://github.com/features/copilot) - Network accessline 14
[](https://github.com/openai/codex) - Network accessline 15
[](https://ai.google.dev) - Network accessline 16
[](https://codeium.com/windsurf) - Network accessline 17
[](https://www.jetbrains.com/ai/) - Network accessline 18
[](BENCHMARK.md)
references/sources.md
- Network accessline 6
- **Authors:** Madaan, Tandon, Gupta, Hallinan, Gao, Wiegreffe, Alon, Dziri, Prabhumoye, Yang, Gupta, Majumder, Hermann, Welleck, Yazdanbakhsh, Clark - **Year:** 2023 - **URL:** https://arxiv.org/abs/2303.17651 - Network accessline 7
- **Year:** 2023 - **URL:** https://arxiv.org/abs/2303.17651 - **Code:** https://github.com/madaan/self-refine - Network accessline 8
- **URL:** https://arxiv.org/abs/2303.17651 - Network accessline 9
- **Code:** https://github.com/madaan/self-refine - Network accessline 14
- **Authors:** Shinn, Labash, Narasimhan - **Year:** 2023 (NeurIPS) - **URL:** https://arxiv.org/abs/2303.11366 - Network accessline 15
- **Year:** 2023 (NeurIPS) - **URL:** https://arxiv.org/abs/2303.11366 - **Code:** https://github.com/noahshinn/reflexion - Network accessline 16
- **URL:** https://arxiv.org/abs/2303.11366 - Network accessline 17
- **Code:** https://github.com/noahshinn/reflexion - Network accessline 22
- **Authors:** Dhuliawala, Kordi, Khashabi, Schubotz, Azer, Gurevych - **Year:** 2023 - **URL:** https://arxiv.org/abs/2309.11495 - Network accessline 23
- **Year:** 2023 - **URL:** https://arxiv.org/abs/2309.11495 - **What we use:** Verification question pattern for factual claims in Level 2-3 reviews. - Network accessline 24
- **URL:** https://arxiv.org/abs/2309.11495 - Network accessline 28
- **Authors:** Kadavath et al. - **Year:** 2022 - **URL:** https://arxiv.org/abs/2207.05221 - Network accessline 29
- **Year:** 2022 - **URL:** https://arxiv.org/abs/2207.05221 - **What we use:** Self-calibration — models can assess their own confidence. - Network accessline 30
- **URL:** https://arxiv.org/abs/2207.05221 - Network accessline 49
- **Authors:** Wang et al. - **Year:** 2022 - **URL:** https://arxiv.org/abs/2203.11171 - Network accessline 51
- **URL:** https://arxiv.org/abs/2203.11171 - Network accessline 54
- **Authors:** Yao et al. - **Year:** 2023 - **URL:** https://arxiv.org/abs/2305.10601 - Network accessline 56
- **URL:** https://arxiv.org/abs/2305.10601 - Network accessline 59
- **Authors:** Zhang et al. - **Year:** 2023 - **URL:** https://arxiv.org/abs/2308.04371 - Network accessline 61
- **URL:** https://arxiv.org/abs/2308.04371 - Network accessline 65
### Learn Prompting — Self-Criticism Section - **URL:** https://learnprompting.org/docs/advanced/self_criticism/introduction - Network accessline 66
- **URL:** https://learnprompting.org/docs/advanced/self_criticism/introduction - Network accessline 69
### Self-Refine Demo Site - **URL:** https://selfrefine.info/ - Network accessline 70
- **URL:** https://selfrefine.info/
How the signals fit together
Facts from a static read of the files at the pinned commit. They describe what the code does, not why.
Some files could not be read; the facts below still hold.
Signal confidence: 51 facts
- Network access in prose of documentationBENCHMARK.md:309Low confidence
- Network access in prose of documentationBENCHMARK.md:310Low confidence
- Network access in prose of documentationBENCHMARK.md:311Low confidence
- Network access in prose of documentationBENCHMARK.md:312Low confidence
- Network access in prose of documentationBENCHMARK.md:313Low confidence
- Network access in prose of documentationBENCHMARK.md:314Low confidence
- Network access in prose of documentationBENCHMARK.md:690Low confidence
- Network access in prose of documentationBENCHMARK.md:691Low confidence
- Network access in prose of documentationBENCHMARK.md:692Low confidence
- Network access in prose of documentationBENCHMARK.md:703Low confidence
- Network access in prose of documentationBENCHMARK.md:704Low confidence
- Network access in prose of documentationBENCHMARK.md:705Low confidence
- Network access in prose of documentationBENCHMARK.md:714Low confidence
- Network access in prose of documentationBENCHMARK.md:715Low confidence
- Network access in prose of documentationBENCHMARK.md:716Low confidence
- Dangerous shell operation in prose of documentationBENCHMARK.md:727Low confidence
- Network access in prose of documentationCONTRIBUTING.md:9Low confidence
- Network access in prose of documentationREADME.md:9Low confidence
- Network access in prose of documentationREADME.md:10Low confidence
- Network access in prose of documentationREADME.md:11Low confidence
- Network access in prose of documentationREADME.md:12Low confidence
- Network access in prose of documentationREADME.md:13Low confidence
- Network access in prose of documentationREADME.md:14Low confidence
- Network access in prose of documentationREADME.md:15Low confidence
- Network access in prose of documentationREADME.md:16Low confidence
- Network access in prose of documentationREADME.md:17Low confidence
- Network access in prose of documentationREADME.md:18Low confidence
- Network access in prose of documentationreferences/sources.md:6Low confidence
- Network access in prose of documentationreferences/sources.md:7Low confidence
- Network access in prose of documentationreferences/sources.md:8Low confidence
- Network access in prose of documentationreferences/sources.md:9Low confidence
- Network access in prose of documentationreferences/sources.md:14Low confidence
- Network access in prose of documentationreferences/sources.md:15Low confidence
- Network access in prose of documentationreferences/sources.md:16Low confidence
- Network access in prose of documentationreferences/sources.md:17Low confidence
- Network access in prose of documentationreferences/sources.md:22Low confidence
- Network access in prose of documentationreferences/sources.md:23Low confidence
- Network access in prose of documentationreferences/sources.md:24Low confidence
- Network access in prose of documentationreferences/sources.md:28Low confidence
- Network access in prose of documentationreferences/sources.md:29Low confidence
- Network access in prose of documentationreferences/sources.md:30Low confidence
- Network access in prose of documentationreferences/sources.md:49Low confidence
- Network access in prose of documentationreferences/sources.md:51Low confidence
- Network access in prose of documentationreferences/sources.md:54Low confidence
- Network access in prose of documentationreferences/sources.md:56Low confidence
- Network access in prose of documentationreferences/sources.md:59Low confidence
- Network access in prose of documentationreferences/sources.md:61Low confidence
- Network access in prose of documentationreferences/sources.md:65Low confidence
- Network access in prose of documentationreferences/sources.md:66Low confidence
- Network access in prose of documentationreferences/sources.md:69Low confidence
and 1 more
Works with
| Agent | Status | Evidence | Install to |
|---|---|---|---|
| Claude Code | Native | Manifest .claude-plugin/.claude-plugin/plugin.json | .claude/skills/<skill-name>/ |
| Codex | Compatible | Standard SKILL.md SKILL.md | .agents/skills/<skill-name>/ |
| Cursor | Compatible | Standard SKILL.md SKILL.md | .cursor/skills/<skill-name>/ |
| Gemini CLI | Native | Path GEMINI.md | .gemini/skills/<skill-name>/ |
| GitHub Copilot | Compatible | Standard SKILL.md SKILL.md | .github/skills/<skill-name>/ |
| OpenCode | Compatible | Standard SKILL.md SKILL.md | .opencode/skills/<skill-name>/ |
- Native The repository ships a manifest, folder or frontmatter field for this agent.
- Compatible A standard SKILL.md that this agent can read.
- Unknown No evidence either way.
Derived automatically from paths, manifests and frontmatter. Not tested on each agent.
