improve-loop
Skill1 starsChanged 4 days agoMITView on GitHub
Work through docs/STORIES.md one story at a time - plan, build, test, run and look, compare, fix, commit - until a milestone is done, unattended if needed. Use when the user says "keep going", "work through the backlog", "build M1", "make it match the reference", or wants an autonomous build loop.
7 other projects use a version of this, 3 of them edited.
Adopted by
Most recently taken up by
- morochena/skillstheir own version, first seen Nov 15, 2026
- Stijnus/dsh-rev-engedited, first seen Nov 8, 2026
- daveebbelaar/bawaedited, first seen Nov 8, 2026
- daveebbelaar/bamaedited, first seen Nov 1, 2026
- maxvyshniakov/improve-looptheir own version, first seen Oct 13, 2026
- zircote/improvertheir own version, first seen Oct 11, 2026
Used with
Projects with it also use app-brief, design-from-app and 6 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.
StijnusSkillapp-brief
One-page brief (docs/BRIEF.md) for a new macOS app, written before any code. Use when the user has an app idea, wants to replace an app they pay for, or the research and clone skills are done.
Also in 3 projects that use this
StijnusSkilldesign-from-app
Rebuild the look of an app the user likes as a native SwiftUI design kit, by measuring its screenshots (sizes, spacing, type, colors, icons), building its parts, and comparing pixel by pixel until they match. Use when the user names an app whose look they want, shares screenshots of one, or says "make it look like X".
Also in 3 projects that use this
launchapp-devSkilllayout-grid
Define responsive layout grid systems with columns, gutters, margins, and breakpoint behavior.
Also in 3 projects that use this
timeplus-ioSkillbuild-and-verify
Build, compile, run server/client/cluster, execute unit/stateless/SQL tests, verify results, and troubleshoot build/test failures. Make sure to use this skill whenever the user mentions building, compiling, ninja, cmake, running tests, test failures, starting the server, or pre-commit checks, even if they just say 'it doesn't build' or 'the test broke'.
Also in 3 projects that use this
CrystalPlatformsSkillagent-cli
Design and audit CLIs that AI agents (Claude Code, Codex, automated pipelines) consume. Applies ten agent-native principles in two tiers — Tier 1 table stakes (non-interactive default, structured output, errors that enumerate, safe retries, bounded responses) and Tier 2 compounding (cross-CLI vocabulary, three-layer introspection, async-aware execution, persistent profiles, two-way I/O) — with a Blocker / Friction / Optimization severity rubric across six command classes (read, mutate, stream, bootstrap, async, config). Use when building, reviewing, or specifying a CLI for agent invocation, mentions argparse, click, cobra, clap, commander, yargs, oclif, thor, agent-friendly or agent-native CLI design, --json output, exit codes, idempotent commands, --wait flags, agent-context introspection, persistent profiles, --deliver routing, --force bypass, vocabulary consistency, or repos with cli.py, main.go, src/cli.rs, bin/<tool>. Skip general shell scripting and human-only TUIs.
Also in 3 projects that use this
bborok1234Skilldesign-kit
새 프로젝트/화면의 디자인 시스템을 프로덕션급으로 빠르게 세우고(부트스트랩), 이미 만든 UI의 퀄이 안 잡힐 때 진단→교정하고, AI 슬롭 없이 폴리싱하는 개인 디자인 게이트. "디자인 시스템 잡아줘", "랜딩/UI 만들어", "슬롭 잡아줘", "이 화면 폴리싱", "퀄리티가 안 잡혀/디자인 고쳐줘/왜 싸구려 같지", 새 프론트엔드 시작 시 적용. 미학(팔레트·폰트·정체성)은 인터뷰로 함께 설계하고, 시스템 구성법·판단룰·안티슬롭·진단교정·빌드루프는 프로젝트 무관하게 재사용.
Also in 3 projects that use this
- +1 more from Stijnus
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 3
- daveebbelaar/bama★ 1.7k53% same
- daveebbelaar/bawa★ 1746% same
- Stijnus/dsh-rev-eng★ 152% same
Wrote their own version · 4
- morochena/skills★ 1same name
- maxvyshniakov/improve-loop★ 0same name
- skipstery/improve-loop★ 0same name
- zircote/improver★ 0same name
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.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agents-mdSkill
- app-iconSkill
- buildSkill
- cloneSkill
- debugSkill
- design-systemSkill
- docker-optimizeSkill
- mac-appSkill
- mac-designSkill
- product-briefSkill
- quality-barSkill
- refactorSkill
- researchSkill
- reviewSkill
- start-hereSkill
- stop-overthinkingSkill
- ui-directorSkill
- user-storiesSkill
- ux-designSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 3 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 7 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Stop after the milestone the user named, or after the current milestone if they named none.
- Very specific: line 24
If the story adds a screen, an action, or words and has no UX: block yet, call the Skill tool with ux-design first.
- Distinctive: line 27
Write two to five lines: which files change, what already exists that you will reuse, which data fields are new, which command and shortcut …
- Very specific: line 33
Follow the build skill (tests first), the story's UX: block, CONSTRAINTS.md and DESIGN-SYSTEM.md if the project has them, and the …
- Very specific: line 39
Run the tests and the checks in CONSTRAINTS.md.
- Distinctive: line 45
Look at your screenshots and the story's reference screenshots side by side.
- Very specific: line 59
No reference screenshot (no app was cloned)?
- Very specific: line 92
When the last story of a milestone is done, call the Skill tool with review on the milestone's code before you start the next one.
“Common” is measured: kept by at least 6 in 10 of the 7 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
Improve loop
One pass through the loop takes one story from todo to done:
pick story -> plan -> test and code -> run and look -> compare -> fix -> commit -> update STORIES.mdStop after the milestone the user named, or after the current milestone if they named none. Then report.
1. Pick
Open docs/STORIES.md. Take the first todo story in the current
milestone whose dependencies are done. Set it to doing.
2. Plan
If the story adds a screen, an action, or words and has no UX: block
yet, call the Skill tool with ux-design first.
Write two to five lines: which files change, what already exists that you will reuse, which data fields are new, which command and shortcut it adds, which screen shows it. A new stored field gets a default value, so existing data keeps loading.
3. Test and code
Follow the build skill (tests first), the story's UX: block, CONSTRAINTS.md and DESIGN-SYSTEM.md if the
project has them, and the platform's skill (mac-app and mac-design, or ui-director). Keep
each file small enough to read in one go.
4. Test, run and look
Run the tests and the checks in CONSTRAINTS.md; a failure whose cause isn't obvious goes to
debug. Run the app with sample data, and capture the screens the story touches, light and dark,
the way the platform's skill says (mac-app or ui-director).
5. Compare
Look at your screenshots and the story's reference screenshots side by side. Write down the differences that matter, in this order:
- Missing or wrong behavior from the acceptance criteria.
- Words and flow: names, surface, and states that differ from the
UX:block ordocs/GLOSSARY.md. - Layout: wrong column, wrong order, missing element, off-grid spacing.
- Hierarchy: what is biggest, boldest, first.
- Spacing and alignment.
- Color and details.
The goal is the same structure and behavior, built from the platform's own controls. It is not a pixel copy. When the reference uses a custom control and the platform has a native one, use the native one.
No reference screenshot (no app was cloned)? Compare against the story's
acceptance lines and the design skill's rules (mac-design or ui-director) instead.
Capture only the screens a story touches, and every screen at the end of each milestone.
Fix, rebuild, and compare again. Three rounds per story at most. If it still
does not match, set the story to todo again with a note that says what is
blocking, and move on.
6. Commit and record
git add -A
git commit -m "Complete tasks with Command-Return"Set the story to done in docs/STORIES.md and commit that with the code.
One story per commit, so any story can be reverted on its own.
7. Report
At the end of the loop, report to the user:
- Stories done, with one line each and the evidence: the passing test output and the screenshots that show them.
- Stories blocked, and why.
- Anything the user should try by hand (shortcuts, drag and drop).
- The next story in line.
Then open the new build so the user can try it.
Milestone check-in
When the last story of a milestone is done, call the Skill tool with review on the milestone's code before you start the next one. Unattended, fix its Must fix findings, and leave the rest in docs/REVIEW.md for the user.
A story that fixes a bug follows debug, including its entry in docs/FIXLOG.md, which the
check-in reads.
Running it unattended
The loop works with no one watching, because every step checks itself: the build, the tests, the screenshots, the acceptance criteria. To let it run longer, start it with a clear limit ("finish M2, then stop"), make sure the tree is committed before you start, and never let it touch the user's real database. Each story is a separate commit, so the user can review the history in the morning and revert anything they do not like.
Done when every story in the milestone is done or named in the report as
blocked with a reason, each done story has its own commit, and the user
has the report.
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
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.

