Read environment-setup-validator skill Read environment-setup-validator skill RESOLVED SOURCE: TYPE B — /mnt/skills/user/environment-setup-validator/SKILL.md Output: AUDIT FINDINGS SEVERITY LOCATION FINDING BLOCKER frontmatter (lines 3-11) description uses YAML folded scalar (>) with line breaks; descriptions must be one continuous paragraph for reliable trigger matching. MAJOR body (lines 16-18) Missing ## Purpose section; the level-1 heading is followed directly by an unlabeled paragraph instead of the required ## Purpose H2. MAJOR ## When to Use (lines 22-29) Missing ### SCOPE — This skill does NOT handle: subsection with 3 to 6 exclusions. MAJOR body (lines 33-46) ## Input Modes is a top-level section between ## When to Use and ## Process; only Purpose / When to Use / Process / Validation are permitted in that span. Content should be folded into Process Step 1 or moved after Validation. MAJOR ## Process (line 52 onward) Steps use ### Step 1 — ... H3 headings instead of a numbered list with bolded action phrases (1. **Triage** —). Breaks the convention every other user skill follows. MAJOR body (lines 195-203) ## End-of-build Report is a top-level section after Validation containing a hardcoded sample output with fixed counts (Issues (❌) : 2). The numbers will hallucinate on real runs — the model will copy the example values rather than computing them. MINOR ## Validation (line 185) Preamble line "Before delivering, check:" precedes the checkbox list; checkboxes should follow the H2 directly without intervening prose. MINOR ## When to Use (lines 24-29) Trigger list has 6 items but uses bullets instead of a numbered list. MINOR ## Process Step 2 subsections Each domain (Node / Deps / Env Vars / Docker / CI) is presented as an H4 subsection rather than as sub-steps of Step 2, making the process count ambiguous (is it 3 steps or 7?). FIXED SKILL.MD md --- name: environment-setup-validator description: Validates and diagnoses local or CI development environment setup — Node.js version, Docker configuration, missing or misconfigured env vars, and dependency installation issues. Use this skill whenever a developer says "my setup doesn't work", "something is wrong with my environment", "env vars aren't loading", "Docker won't start", "node version mismatch", or pastes error output from npm/yarn/pnpm install, docker-compose, or a failing CI run. Trigger also when the user shares a .env.example, Dockerfile, docker-compose.yml, or .nvmrc and wants it reviewed or validated. --- # Environment Setup Validator ## Purpose Developers lose hours to environment setup failures that mix multiple root causes — a Node version mismatch hiding behind a peer-dep error, a missing env var manifesting as a Docker crash, a CI failure caused by an uncommitted lock file. This skill prevents that failure mode by classifying the failure into a fixed set of domains (Node, deps, env vars, Docker, CI), validating each in isolation against the user's actual config, and delivering a report where every flagged issue has a concrete fix rather than a description. ## When to Use 1. `npm install`, `yarn`, or `pnpm install` throws errors the user cannot resolve from the message alone. 2. App crashes on startup with "missing env variable" or `undefined` config values. 3. Docker build or `docker-compose up` fails with port conflicts, volume issues, or service-start ordering problems. 4. Node version mismatches between local, CI, and production cause inconsistent behaviour. 5. User shares a `.env.example` and wants to validate their `.env` against it. 6. CI pipeline fails at the environment setup step but the same commands succeed locally. 7. User shares a `Dockerfile`, `docker-compose.yml`, or `.nvmrc` and wants it reviewed before adopting. ### SCOPE — This skill does NOT handle: - Application-level bugs once the environment is confirmed correct - Database schema migrations or seed data problems - Dependency version upgrades (npm/pip/cargo bumps) - Secrets management policy or vault integration - Cloud infrastructure (Terraform, Kubernetes) beyond container-level config ## Process 1. **Collect inputs** — Accept whichever the user provides: pasted error output, a config file (`Dockerfile`, `docker-compose.yml`, `.nvmrc`, `.env.example`), a plain description ("works on my machine but fails in CI"), or any combination. If the input is too vague to classify, ask once: "Could you share the error message and any relevant config files (.env.example, Dockerfile, package.json)?" Do not proceed with a guess. 2. **Triage the failure domain** — Classify the problem into one or more of: Node (version mismatch, `engines` field, `.nvmrc`, nvm errors), Deps (install errors, peer-dep conflicts, lock-file issues), Env vars (`undefined`, missing keys, wrong `.env` loaded), Docker (build errors, port conflicts, volume mount issues), CI (works locally, fails in pipeline, secrets not injected). Record the matched domains before validating. 3. **Validate Node configuration** — Check `.nvmrc`, `package.json` `engines.node`, and `Dockerfile` `FROM node:XX` for the required version. Flag local Node version mismatch with `.nvmrc` (instruct `nvm use`), an `engines` field too strict for the installed version (state both versions), and non-deterministic base images like `node:latest` (recommend a pinned tag, e.g. `node:20-alpine`). 4. **Validate package manager and dependencies** — Identify which lock file is present (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`) and confirm the matching package manager is in use. Flag `ERESOLVE` peer-dep errors (recommend `--legacy-peer-deps` or upgrade), lock file out of sync (delete `node_modules` and lock file, reinstall), mixed package managers (add `packageManager` field), and `node_modules` committed to git (add to `.gitignore`, remove from repo). 5. **Validate environment variables** — If `.env.example` is provided, compare its keys against `.env` (request `.env` if absent). For each key, report: present and set, missing, or present but empty. Flag common misconfigurations: `DATABASE_URL` missing protocol, `PORT` set as a string when a number is expected, secrets hardcoded in `.env.example`, `.env` not in `.gitignore`. Produce a diff table with columns Key / .env.example / .env / Status. 6. **Validate Docker and Docker Compose** — Check that base images are pinned, `COPY` order is optimised for layer caching (deps before source), exposed ports match `docker-compose.yml` mappings, volume mounts do not shadow `node_modules`, and dependent services have health checks. Flag overwritten `node_modules` (recommend anonymous volume `- /app/node_modules`), port-already-in-use conflicts, services starting before the DB is ready (add `depends_on` with `healthcheck`), and invalidated build cache (move `COPY package*.json` before `COPY . .`). 7. **Validate CI environment** — Check whether secrets are injected (env vars set locally but undefined in pipeline), Node version is pinned in CI config (`actions/setup-node` with explicit version), cache is configured for `node_modules` or `.pnpm-store`, and OS differences between local and CI cause path or case-sensitivity issues. 8. **Deliver findings report** — Output a structured report with three sections: `### ✅ OK` (passed checks), `### ❌ Issues Found` (each with domain tag, problem, and exact fix on the next line), and `### ⚠️ Warnings` (non-blocking recommendations). Every flagged issue must include the concrete fix command or config change, not just the problem description. Never suggest hardcoding secrets or credentials; recommend the secrets manager or env-file pattern appropriate to the platform. ## Validation - [ ] Every flagged issue in the report includes a concrete fix command or config change on the line immediately after the problem statement. - [ ] No suggested fix hardcodes a secret, password, API key, or credential value. - [ ] Docker fixes preserve existing volume mounts that were not flagged as problematic. - [ ] Node version recommendations match the project's `engines.node` field when one is present. - [ ] Env var keys flagged as missing are not already set via system environment (the report notes this caveat when `.env` was not provided). - [ ] The report contains all three sections (OK, Issues Found, Warnings) even when one section is empty, with the empty section marked "none". - [ ] Each issue is tagged with its failure domain (`[Node]`, `[Deps]`, `[Env Vars]`, `[Docker]`, `[CI]`). CHANGE SUMMARY frontmatter: collapsed YAML folded-scalar description into a single-line paragraph so trigger matching reads it as one string. body header: added ## Purpose section describing the failure mode and outcome; demoted the previous unlabeled lead paragraph into it. ## When to Use: converted bullet list to numbered list, expanded to 7 concrete triggers, and added ### SCOPE — This skill does NOT handle: with 5 exclusions. ## Input Modes section: removed as a standalone H2; folded into Process Step 1 ("Collect inputs") to preserve the four-section template. ## Process: rewrote H3-per-step format into a numbered list of 8 imperative steps with bolded action phrases, matching the convention used in other user skills. ## End-of-build Report: removed; the hardcoded sample counts (Issues (❌) : 2, Warnings (⚠️) : 2) would have been copied verbatim by the model rather than computed. Report structure is now defined as the deliverable in Process Step 8. ## Validation: removed preamble line "Before delivering, check:"; tightened checkboxes to be inspectable post-conditions of the delivered report. Tables for symptoms and fixes were preserved in spirit but moved into prose inside Process steps so each step describes one observable action. The fixed skill is ready to deploy.