Agent skill

Looper

by ksimback in ksimback/looper

Scaffold a well-designed agent loop with best-practice coaching and a cross-model review council.

MITAuto-check: notesAI & LLM Engineering

Install Looper

skills CLI
$ npx skills add ksimback/looper --skill looper -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ksimback/looper looper --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
looper
GitHub stars
710
Token cost
~2.7k tokens
SKILL.md length
1,070 words
Files
78 (incl. scripts, references)
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

Scaffold a well-designed agent loop with best-practice coaching and a cross-model review council.

  • Works in 11 steps: Resolve the target path and optional… → Load the relevant rubric only when… → Interview in seven stages: goal,… → …
  • The user wants to design
  • SKILL.md covers Workflow, Template Mode, File Rules and Helper Python, plus 3 more sections
  • Runs Python scripts from its folder

What it does

Looper is an agent skill from ksimback/looper. Scaffold a well-designed agent loop with best-practice coaching and a cross-model review council. Use when the user wants to design, build, or set up an agent loop, iterative agent workflow, self-review loop, LLM-as-judge loop, multi-model council, reviewer/judge gate, or /goal-style looping process. Start from a named pattern template (security-scan, code-review, bug-hunt, docs-sync, research-synthesis) or from a blank interview. Guide goal refinement, typed verification criteria, reviewer and judge selection…

Its SKILL.md is about 2.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 84 other files, including scripts and reference files (for example `.github/workflows/ci.yml`, `CHANGELOG.md` and `CONTRIBUTING.md`).

It sits in AI & LLM Engineering, covering Autonomous loops, LLM evaluation and Security review. The repository describes itself as: Design visual, review-gated agent loops for Claude Code before you run them. The licence is MIT.

When your agent uses it

  • The user wants to design
  • Set up an agent loop
  • Iterative agent workflow
  • Self-review loop

Example prompts

  • “/looper”

Requirements

  • Python 3
  • Pre-approved tools (allowed-tools): Read, Write, Bash

Workflow steps

11 steps, taken from the first numbered list in SKILL.md.

  1. Resolve the target path and optional --template from the
  2. Load the relevant rubric only when entering that stage
  3. Interview in seven stages: goal, verification, host model, council,
  4. Critique each stage before accepting it. Prefer concrete alternatives over
  5. Keep reviewer and judge roles distinct. A reviewer writes notes. A judge
  6. Require multiple termination guards: max_iterations, a revision cap on
  7. Before any cross-vendor council member is selected, state what context will
  8. Show an ASCII flow preview of the planned loop and ask for confirmation
  9. Emit these files into the target
  10. After writing loop.yaml, resolve the helper Python (see Helper Python
  11. Ask whether the user wants to run the loop now in this session. If yes,

What it can do on your machine

Read from SKILL.md and the folder at commit 8a9b798. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Write
    • Bash

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python, from the files we listed), which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Looper loads about 2.7k tokens when it runs, and up to ~4.7k if it reads all its reference files. Until then it costs about 182 tokens; SKILL.md has 1,070 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~182
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~4.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:120
    - Default redaction globs are `.env`, `.env.*`, `secrets/**`, and `**/*.key`.
  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Read, Write, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from ksimback/looper at commit 8a9b798, republished under its MIT licence (© ksimback). 1,070 words, ~2,693 tokens.

