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

How 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

Other assistants

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.

Test level

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