How do I install the Retrofit Project skill?

Run npx skillmds@latest add joseluisamado/retrofit-project in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Retrofit Project safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Retrofit Project?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Retrofit Project free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Retrofit Project?

joseluisamado (@joseluisamado) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Retrofit Project by joseluisamado — Agent Skill

Name: Retrofit Project
Author: joseluisamado

Retrofit Project

Reshape an existing project to the bootstrap-project skill standard without losing content, history, or working code. Walks the repo, classifies every file as missing / present-template-shape / present-bespoke / empty-placeholder, asks the same five spec questions as bootstrap-project (plus a content-strategy question), reshapes the docs quintet, backfills CHANGELOG from git history, moves files with reference-updating, and marks the project with `.bootstrap-meta.yaml` mode: retrofit. Use this when the user says "retrofit this project", "bring this repo up to the bootstrap-project standard", "reshape this to skill shape", or invokes /retrofit-project. Like bootstrap-project, it is a finalizer — it assumes the analysis conversation has happened in this session and extracts spec from context. Unlike bootstrap-project, it does NOT refuse on non-empty projects — that is its entire reason to exist. Do NOT use this for: greenfield projects (use /bootstrap-project instead); projects without a `.git/` directory (the

joseluisamado Updated Sep 17, 2026

File contents

retrofit-project

This skill produces the same end-state as bootstrap-project (same templates, same canonical shape) on a repo that already has content. The hard part is not the writing — it is the negotiation with what is already there: preserving facts under reshape, finding canonical homes for bespoke content, moving files without breaking references, and being explicit about what was deleted and why.

The full playbook lives in INSTRUCTIONS.md. Read it when the skill is invoked. The short version:

Refuse if invoked cold or on a non-git repo. Need analysis context and a git safety net.
Inventory diff. Walk every always-present file from the bootstrap spec; classify as missing / present-template-shape / present-bespoke / empty-placeholder. Print the table.
Extract spec from conversation — same fields as bootstrap-project (project_name, principles, milestones, stack_profile, deploy_model, audience, license, add-ons), plus content-preservation strategy.
Confirm the plan in one block: what gets written, rewritten, moved, deleted. Wait for "go."
Execute in this order: (a) write missing always-present files; (b) rewrite bespoke docs to canonical shape, preserving content; (c) move files with reference-updating sub-passes; (d) delete with explicit justification; (e) backfill CHANGELOG from git tag + git log + any existing PROGRESS versioning table; (f) write .bootstrap-meta.yaml with mode: retrofit.
Generate BOOTSTRAP-MANIFEST.md with the richer retrofit shape: files written / rewritten / moved / deleted / preserved unchanged.
Final compliance review. Cross-ref check, no-clobber check, no-forbidden-file check. Print the "next 30 minutes" punch list.

The skill shares templates/ with bootstrap-project — same renderers, same conditional flags. Don't duplicate.

The skill never deletes silently. Every deletion appears in the confirmation block before execution and in the manifest after.

For background on why retrofits are not just "bootstrap on a dirty directory," see patterns/why-retrofit-is-different.md.

---name: retrofit-projectdescription: Reshape an existing project to the bootstrap-project skill standard without losing content, history, or working code. Walks the repo, classifies every file as missing / present-template-shape / present-bespoke / empty-placeholder, asks the same five spec questions as bootstrap-project (plus a content-strategy question), reshapes the docs quintet, backfills CHANGELOG from git history, moves files with reference-updating, and marks the project with `.bootstrap-meta.yaml` mode: retrofit. Use this when the user says "retrofit this project", "bring this repo up to the bootstrap-project standard", "reshape this to skill shape", or invokes /retrofit-project. Like bootstrap-project, it is a finalizer — it assumes the analysis conversation has happened in this session and extracts spec from context. Unlike bootstrap-project, it does NOT refuse on non-empty projects — that is its entire reason to exist. Do NOT use this for: greenfield projects (use /bootstrap-project instead); projects without a `.git/` directory (the ---# retrofit-projectThis skill produces the same end-state as `bootstrap-project` (same templates,same canonical shape) on a repo that already has content. The hard part isnot the writing — it is the *negotiation* with what is already there:preserving facts under reshape, finding canonical homes for bespoke content,moving files without breaking references, and being explicit about what wasdeleted and why.The full playbook lives in [`INSTRUCTIONS.md`](./INSTRUCTIONS.md). Read itwhen the skill is invoked. The short version:1. **Refuse if invoked cold or on a non-git repo.** Need analysis context and a git safety net.2. **Inventory diff.** Walk every always-present file from the bootstrap spec; classify as missing / present-template-shape / present-bespoke / empty-placeholder. Print the table.3. **Extract spec from conversation** — same fields as bootstrap-project (project_name, principles, milestones, stack_profile, deploy_model, audience, license, add-ons), plus content-preservation strategy.4. **Confirm the plan** in one block: what gets written, rewritten, moved, deleted. Wait for "go."5. **Execute** in this order: (a) write missing always-present files; (b) rewrite bespoke docs to canonical shape, preserving content; (c) move files with reference-updating sub-passes; (d) delete with explicit justification; (e) backfill CHANGELOG from `git tag` + `git log` + any existing PROGRESS versioning table; (f) write `.bootstrap-meta.yaml` with `mode: retrofit`.6. **Generate `BOOTSTRAP-MANIFEST.md`** with the richer retrofit shape: `files written / rewritten / moved / deleted / preserved unchanged`.7. **Final compliance review.** Cross-ref check, no-clobber check, no-forbidden-file check. Print the "next 30 minutes" punch list.The skill **shares `templates/`** with `bootstrap-project` — same renderers,same conditional flags. Don't duplicate.The skill **never deletes silently**. Every deletion appears in theconfirmation block before execution and in the manifest after.For background on why retrofits are not just "bootstrap on a dirtydirectory," see [`patterns/why-retrofit-is-different.md`](./patterns/why-retrofit-is-different.md).

Frequently asked questions