how-to-runlisted

Generates or updates a project's HOW-TO-RUN.md — a single document that teaches a new developer how to set up their environment and run the project locally. Detects build system, toolchain, SDKs, source dependencies (git submodules, sibling repos), external services, environment config, and hardware/OS requirements. Works for web apps, C/C++ desktop apps, native mobile, JVM/Android, game engines, embedded/firmware, and backend services. Audits an existing HOW-TO-RUN.md against actual project state. Learns from setup info found in README.md / CONTRIBUTING.md / docs but never modifies those files — any outdated info found elsewhere is reported to the user at the end. Use after /optimus:init or standalone when onboarding feels broken. Handles single projects, monorepos, and multi-repo workspaces. When the file already exists, also offers a guided in-chat walkthrough where the user runs each documented step locally — the skill never executes commands itself. Use the walkthrough when onboarding a new developer.
oprogramadorreal/optimus-claude · ★ 57 · AI & Automation · score 82

Install: claude install-skill oprogramadorreal/optimus-claude

# How to Run Generate or update a `HOW-TO-RUN.md` at the project (or workspace) root that teaches a new developer who has just cloned the repo how to set up their environment and run the project locally — covering OS/hardware prerequisites, toolchain & SDKs, source dependencies (submodules, sibling repos), language-level install, external services, env config, build, run, and tests. **Write scope:** The only file this skill is ever permitted to create or modify is `HOW-TO-RUN.md`. It never modifies `README.md`, `CONTRIBUTING.md`, `docs/*`, `BUILDING.md`, `INSTALL.md`, or any other file — not even to add a link. Existing docs are *input only*: the skill learns from them but always verifies every fact against the actual codebase before using it. The optional guided in-chat walkthrough (Step 3a) is display-only — it never executes commands; the user runs every step locally. The walkthrough procedure lives in `references/guided-walkthrough.md`. ## Step 1: Detect Full Project Context (agent-assisted) Delegate project scanning to a detection agent to keep the main context clean for content generation. Read `$CLAUDE_PLUGIN_ROOT/skills/how-to-run/agents/shared-constraints.md` for agent constraints. Read `$CLAUDE_PLUGIN_ROOT/skills/how-to-run/agents/project-environment-detector.md` for the full prompt template, detection tasks, and return format for the Project Environment Detector Agent. Read these reference files and provide their content to the agent as context before the age