Download SKILL.mdSave it as .claude/skills/looper/SKILL.md (or your agent's skills folder). This skill also uses 77 other files; get the full folder from GitHub.
name
looper
description
Scaffold a well-designed agent loop with best-practice coaching and a cross-model review council. Use when the user wants to design, build, or set up an agent loop, iterative agent workflow, self-review loop, LLM-as-judge loop, multi-model council, reviewer/judge gate, or /goal-style looping process. Start from a named pattern template (security-scan, code-review, bug-hunt, docs-sync, research-synthesis) or from a blank interview. Guide goal refinement, typed verification criteria, reviewer and judge selection, privacy boundaries, termination guards, no-progress stops, and lightweight observability, then emit a RUN_IN_SESSION.md handoff prompt plus portable loop.yaml, loop.resolved.json, LOOP.md, and run-loop.py.
allowed-tools
Read, Write, Bash
disable-model-invocation
true
argument-hint
[target-dir] [--template <name>]

Looper

Use Looper as a loop design coach and scaffolder. During design, interview, critique, validate, and write files. After emission, offer to run the loop in the current session using RUN_IN_SESSION.md; keep run-loop.py as the advanced external runner.

Workflow

  1. Resolve the target path and optional --template <name> from the /looper arguments. If no target is given, use ./looper-output. If the target contains an existing loop.yaml, treat the task as an edit/resume instead of a fresh scaffold. If a template was requested, follow Template Mode below instead of the blank-slate interview in step 3.
  2. Load the relevant rubric only when entering that stage:
    • Goal stage: references/goal-rubric.md.
    • Verification stage: references/verification-rubric.md.
    • Council stage: references/council-rubric.md.
    • Control stage: references/control-rubric.md.
    • Model detection or privacy details: references/model-detection.md.
  3. Interview in seven stages: goal, verification, host model, council, gates/control, confirmation flow preview, emit/run option. In the control stage, cover execution boundary, isolation, no-progress signals, state, and run logging.
  4. Critique each stage before accepting it. Prefer concrete alternatives over vague warnings. Push weak goals toward outcome, scope, context, and done state. Push weak verification toward programmatic checks first, then judge rubrics, then human signoff.
  5. Keep reviewer and judge roles distinct. A reviewer writes notes. A judge returns a structured verdict. revise_until_clean must name a judge member or human as verdict_source.
  6. Require multiple termination guards: max_iterations, a revision cap on each gate, a no-progress stop, and either a budget cap or an explicit human stop point.
  7. Before any cross-vendor council member is selected, state what context will leave the user's machine, which CLI receives it, which redaction globs apply, and that both execution paths require first-send consent.
  8. Show an ASCII flow preview of the planned loop and ask for confirmation before final emission. Optimize for Claude Code CLI readability.
  9. Emit these files into the target:
    • loop.yaml
    • loop.resolved.json
    • LOOP.md
    • RUN_IN_SESSION.md
    • run-loop.py
    • loop-workspace/
    • README.md
  10. After writing loop.yaml, resolve the helper Python (see Helper Python below) and run: "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py compile <target>/loop.yaml --out <target>/loop.resolved.json --render <target>/LOOP.md --session-prompt <target>/RUN_IN_SESSION.md Then run "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml and relay the findings: fix any error[...] before continuing (the spec would not behave as written), and surface warning[...] lines to the user as design coaching they may accept or address.
  11. Ask whether the user wants to run the loop now in this session. If yes, follow RUN_IN_SESSION.md directly as the active task. If no, explain that the same file is the easy restart path and run-loop.py is available for advanced external execution.

Template Mode

The pattern library lives at ${CLAUDE_SKILL_DIR}/templates/loops/ — one directory per template containing a complete, compilable loop.yaml (with {{PLACEHOLDER}} tokens marking project-specific slots), a README.md (use-when, placeholder table, customization notes), and optionally scripts/ with helper checkers. The catalog index is templates/loops/README.md.

A template is a pre-answered interview, not a bypass of design review:

  1. If the target directory already contains a loop.yaml, the edit/resume rule in step 1 wins: do not overwrite it with a template. Say the directory already has a loop and ask the user to pick an empty target or confirm they want it replaced before continuing.
  2. If --template has no name, an unknown name, or the user asks what is available, show the catalog table (template + use-when) and let them pick.
  3. Read the template's loop.yaml and README.md. Use the template as the seed instead of a blank spec.
  4. Run a compressed interview in place of the seven blank-slate stages: ask for each {{PLACEHOLDER}} slot named in the template README, run the host-model stage against detected CLIs (detect-models) and swap host / council invocations to what is actually installed and authed, then confirm target and workspace paths.
  5. Everything after the interview still applies unchanged: critique each pre-filled stage against its rubric (step 4), the structural rules (steps 5–8) including the cross-vendor egress statement, the ASCII flow preview, confirmation, emission, and compile.
  6. Never emit while any {{ token remains in loop.yaml. The compiler prints looper: warning: unresolved template placeholders remain ... for this case — treat that warning as a blocker, not advice.
  7. At emission, copy the template's scripts/ directory (when present) into <target>/scripts/ alongside the standard emitted files, before running compile.
Show full SKILL.md (380 more words)Show less

File Rules

  • Write argv arrays, never shell command strings, for all model and check invocations.
  • Do not write API keys, access tokens, passwords, or CLI auth material into loop.yaml, loop.resolved.json, or model registries.
  • Default redaction globs are .env, .env.*, secrets/**, and **/*.key.
  • Keep loop.yaml human-readable and commented where useful. The emitted runner reads only loop.resolved.json.
  • Keep RUN_IN_SESSION.md as the default/easy execution handoff. It is meant for the current LLM session or a future pasted prompt.
  • Copy templates/run-loop.py exactly unless the user explicitly asks to edit the external runner contract.

Helper Python

The installer creates a private venv inside the skill directory. Its Python lives at .venv/bin/python on macOS/Linux and .venv/Scripts/python.exe on Windows. Shell state does not persist between commands, so prefix every helper invocation below with this resolution (works in POSIX shells and Git Bash on Windows):

bash
LOOPER_PYTHON="${CLAUDE_SKILL_DIR}/.venv/bin/python"; [ -x "$LOOPER_PYTHON" ] || LOOPER_PYTHON="${CLAUDE_SKILL_DIR}/.venv/Scripts/python.exe"; [ -x "$LOOPER_PYTHON" ] || { LOOPER_PYTHON=python3; "$LOOPER_PYTHON" -c "" >/dev/null 2>&1 || LOOPER_PYTHON=python; }

The final fallback executes the candidate rather than just locating it: on Windows, python3 on PATH is often the Microsoft Store alias stub, which exists but cannot run scripts. If no candidate can execute -c "", tell the user to rerun the Looper installer (it creates the venv).

Helper Scripts

Each command below assumes the Helper Python resolution is prefixed in the same shell invocation:

  • Detect model CLIs: "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py detect-models --write
  • Register a custom CLI (quote the whole invocation if it contains flags): "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py register-model <id> --invoke "<cmd> [args...]"
  • Compile and render: "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py compile <target>/loop.yaml --out <target>/loop.resolved.json --render <target>/LOOP.md --session-prompt <target>/RUN_IN_SESSION.md
  • Lint against the design-rubric anti-patterns (add --strict to fail on warnings, --json for tooling): "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml
  • Render only the in-session handoff: "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py session-prompt <target>/loop.resolved.json --out <target>/RUN_IN_SESSION.md

Confirmation Flow Preview

Use this shape and customize labels:

text
+--------------------------------+
| 1. Goal + context              |
| read sources                   |
+--------------------------------+
               |
               v
+--------------------------------+
| 2. Draft plan.md               |
| state -> state.json            |
+--------------------------------+
               |
               v
+--------------------------------+
| 3. Plan gate                   |
| verdict: reviewer-1            |
+--------------------------------+
               | needs work -> revise <= 3 -> step 2
               | pass
               v
+--------------------------------+
| 4. Write delivery-N.md         |
| log -> run-log.md              |
+--------------------------------+
               |
               v
+--------------------------------+
| 5. Delivery gate               |
| verdict: reviewer-1            |
+--------------------------------+
               | needs work -> revise <= 3 -> step 4
               | pass
               v
+--------------------------------+
| 6. Final output                |
| all gates clean                |
+--------------------------------+

Stops: pass gates | max 12 iterations | no progress x2 | budget 30m, $5.0, 2000000 tokens

Emit Checklist

  • The goal has a clear outcome, scope boundary, context sources, and done state.
  • Verification criteria are typed as programmatic, judge, or human.
  • At least one criterion is not purely vibe-based unless the user explicitly accepts that risk.
  • Each revise_until_clean gate has a valid verdict_source.
  • Every external invocation is an argv array with a timeout.
  • Cross-vendor egress is scoped, redacted, and consent-gated.
  • loop_control has iteration, revision, no-progress, and wall-clock or budget caps.
  • Execution boundary and isolation are explicit, even when the choice is the current workspace.
  • Observability names a run-log.md and state.json path.
  • loop.resolved.json, LOOP.md, and RUN_IN_SESSION.md compile successfully before handoff.

© ksimback, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 77 other files (scripts, references) in the repository root of ksimback/looper.

  • SKILL.md
  • .gitattributes
  • .github/workflows/ci.yml
  • .gitignore
  • CHANGELOG.md
  • CONTRIBUTING.md
  • LICENSE
  • README.md
  • RUNNER-CONTRACT.md
  • agents/openai.yaml
  • commands/looper.md
  • conformance/check_runner.py
  • examples/ai-workflow-mapping/LOOP.md
  • examples/ai-workflow-mapping/README.md
  • … and 64 more

Open the folder on GitHubat commit 8a9b798

Compare with similar skills

Looper next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Looper compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Looper this skillksimback/looper710—~2.7kAutomated safety check: NotesMIT
Agents Best PracticesDenisSergeevitch/agents-best-practices2.4k—~7.4kAutomated safety check: PassMIT
Loop Architectfabricioctelles/skills106—~2.1kAutomated safety check: NotesMIT
Clawpathy AutoresearchClawBio/ClawBio1.2k—~1.4kAutomated safety check: PassMIT
Evalagentevals-dev/agentevals162—~904Automated safety check: PassApache-2.0
Autocontext Knowledge Creatorgreyhaven-ai/autocontext1.3k—~964Automated safety check: PassApache-2.0

Similar skills

  • Agents Best Practices

    DenisSergeevitch/agents-best-practices

    A skill your agent uses when designing, generating an MVP blueprint for, auditing, troubleshooting, refactoring, or explaining an agentic harness for any domain.

    2.4k GitHub stars~7.4k tokensUpdated 4 days ago
    AI & LLM EngineeringAuto-check passed
  • Loop Architect

    fabricioctelles/skills

    Design well-structured agent loops with best-practice coaching and cross-model review gates before you run them.

    106 GitHub stars~2.1k tokensUpdated 5 days ago
    Agent WorkflowsAuto-check: notes
  • Clawpathy Autoresearch

    ClawBio/ClawBio

    Eval-driven skill tuning. An agent skill from ClawBio/ClawBio.

    1.2k GitHub stars~1.4k tokensUpdated today
    AI & LLM EngineeringAuto-check passed
  • Eval

    agentevals-dev/agentevals

    Evaluate and score agent behavior against a golden reference.

    162 GitHub stars~904 tokensUpdated today
    AI & LLM EngineeringAuto-check passed
  • Autocontext Knowledge Creator

    greyhaven-ai/autocontext

    Runs the `autoctx` CLI to improve an approach to a task over several generations, score or refine a single output and inspect what a run produced.

    1.3k GitHub stars~964 tokensUpdated 2 days ago
    AI & LLM EngineeringAuto-check passed
  • Agent Eval

    ericrisco/rsc-harness

    A skill your agent uses when measuring whether an LLM or agent system actually got better and gating merges on it: golden sets, fixing an inflated LLM-as-judge, scoring RAG (faithfulness, contextual…

    174 GitHub stars~3.2k tokensUpdated yesterday
    AI & LLM EngineeringAuto-check passed

Questions about Looper

What does Looper do?

Scaffold a well-designed agent loop with best-practice coaching and a cross-model review council. Looper is an agent skill from ksimback/looper. Scaffold a well-designed agent loop with best-practice coaching and a cross-model review council.

When should I use Looper?

Looper fits situations like: the user wants to design; set up an agent loop; iterative agent workflow; self-review loop.

How do I install Looper in Claude Code?

Run `npx skills add ksimback/looper --skill looper -a claude-code`. Or copy the skill folder (the ksimback/looper repository) into .claude/skills/looper in your project. Claude Code loads it when a task matches its description.

How do I install Looper in Codex?

Run `npx skills add ksimback/looper --skill looper -a codex`. Or copy the skill folder (the ksimback/looper repository) into .agents/skills/looper in your project. Codex loads it when a task matches its description.

Can I use Looper in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ksimback/looper --skill looper -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/looper, .gemini/skills/looper, .github/skills/looper and .opencode/skills/looper in your project.

What does Looper need to run?

Going by SKILL.md and its folder, Looper needs Python for the scripts in its folder. Our summary lists: Python 3. Its frontmatter pre-approves these tools: Read, Write, Bash.

Does Looper access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Looper safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file; pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Looper use?

Looper is published under the MIT licence (from the LICENSE file in the skill folder). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Looper use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2k tokens, read only when the agent opens those files.

What are the alternatives to Looper?

Skills that share tags, products or a category with Looper: Agents Best Practices (DenisSergeevitch/agents-best-practices, 2.4k stars), Loop Architect (fabricioctelles/skills, 106 stars), Clawpathy Autoresearch (ClawBio/ClawBio, 1.2k stars) and Eval (agentevals-dev/agentevals, 162 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Looper?

ksimback (a GitHub user) maintains it in ksimback/looper, which has 710 GitHub stars. The repository was last updated on August 9, 2026.

Source: ksimback/looper on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.