/install-script-generator

name: install-script-generator
description: "Generate cross-platform install scripts for any software or library — a standalone install.sh runnable via a curl/wget one-liner with OS, arch, and package manager detection. Don't use for Dockerfiles, CI/CD pipelines, or one-off shell scripts."
license: MIT
effort: high
metadata:
  version: 2.3.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

Install Script Generator

Generate robust, cross-platform installation scripts that users can run with a **single bash command** via GitHub raw URLs. This SKILL.md is a lean index — long templates and tables live under `references/` to protect the agent's context budget.

When to Use

• The user asks for a `curl | bash` one-liner for their project.
• A repo needs a `install.sh` that auto-detects OS, arch, and package manager.
• A Python/Go/Node/Rust module should be installable in one command from a fresh machine.

Skip this skill for Dockerfiles, CI/CD pipelines, or one-off local shell scripts.

Prerequisites

• The repo has a known `<owner>/<repo>` (check `git remote -v`) and a default branch.
• The target software's build system is identifiable (`Makefile`, `package.json`, `setup.py`, `Cargo.toml`, `go.mod`, etc.).
• `python3` is available locally for the helper scripts under `scripts/`. If `python3` is missing, skip each helper-script step, record it as `not run (python3 not found)`, and continue; the run then ends `PARTIAL`.

Reference Files (read on demand to save tokens)

| File | When to read | |------|--------------| | `references/install-template.md` | When generating `install.sh` — full bash template with detection helpers, dependency installer, and main entry point | | `references/readme-snippet.md` | When updating the README — copy-paste install block plus URL format notes | | `references/edge-cases.md` | When handling unusual OS/sudo/path scenarios and writing step reports | | `references/final-report.md` | When writing the final report — the four parts, status rules, outcome table, examples, reader checks | | `scripts/env_explorer.py` | Local environment probe (OS, arch, package managers, sudo) | | `scripts/plan_generator.py` | Generates `installation_plan.yaml` from env + target | | `scripts/executor.py` | Dry-runs `installation_plan.yaml` with rollback, before Phase 3 generation | | `scripts/doc_generator.py` | Renders user-facing `USAGE_GUIDE.md` |

Do not inline these contents into the conversation; link to them to preserve the context window.

Repo Sync Before Edits (mandatory)

Run this once, before Phase 1. Before creating, updating, or deleting files in an existing repo, sync the current branch with remote:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is dirty, `git stash push -u -m pre-sync` first, sync, then `git stash pop`. If `origin` is missing or rebase/stash conflicts occur, stop and ask the user before continuing.

Workflow

A **fix attempt** is one edit followed by a rerun of the failed check. Stop after 3 fix attempts on the same check, record the check as failed, and continue to the next phase. To **stop with `BLOCKED`**, skip the remaining phases and print the final report.

Phase 1 — Exploration

1. Identify the target software/module/tool. If the user did not name it and the repo holds more than one buildable project, ask which one. 2. Inspect the repo for build files (`Makefile`, `package.json`, `setup.py`, `Cargo.toml`, `go.mod`, ...). 3. Record the install method: the package name, if the target is published in a package manager, or the build-and-copy commands from its build file. If neither exists, ask the user. If the user gives no install method, stop with `BLOCKED`. 4. List dependencies the software needs to build and run. 5. Run `git remote get-url origin` to read `<owner>/<repo>`. 6. Run `git symbolic-ref --short refs/remotes/origin/HEAD` and strip `origin/` to read the default branch. 7. If step 5 or step 6 fails, ask the user for the value. If the user gives no answer, stop with `BLOCKED`. 8. Run `python3 scripts/env_explorer.py` to capture OS, arch, package managers, shell, and sudo availability into `env_info.json`.

Phase 2 — Planning

1. Order the dependencies so each one installs before anything that needs it. 2. For each dependency, note the `command -v <dep>` check `install.sh` uses to skip one that is already installed. 3. Run `python3 scripts/plan_generator.py --target "<name>" --env-file env_info.json --deps <dep1> <dep2> ...` (dependencies from step 1, space-separated; omit `--deps` only if there are none) to emit `installation_plan.yaml`. 4. If the target is not published in the detected package manager, edit the `Install <name>` step in `installation_plan.yaml`: set `command`, `verify`, and `rollback` to the commands `install_<tool>` will run. 5. Replace every `# TODO` placeholder in the plan. Add a step for each dependency that `plan_generator.py` warned it left out. 6. Run `python3 scripts/executor.py --plan installation_plan.yaml --dry-run`. 7. Check the dry run: it exits 0, its last summary line starts `DRY RUN:`, stderr has no `placeholder command` warning, the steps follow the step 1 order, and every `Install ...` step has a non-null `rollback`. The package-manager check and final verify steps carry `rollback: null` by design. If a check fails, fix the plan and rerun step 6.

The dry run skips execution, so it checks the plan's shape, not that installation or rollback actually works.

Phase 3 — Generation (primary output)

If `install.sh` already exists at the repo root, show the user the planned changes and ask before overwriting it. If the user declines, stop with `BLOCKED`.

Generate `install.sh` at the repo root using `references/install-template.md`. The template contains four sections you compose:

1. Header + colour helpers (`info`, `ok`, `warn`, `err`, `die`). 2. Detection helpers (`detect_os`, `detect_arch`,