github-repo-finalizer
/github-repo-finalizer
Finalize a repo for GitHub: keep the final working version, remove obsolete V1/V2 folders and dead files with evidence, fix secrets, write a README grounded in the code, verify the app runs. Use for "clean up my repo", "delete old versions", "audit before pushing", "rewrite the README".
- Author
- MaherAbderrahim ↗
- Repository
- github-repo-finalizer ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 10
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/repo_audit.py, scripts/test_repo_audit.py
What it does and when to use it
Finalize a repo for GitHub: keep the final working version, remove obsolete V1/V2 folders and dead files with evidence, fix secrets, write a README grounded in the code, verify the app runs. Use for "clean up my repo", "delete old versions", "audit before pushing", "rewrite the README".
Triggers from the description
Original author description
Finalize a repo for GitHub: keep the final working version, remove obsolete V1/V2 folders and dead files with evidence, fix secrets, write a README grounded in the code, verify the app runs. Use for "clean up my repo", "delete old versions", "audit before pushing", "rewrite the README".
How it works
- Task boundaries
- Modes
- Hard safety rules (all modes)
- Workflow
- Example user prompts and how to respond
- Self-check before reporting
SKILL.md preview
---
name: github-repo-finalizer
description: >-
Finalize a repo for GitHub: keep the final working version, remove obsolete
V1/V2 folders and dead files with evidence, fix secrets, write a README
grounded in the code, verify the app runs. Use for "clean up my repo",
"delete old versions", "audit before pushing", "rewrite the README".
---
# GitHub Repo Finalizer
Transform an existing repository into a clean, professional, presentation-ready
GitHub repo: one coherent final implementation, a README grounded in reality,
verified to still run. The goal is **not** to delete as many files as possible —
it is to keep everything the final application needs and remove what
unnecessarily exposes intermediate development work.
## Task boundaries
Cleanup ≠ refactoring ≠ feature work ≠ Git history surgery.
| Request type | Action |
|---|---|
| "Clean up / finalize / publish-ready / keep final version / dead files / professional README" | Use this skill |
| "Fix bug X", "add feature Y", "refactor module Z" | Normal coding session |
| "Erase GitHub history", "purge secrets from history", "force-push" | See [git-safety.md](references/git-safety.md) remediation section — requires explicit authorization only; never triggered by a general cleanup request |
## Modes
Ask the user (or infer) which mode, and state it explicitly at the start.
| Mode | Does | Touches files? |
|---|---|---|
| **audit** | Full Phase 1–2, then a prioritized report. Nothing modified. | Never |
| **cleanup** | Audit, then: high-confidence removals + `.gitignore` + secrets hygiene + README + metadata recommendations. Verify afterwards. Ambiguous items → ask first. | Approved changes only |
| **release** | Cleanup, plus full diff review, a single clean approved commit, optional push. Push **only** when the user explicitly says so. | Committed changes |
Never interpret a general "clean up my repo" as authorization for: history
rewrites, force-push, credential rotation, remote renaming, or deleting
unrelated local work (datasets, notebooks, backups, files outside the repo).
## Hard safety rules (all modes)
1. **Preflight before anything.** Run `git status` and `git log --oneline -5`.
If there are uncommitted changes, list them and plan **around** them: never
stage, overwrite, or discard other people's uncommitted work. In release
mode, ask the user how to isolate it before committing.
2. **Forbidden commands:** `git clean -fdx`, `git reset --hard`, `git push
--force`, `git rebase`/`filter-branch`/`filter-repo`, `gh repo edit --rename`
as automatic steps. Never run destructive cleanup against broad filesystem
paths (e.g. `rm -rf` on anything outside the repo root).
3. **Delete within scope only.** The default scope is the current repo working
tree. Never delete a file outside the repo root; never delete local
datasets/models/backups unless explicitly authorized per-item.
4. **History is acceptable.** Removing a file from the working tree does not
erase it from past commits — say so. Never promise secret deletion "from
history". If history remediation is needed, follow [git-safety.md](references/git-safety.md) with explicit approval.
5. **Secrecy.** Never print secret values. Report `path:line` + variable name
redacted. Flag exposed credentials for revocation/rotation.
6. **No fabrication ever.** No invented features, screenshots, badges, demo
URLs, benchmarks, or test passes. If something could not be verified, say so.
7. **Recovery path.** Before any deletion batch, produce the plan table (Phase 3
output) so every deletion is traceable. `git rm` of tracked files is
recoverable from history; for untracked junk, list every path in the final
report, or move them to a quarantine folder the user names.
## Workflow
### Phase 1 — Audit (always first, every mode)
Run the helper (inside this skill's directory) for a fast, read-only inventory:
```bash
python <skill-dir>/scripts/repo_audit.py <repo-root> # text summary
python <skill-dir>/scripts/repo_audit.py <repo-root> --json out/audit.json
```
The helper only supplements your reading — work through the repo yourself for
anything it cannot see (imports, loaders, CI). Then, following [audit-inventory.md](references/audit-inventory.md):
- Identify the stack, entry points, manifests, build/test commands (see
[project-playbooks.md](references/project-playbooks.md) for per-stack details).
- Read the actual source to find which implementation is the **final version**
(size, imports, references, recency, completeness, user statements). Never
decide by filename alone.
- Classify every suspicious candidate into one of four confidence levels
(matrix and evidence rules are in audit-inventory.md):
`safe-to-remove`, `likely-unnecessary`, `must-retain`, `uncertain`.
Account for **all** reference styles before calling anything dead: dynamic
imports, framework conventions (`app/` routing, `__init__.py`, `admin.py`),
config-based loading, runtime file paths, plugins, CI workflows, referenced
relative links, and external consumers. A file with no obvious import is **not
automatically dead**.
### Phase 2 — Removing obsolete versions (consolidation)
- Candidates: `V1/ V2/ old/ backup/ copies/`, abandoned prototypes, parallel
implementations, duplicate docs, throwaway debug scripts/logs,
unreferenced experiments, regenerable build outputs.
- Prove the winner: trace imports/routes/manifests to the final app; confirm
with the user if folders differ in more than trivial ways.
- Keep: compatibility shims referenced by the final code, migration history,
assets referenced by paths, tests, CI, lockfiles, licenses, deployment files.
- Folder names with version numbers are **clues, not conclusions**.
### Phase 3 — Plan and approve (cleanup/release modes only)
Present a plan before deleting anything non-obvious:
```markdown
## Cleanup plan (approval needed)
| Path | Level | Verdict | Evidence |
|---|---|---|---|
| experiments/old_api/ | safe-to-remove | delete | imports? none found; not in manifest tests/CI; only referenced by deleted V1 |
| data/model.pkl | must-retain | keep | loaded by xai/predictor.py:42 |
| spreadsheet_round2.xlsx | uncertain | ASK | author name suggests data, no code refs |
Require explicit approval for: `uncertain` and `likely-unnecessary` items,
entire test suites, documentation, large binary assets, and anything the
user may have a personal attachment to (datasets, notebooks, screenshots,
old demo recordings). Verify once more that nothing referenced by the final
implementation is on the delete list.
```
Safe-to-remove (regenerable artifacts, caches, OS junk: `__pycache__/`,
`.pytest_cache/`, `node_modules/`, `dist/`, `.next/`, `*.log`, `.DS_Store`)
may be removed in cleanup mode *with confirmation for anything the user is
emotionally attached to*. Everything else requires approval.
For tracked files, prefer `git remove` semantics (records deletion in the
staged tree); for untracked junk, ordinary `Remove-Item`/`rm`. Also update
`.gitignore` to match the project's real generated artifacts.
### Phase 4 — Secrets and hygiene
Per [git-safety.md](references/git-safety.md) §secrets:
- Scan for real credentials (`.env` committed, keys, tokens, local db files).
- Report only redacted findings; propose `.env.example` with placeholders;
never copy real values into it; never write them into the README.
- If a real credential was exposed (committed or in the current tree), flag it
for **revocation/rotation** — that decision and any history surgery belong
to the user.
- Update `.gitignore` for real generated/local artifacts; never ignore source
or needed assets.
### Phase 5 — README (cleanup/release modes)
Rewrite or create the root `README.md` following [readme-and-metadata.md](references/readme-and-metadata.md):
- Grounded strictly in the inspected code: title, description, problem +
audience, real features, real stack, architecture outline, simplified tree,
prerequisites, install, env vars, exact launch and test commands, usage of
main features, deployment and license when relevant.
- Maps the stack to the instructions (a Flutter app gets phone/emulator and
`flutter run` steps; a Django API gets venv, migrations, and `runserver`).
- Adapted to the project's type: the README describes the current app only —
no development history, old-version comparisons, abandoned approaches, or
internal struggles.
- Every link, path, and command must exist/be valid — verify what can be
verified; do not cite screenshots or URLs that do not exist.
### Phase 6 — GitHub metadata
Per [readme-and-metadata.md §GitHub metadata](references/readme-and-metadata.md#github-metadata-apply-or-recommend):
recommend improvements, or apply them when the user is authorized (e.g.
`gh api -X PATCH /repos/{owner}/{repo}` after explicit approval):
description (one accurate sentence), topics (languages, frameworks, domain
keywords), suggested repo **name** if the current one is misleading
(never actually rename the remote without explicit approval; note downstream
breaking risk: links, integrations, deploy hooks, collaborators), website URL
only if real, and keep the existing **license** unchanged unless told otherwise.
If no authorized editing capability exists, deliver the recommended values as
a copy-paste block (e.g. "Settings → About → Description / Topics").
### Phase 7 — Verify (cleanup/release modes)
Follow the verification commands per stack in [project-playbooks.md](references/project-playbooks.md). At minimum:
- Dependencies: install/validate using documented procedure, when practical.
- Run tests and type-check/build as available for the stack.
- Verify the entry point and its required assets (imports, paths, secrets)
exist; validate README commands and links; instantiate the app where cheap
(do not launch servers or long jobs without approval).
- Compare final state vs. the initial audit; confirm nothing `must-retain`
was removed. If something broke, investigate and restore.
- Report tests that could not run because of missing credentials, hardware,
or network — and never claim full functionality without verified execution.
### Phase 8 — Release commit (release mode only)
- Review the full diff (`git add -A` then `git diff --cached --stat`, and a
real read of the diff for anything risky).
- Commit **only this task's** changes; isolate any unrelated user work first
(ask!). Suggested message: `chore: finalize repository (cleanup, README, hygiene)`.
- Push only when the user explicitly authorizes it and the branch/remote is
confirmed (never force-push).
- Never claim tests passed if they did not run or pass; include what ran and
what was skipped in the commit-adjacent summary.
### Phase 9 — Final report (all modes)
```markdown
## Finalization report
**Mode:** cleanup **Stack:** Django + Python 3.12
### Removed (with reason)
- docs/old_setup.md — duplicate of README install steps [untracked]
- logs/trial.log — recorded run output [untracked]
### Retained (and why, important items only)
- evaluation/metrics_fixture.json — imported by tests/metrics_test.py
- lfs/model_meta.json — loaded at startup by proxy/model_loader.py (large-file manifest)
### Created / updated
- README.md (rewritten, grounded in the real Django app)
- .gitignore (added __pycache__/, *.log, .env)
### Metadata (proposed)
description: "…" topics: django, python, ml, xai
repo name: keep or → "prostate-xai-dashboard" (needs your approval)
### Verified
- pytest: 14 passed / 1 skipped (env-dependent: needs OPENAI_API_KEY) ✓
- python -c "import xai; app config loads" ✓
- README launch command matches scripts/run_demo.py ✓
### Not verified / risks
- Flutter driver tests: no emulator available — NOT run
- exposed OpenAI key in git history → recommend rotation (decided NOT to rewrite history)
### Git
- Staged: M README.md, M .gitignore, D docs/old_setup.md, D logs/trial.log
- Commit: authored only after your go-ahead. Push: needs explicit approval.
```
Keep completed actions and recommendations clearly separated.
## Example user prompts and how to respond
| User says | Mode + first move |
|---|---|
| "Audit my repo before I push to GitHub" | audit → Phase 1–2 → report, no edits |
| "Clean up my GitHub repo, same final app, remove old V2" | cleanup → Phase 1 → Phase 3 plan → approval → execute/verify |
| "Prepare this for jury/portfolio — README + hygiene" | cleanup, README-first emphasis |
| "Remove old V1/V2/V3 and keep only the final working app" | cleanup; prove winner before deletions |
| "Find unused files and dead code" | audit, deliver classification report |
| "Make repo ready to publish" | release, verify + commit path |
## Self-check before reporting
- [ ] Were uncommitted, unrelated user changes preserved?
- [ ] Is every deleted path backed by evidence and approval?
- [ ] Is the README verifiable (commands, links, no invented content)?
- [ ] Did the app still build/run (or was the limitation honestly reported)?
- [ ] Was any forbidden history/scope-hygiene action taken without approval?
- [ ] Is the report complete per Phase 9?
Files in this package (10)
- .gitignore 1 KB
- LICENSE 1 KB
- README.md 4 KB
- SKILL.md 13 KB
- references/audit-inventory.md 5 KB
- references/git-safety.md 3 KB
- references/project-playbooks.md 5 KB
- references/readme-and-metadata.md 5 KB
- scripts/repo_audit.py 12 KB
- scripts/test_repo_audit.py 7 KB
Versions
The database has no other skills named github-repo-finalizer.
Database snapshot: 13.11.2026 · package version 1ac3893be329 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100github-readme
Generate polished GitHub README.md files for Mick's repositories in his established voice and structure. Always trigger immediately when the user's message starts with "readme" or "gr". Also trigger on "write a readme", "generate readme", "readme for this repo", "document this… - 100repo-structurer
Cleans up and structures a repository for production. Adds README files to every directory, modularizes code, removes dead files, and makes the repo LLM-smart. Use when the user asks to "clean up", "structure", "document", or "organize" their repo. Don't use for code review or bug fixing. - 95github-readme
Use when someone asks to write, create, rewrite, or improve a README / README.md for a project or GitHub repo, or to document a project for GitHub. Produces a minimal technical README in the owner's house style (logo header, cover, verified facts only). - 100readme-writer
Generate polished, well-structured README.md files for software projects. Use this skill whenever the user wants to write, create, draft, generate, update, improve, or rewrite a README — including phrasings like "write a readme", "document this project", "make a readme for my… - 100write-readme
Write or audit a project README. Fixes the section set by project type, front-loads the one-line description and the proof command, then runs the link, heading and snippet checks. Use when asked to write, rewrite, tighten or audit a README, or when a repo has none. - 100readme
Write or rewrite a project's README so it is short, accurate and specific to the project: what it is, how to install, use and build it, verified against the repo. Use when asked to create, write, update, rewrite or review a README.