iterate
Skill0 starsChanged 6 months agoMITView on GitHub
Meta-skill for skill self-improvement. After another skill finishes a run, /iterate analyzes the run's logs (friction events, retries, sub-agent rejections, pacing mismatches, bugs), produces a structured retrospective report, accumulates per-class friction counts, and — when a class crosses the configured threshold — opens a PR to that skill's open-source repo with a proposed SKILL.md diff. NEVER auto-merges; the human always reviews. Target skills opt in by declaring an `iteration:` block in their frontmatter. Invoke when the user says "iterate this skill", "iterate /devloop", "run a retro on the last skill run", "/iterate <skill-name>", or when a target skill auto-hands-off at end of its run.
- Commits and pushes
13 other projects use a version of this.
Adopted by
Most recently taken up by
- librosdeia/builder-method-claude-plugintheir own version, first seen Nov 15, 2026
- RohiRIK/skillstheir own version, first seen Nov 15, 2026
- 5thlayer/skillworkstheir own version, first seen Nov 8, 2026
- viktorsboroviks/skillstheir own version, first seen Nov 8, 2026
- devjiwonchoi/skillstheir own version, first seen Nov 8, 2026
- jingzhao-l/iterate-skilltheir own version, first seen Nov 7, 2026
Used with
Projects with it also use test, explain and 7 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
Microsoft AzureSkilltest
Also in 4 projects that use this
sunnyclinches44Skillexplain
Explains code using real-world analogies and ASCII diagrams
Also in 3 projects that use this
NVIDIASkillresearch
Before designing a feature, research how comparable libraries solve the problem, check best practices, known pitfalls, and upstream changes. Use when starting a new feature, investigating an unfamiliar area, or the user asks to research something.
Also in 5 projects that use this
Microsoft AzureSkilldesign
Design rules and conventions for the API Center Portal. Use when editing detail pages, card components, badges, layout, navigation, sidebars, or headers. Covers badge styling, metadata placement, page navigation patterns, and layout alignment.
Also in 3 projects that use this
MicrosoftSkillwriting-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
Also in 3 projects that use this
AWSSkillretro
Conduct a retrospective on a coding session.
Also in 3 projects that use this
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- OpenHands/extensions★ 167same name
- lalulali/vespyr★ 11same name
- bkraad47/ramen★ 4same name
- devjiwonchoi/skills★ 2same name
- jingzhao-l/iterate-skill★ 2same name
- marcuskrogh/skills★ 1same name
- RohiRIK/skills★ 1same name
- scottlivingston/claude-skills★ 1same name
- trevorbyrum/claude-skills-suite★ 1same name
- viktorsboroviks/skills★ 1same name
3 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 13 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
If neither is provided, ask the user via AskUserQuestion:
- Very specific: line 53
If iteration.enabled is missing or false, exit with a one-line note: "Skill <name> has not opted into iteration.
- Very specific: line 265
After writing RETRO, for each friction_class where count ≥ threshold AND pr_status == "none" AND not flagged by anti-pattern:
- Distinctive: line 293
If the user does not have push access to the skill_repo (e.g.
- Distinctive: line 331
If invoked with no args, ask the user which skill to iterate on.
- Distinctive: line 335
After running, print one short message to the user:
- Distinctive: line 348
Do NOT print the full report contents — point at the file.
- Distinctive: line 357
No automatic rollback if a merged PR turns out to have regressed the skill — the next iteration will catch it, but a regression is possible …
“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
iterate — skill self-improvement loop (the meta-skill)
You are a skill iterator. Another skill just finished a run; your job is to read its run
artifacts, identify what worked vs what struck friction, and either (a) write a retrospective
report for the user to act on, or (b) when the same friction has recurred enough times, open a
pull request to that skill's open-source repo with a concrete SKILL.md diff and a justification
backed by the friction evidence.
You are conservative by default. A skill self-modifying without human review is a runaway risk. Your output is a proposal; humans decide.
0. Kickoff — gather the run context
You need two things to start:
- Target skill name (e.g.
devloop). Either passed as argv, or you can read the most recent skill invocation from the conversation context. - Working directory of the run (where the target skill produced its artifacts — usually the user's project repo, NOT the skill's own repo).
If neither is provided, ask the user via AskUserQuestion:
- Which skill just ran? (List candidate names if you can detect them)
- Which working directory did it run in? (Default: current
pwd)
Once you know these two, read the target skill's frontmatter from
~/.claude/skills/<skill-name>/SKILL.md. Look for the iteration: block:
iteration:
enabled: true # if false or missing, exit
skill_repo: <owner>/<repo> # required for PR opening
threshold: 3 # default; per-skill override
artifacts:
friction_log: ./LOOP-FRICTION.jsonl # relative to run working dir
run_log: ./LOOP-LOG.md
state_file: ./.iteration-state.json # relative to run working dirIf iteration.enabled is missing or false, exit with a one-line note: "Skill <name> has not
opted into iteration. Add an iteration: frontmatter block to enable."
1. The iteration contract (what target skills declare)
The target skill is responsible for:
- Declaring the
iteration:block in its frontmatter - Writing a friction log during runtime — append-only JSONL, one event per line
- Writing a run log (free-form markdown, summary of the run)
- Auto-invoking
/iterate <skill-name>at end of run (or letting the user do it manually)
/iterate is responsible for:
- Reading the artifacts
- Analyzing them via sub-agent
- Updating the state file (accumulators)
- Writing the RETRO report
- Opening PRs when thresholds are hit
2. Friction log schema
Target skills append one JSON object per line to the friction log:
{"ts": "2026-05-13T16:42:11Z", "run_id": "<uuid>", "task": "issue-42", "type": "permission_blocked", "details": {"cmd": "gh auth status", "outcome": "user_approved_inline"}, "lesson_hint": "gh auth subcommands may need allowlist update"}
{"ts": "2026-05-13T16:51:03Z", "run_id": "<uuid>", "task": "issue-42", "type": "pacing_mismatch", "details": {"step": "deploy_verify", "scheduled_wait_s": 150, "actual_ready_s": 245, "retries": 2}, "lesson_hint": "Default deploy-verify wait undershoots for this build"}
{"ts": "2026-05-13T16:58:22Z", "run_id": "<uuid>", "task": "issue-43", "type": "subagent_flag_persistent", "details": {"verdict_cycles": 3, "final_verdict": "OK after fixes"}, "lesson_hint": "Self-review pass before sub-agent could have caught this earlier"}Predefined event types (target skills can extend with custom types, but these should be recognized by retro):
| Type | When to log | Required details fields |
permission_blocked | A bash/tool permission prompt fired | cmd, outcome |
permission_thrash | Same command blocked ≥2 times in one run | cmd, count |
retry | A command had to be re-run | cmd, attempts, reason |
pacing_mismatch | Scheduled wait was too short or too long | step, scheduled_wait_s, actual_ready_s |
subagent_flag_persistent | Reviewer rejected ≥2 cycles | verdict_cycles, final_verdict |
unexpected_state | Reality didn't match assumption (e.g. stale git state) | assumption, actual |
stop_condition_hit | A STOP condition triggered | which, recoverable |
safety_intentional | A deny / safety mechanism kicked in correctly | cmd, why |
safety_intentional is the inverse of friction — it means a guardrail worked as designed.
You log it so retro knows NOT to propose relaxing it.
3. State file schema
Per-project state file at <working-dir>/.iteration-state.json:
{
"skill": "devloop",
"skill_repo": "AntaresYuan/claude-devloop",
"threshold": 3,
"first_run": "2026-05-13T12:00:00Z",
"runs": [
{"id": "run-001", "ts": "2026-05-13T16:42:00Z", "tasks_done": 4, "friction_count": 6, "retro_path": "RETRO-2026-05-13.md"}
],
"friction_accumulators": {
"permission_blocked::gh-auth": {
"count": 4,
"first_seen": "2026-05-13T12:14:00Z",
"last_seen": "2026-05-13T16:42:00Z",
"examples": [{"run_id": "run-001", "ts": "...", "cmd": "gh auth status"}],
"pr_status": "none"
},
"pacing_mismatch::deploy_verify": {
"count": 2,
"pr_status": "none"
}
},
"pr_history": [
{"pr_url": "https://github.com/AntaresYuan/claude-devloop/pull/12", "friction_class": "permission_blocked::gh-auth", "ts": "...", "status": "open"}
]
}Friction class = <type>::<sub-key> where sub-key is a stable identifier (e.g. command
name, step name, assumption type). The retro sub-agent assigns the sub-key by clustering similar
events.
4. The retro analysis — sub-agent invocation
Spawn a fresh general-purpose sub-agent with Read-only tools (Read, Grep, Glob,
WebFetch). NO Edit / Write / Bash — the sub-agent does not modify anything; it only
returns a structured report.
Sub-agent prompt template:
You are running a retrospective on a single skill run. Inputs:
- Skill name:
<name>- Current SKILL.md at
~/.claude/skills/<name>/SKILL.md(Read it)- Friction log:
<path>/LOOP-FRICTION.jsonl- Run log:
<path>/LOOP-LOG.md- State file (prior runs' accumulators):
<path>/.iteration-state.json- Recent commits to skill_repo:
gh api repos/<owner>/<repo>/commits(last 5)Produce a markdown report covering:
A. Friction observed in this run. Group events by class (
<type>::<sub-key>). For each class: count this run, examples, hypothesis for root cause.B. Quality observations. Did sub-agent reviews flag issues that should have been caught by self-review? Did the user have to step in? Did any PR get reverted?
C. Bugs / regressions. Anything shipped that broke later? Any rollback?
D. Pacing. Were Wakeup intervals well-calibrated? Where was time wasted vs squeezed?
E. Proposed SKILL.md diffs. For each friction class that has a plausible skill-side fix, propose a concrete diff. Format:
--- a/SKILL.md (current section heading) +++ b/SKILL.md (proposed) @@ ... @@ - old line + new lineJustify each diff with friction evidence (event count, examples).
F. Cross-cutting lessons. One-line additions that could go into a "common pitfalls" section.
G. Anti-pattern check — DO NOT propose:
- Removing or weakening any
deny:entry in permission allowlists- Skipping safety checks (e.g.
--no-verify, force pushes, hook bypass)- Loosening any rule labeled "non-negotiable" or "red line" in the current SKILL.md
- Auto-approving anything destructive (rm, drop, force-push, secret rotation)
- Changes to
safety_intentionalevents — those are guardrails working, not frictionIf a proposed change touches any of the above, mark it
BLOCKED_BY_ANTI_PATTERNand explain.Return the report as markdown. Do not modify any files.
Sub-agent runs read-only; receive markdown report; you (the main /iterate run) write it to
disk as RETRO-<YYYY-MM-DD>.md in the working directory.
5. RETRO report format
# Retrospective — /<skill-name> · <YYYY-MM-DD>
**Run**: <run-id>
**Working directory**: <path>
**Tasks completed**: <N>
**Friction events logged**: <M>
**Sub-agent verdict**: <one-line summary>
## A. Friction observed (this run)
### Class: `permission_blocked::gh-auth` (count: 1 this run, **4 cumulative**)
- Example: `gh auth status` was blocked at <ts>, user approved inline
- Hypothesis: `Bash(gh auth:*)` is in deny list (intentional? or oversight?)
- **Status**: at threshold (3) → PR proposed below
### Class: `pacing_mismatch::deploy_verify` (count: 2 this run, **2 cumulative**)
- ...
## B. Quality observations
## C. Bugs / regressions
## D. Pacing
## E. Proposed SKILL.md edits
### Diff #1 — Increase default deploy-verify wait
**Triggered by**: `pacing_mismatch::deploy_verify` (2 occurrences, both retried successfully)
```diff
--- a/SKILL.md (§2 step 13)
+++ b/SKILL.md
@@
- ScheduleWakeup ~150s (or the deploy duration).
+ ScheduleWakeup ~200s (or the deploy duration; observed median 180s on builds with CI).Justification: this run hit deploy-verify retries 2× because 150s was short for the project's build pipeline. Increasing the default to 200s eliminates the retry without significantly delaying the loop.
Anti-pattern check: PASS (no safety, no deny list, no red line touched)
Diff #2 — Add gh auth to recommended allowlist
Triggered by: permission_blocked::gh-auth (4 cumulative across 2 runs)
BLOCKED_BY_ANTI_PATTERN: Bash(gh auth:*) is in the current SKILL.md permissions.deny
list (line 43). Removing or relaxing a deny entry is forbidden. No PR opened for this class.
Suggested human action: review the deny entry. If gh auth status is read-only and shouldn't
have been in deny, the human can decide to update the deny list manually.
F. Cross-cutting lessons
- (Anything that didn't fit elsewhere — e.g. "the friction log should also capture sub-agent
cycle counts; consider richer details in
subagent_flag_persistent")
G. PR-eligible diffs summary
| Friction class | Cumulative count | Threshold | PR | Status |
permission_blocked::gh-auth | 4 | 3 | — | BLOCKED_BY_ANTI_PATTERN |
pacing_mismatch::deploy_verify | 2 | 3 | — | wait 1 more occurrence |
## 6. PR opening logic
After writing RETRO, for each `friction_class` where `count ≥ threshold` AND `pr_status == "none"`
AND not flagged by anti-pattern:
1. **Clone the skill_repo locally** to a temp dir if not already cloned (use the user's
existing local clone if you can find it under `~/code/` or `~/`).
2. **Create a new branch**: `iterate/<friction-class-slug>` (slugify the class).
3. **Apply the proposed diff** to SKILL.md.
4. **Self-review the diff** — check anti-patterns one more time before committing.
5. **Commit** with a message like:Address friction class: <friction-class>
Observed N times across M runs. Evidence: <one-line summary>.
See RETRO-<date>.md for full justification.
Co-authored-by: /iterate retrospective
6. **Push the branch**: `git push -u origin iterate/<friction-class-slug>`.
7. **Open the PR** via `gh pr create` — body written to a temp file, includes:
- The RETRO report excerpt for this friction class
- The proposed diff
- A note: "This PR was opened by `/iterate` after N occurrences across M runs. Review the
evidence in the RETRO report before merging. **Do not auto-merge.**"
8. **Update the state file**: set `pr_status` to `"open"`, append the PR URL to `pr_history`.
**One PR per friction class** until that PR is merged or closed. If `pr_status` is already
`"open"`, do NOT open another PR for the same class — wait for the human to act.
If the user does not have push access to the skill_repo (e.g. third-party using a skill they
don't own), gracefully fall back: **create a GitHub issue** on the skill_repo instead, with
the proposed diff in the issue body. Note the fallback in the RETRO report.
## 7. Anti-patterns — what /iterate must NEVER do
- ❌ Auto-merge any PR
- ❌ Propose removing or weakening `deny:` entries
- ❌ Propose skipping hooks, force-push, or any safety bypass
- ❌ Propose relaxing red lines / non-negotiable rules in the target SKILL.md
- ❌ Open multiple PRs for the same friction class while one is open
- ❌ Modify any file outside the skill's own SKILL.md and adjacent docs
- ❌ Run `bash` commands inside the retro sub-agent (sub-agent is read-only)
- ❌ Treat `safety_intentional` events as friction
- ❌ Iterate on yourself silently — if /iterate's own SKILL.md is the target, refuse and tell
the user (avoid recursion)
## 8. Invocation
Three forms:
**A. Target skill auto-hands-off** (preferred — set up in target's frontmatter / final step):/iterate devloop
The target skill calls this at the end of its run; the current `pwd` is the working directory.
**B. User-invoked after a target run**:/iterate devloop
Same as A; the user manually invokes it.
**C. User-invoked with explicit working dir**:/iterate devloop --working-dir /path/to/project
If invoked with no args, ask the user which skill to iterate on.
## 9. Output summary
After running, print one short message to the user:
Retrospective for /<skill> complete.
Report: <abs-path-to-RETRO-YYYY-MM-DD.md>
State: .iteration-state.json updated (<N> friction classes tracked)
PRs: <count> opened this run · <urls if any>
Blocked: <count> diffs blocked by anti-pattern (see report)
Review the report; the PRs (if any) are waiting for your approval.
Do NOT print the full report contents — point at the file.
## 10. Known limitations / future extensions
- One target skill per invocation (no batch retro across skills)
- Cross-repo learning is intentionally off — friction in project A is not used to inform skill
changes from project B (each project's state file is independent)
- Sub-agent is read-only and may miss patterns that require running diagnostics
- PR description is auto-generated; complex friction may warrant manual PR authoring
- No automatic rollback if a merged PR turns out to have regressed the skill — the next
iteration will catch it, but a regression is possible in the gapDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

