SkillInstalls cleanly
Test whether your README works
fresh-clone
Free MIT skill that copies your project to a temporary folder, follows the README setup steps like a new user, and reports which steps fail and why.
- Works with
- Claude Code
- Good for
- Web developers, Build an app
What it does
A README's setup steps often stop working as a project changes: a script is renamed, a file moves, a new setting is needed. The owner rarely notices, because they never follow their own steps again.
fresh-clone makes a fresh git clone of the project in a temporary folder and follows the README as if it had never seen the project. The assistant writes the README's steps down as a checklist, then runs each command for real through a small timing script and marks it as working, misleading, broken, unclear or "needs a human". A bundled script also gathers facts from the project, such as which settings the code reads. It uses the git history to explain failures, for example when a script was renamed.
The report lists what to add, what to remove and what to fix in the project, and checks translated READMEs. Then it asks about each fix one at a time, applies only the ones you accept, and offers a pull request and a second test. The temporary copy is deleted at the end.
Example prompts
- "/fresh-clone"
- "Does my README still work?"
- "Would a new contributor get stuck setting this up?"
- "Clean up my README before I make this project public."
How to install
git clone https://github.com/vSkyfall/fresh-clone ~/.claude/skills/fresh-cloneHow to use it
In a project, type /fresh-clone or ask "does my README still work?". It runs the steps, shows a report, then asks about each fix one at a time.
Check it works
Run /fresh-clone in a project with a README. You should get a "fresh-clone report" with a table of steps and a "time to first run" line.
Common problems
- The skill isn't offered — it must sit in
~/.claude/skills/fresh-clone(or.claude/skills/fresh-clonein one project); start a new session — https://github.com/vSkyfall/fresh-clone - Steps that need a real API key or paid account are skipped — that is by design; they are marked as needing a human — https://github.com/vSkyfall/fresh-clone
- No clean-machine option — it is only offered when Docker is running — https://github.com/vSkyfall/fresh-clone
- Uncommitted changes are not tested — it clones the committed state of your project — https://github.com/vSkyfall/fresh-clone/blob/4aa16a78635ae6cfa7c1eb5a3d54236f3d5749d6/SKILL.md
Other assistants
- Codex: not listed in the README — https://github.com/vSkyfall/fresh-clone
- Gemini CLI: not listed in the README; not in the Gemini extensions gallery as of 2026-11-04 — https://github.com/vSkyfall/fresh-clone
What to watch out for
- It really runs the README's commands: the assistant turns the README into steps and scripts/run_step.sh runs each one with bash -c and a 300-second timeout, on your computer unless you pick the Docker option
- Install steps such as npm ci or pip install also run the project's own install scripts, so only test projects you trust on your computer
- On your computer, 'no sudo, no global installs, no curl | sh from other domains' are instructions in SKILL.md, not limits in the code
- Docker option: one ubuntu:24.04 container with network access, the clone copied in, steps run as root and it installs whatever the README says (Node, Rust and similar setup scripts); the clone, the fact script, the clone-URL and link checks still run on your computer
- It can start the app's servers in the background, which it says it stops at the end
- Fixes you accept are committed on a new branch (fresh-clone/readme-fixes); if you agree it pushes that branch and opens a pull request with your git and gh login
- Needs bash, git and perl; Docker and the gh CLI are optional
Licence and author
- Licence
- MIT
- Author
- vSkyfall
- Source code
- github.com/vSkyfall/fresh-clone
How we tested it
We installed it on an empty test computer on 4 Nov 2026. Installed and started in a clean test system. Not yet used in a real AI session.
The intake sandbox cannot run git clone install lines, so this test was done by hand. We did not run the skill on a project. Not yet used on real work.
Technical details of the test
- Date
- 4 Nov 2026
- Method
- Manual sandbox run on 2026-11-04 in a clean container (oexp-sandbox image) with no account: ran the README install line git clone https://github.com/vSkyfall/fresh-clone ~/.claude/skills/fresh-clone and checked that SKILL.md with its name and description is in place (commit 4aa16a7).
Checked again on 4 Nov 2026
Alternatives
- Playwright MCP — tests a running site in a browser
- Superpowers — general workflows for testing and debugging
- Docker Skills — helps put an app in a container, rather than test its README
FAQ
- Q: Will it change my current files? A: Not while testing; that happens in a temporary clone. Only fixes you accept are written, and they are committed on a new branch if you say yes.
- Q: Can it check someone else's project? A: Yes. The README shows asking it to check another GitHub project's install steps.
- Q: Is it safe to run on a project I don't trust? A: Not on your computer: it runs that project's setup commands. Choose the Docker option, which runs the steps in a throwaway container instead.
Sources
- github.com/vSkyfall/fresh-clone
- github.com/vSkyfall/fresh-clone/blob/4aa16a78635ae6cfa7c1eb5a3d54236f3d5749d6/SKILL.md
- github.com/vSkyfall/fresh-clone/blob/4aa16a78635ae6cfa7c1eb5a3d54236f3d5749d6/scripts/run_step.sh
- github.com/vSkyfall/fresh-clone/blob/4aa16a78635ae6cfa7c1eb5a3d54236f3d5749d6/references/clean-machine.md
- github.com/vSkyfall/fresh-clone/releases/tag/v1.0.0