agentleFS
AntaresYuanAntaresYuan/claude-skill-iterate/SKILL.md

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

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 AzureSkill

    test

    Also in 4 projects that use this

  • sunnyclinches44Skill

    explain

    Explains code using real-world analogies and ASCII diagrams

    Also in 3 projects that use this

  • NVIDIASkill

    research

    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 AzureSkill

    design

    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

  • MicrosoftSkill

    writing-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

  • AWSSkill

    retro

    Conduct a retrospective on a coding session.

    Also in 3 projects that use this

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
  1. Distinctive:

    If neither is provided, ask the user via AskUserQuestion:

    line 34
  2. Very specific:

    If iteration.enabled is missing or false, exit with a one-line note: "Skill <name> has not opted into iteration.

    line 53
  3. Very specific:

    After writing RETRO, for each friction_class where count ≥ threshold AND pr_status == "none" AND not flagged by anti-pattern:

    line 265
  4. Distinctive:

    If the user does not have push access to the skill_repo (e.g.

    line 293
  5. Distinctive:

    If invoked with no args, ask the user which skill to iterate on.

    line 331
  6. Distinctive:

    After running, print one short message to the user:

    line 335
  7. Distinctive:

    Do NOT print the full report contents — point at the file.

    line 348
  8. Distinctive:

    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 …

    line 357

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Target skill name (e.g. devloop). Either passed as argv, or you can read the most recent skill invocation from the conversation context.
  2. 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 dir

If 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):

TypeWhen to logRequired details fields
permission_blockedA bash/tool permission prompt firedcmd, outcome
permission_thrashSame command blocked ≥2 times in one runcmd, count
retryA command had to be re-runcmd, attempts, reason
pacing_mismatchScheduled wait was too short or too longstep, scheduled_wait_s, actual_ready_s
subagent_flag_persistentReviewer rejected ≥2 cyclesverdict_cycles, final_verdict
unexpected_stateReality didn't match assumption (e.g. stale git state)assumption, actual
stop_condition_hitA STOP condition triggeredwhich, recoverable
safety_intentionalA deny / safety mechanism kicked in correctlycmd, 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:

  1. Skill name: <name>
  2. Current SKILL.md at ~/.claude/skills/<name>/SKILL.md (Read it)
  3. Friction log: <path>/LOOP-FRICTION.jsonl
  4. Run log: <path>/LOOP-LOG.md
  5. State file (prior runs' accumulators): <path>/.iteration-state.json
  6. 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 line

Justify 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_intentional events — those are guardrails working, not friction

If a proposed change touches any of the above, mark it BLOCKED_BY_ANTI_PATTERN and 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 classCumulative countThresholdPRStatus
permission_blocked::gh-auth43—BLOCKED_BY_ANTI_PATTERN
pacing_mismatch::deploy_verify23—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 gap

Download now (ZIP)

Does 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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.