Init Makefiles

init-makefiles

Make is the project's control plane. Generate one Makefile per app (root + up to 3 sub-Makefiles in monorepos), zero required arguments, scenario-appropriate targets only, with safe replacement of any prior scaffold.

This is the consolidated successor to the old make-local, make-railway, and make-vercel direction. Do not recreate provider-specific Makefile skills — classify the project's scenario here, then generate only the targets that scenario needs.

When to use this skill

Trigger on any of these:

• "set up make for this project" / "scaffold a Makefile" / "init Makefile targets"
• "add a make deploy target" / "wire deploy via make" / "give me make local and make prod"
• "my make local is broken / port-stuck / out of date" — refresh stale targets
• "this monorepo has three different Makefiles" — unify them under one banner
• "ship this Mac app to my macbook over rsync" — Scenario G
• "add make tunnel / make funnel" for Tailscale exposure
• "sync the AGENTS.md make-targets section" after editing the Makefile
• "generate the GitHub Actions deploy workflow that backs make deploy"

Do NOT use this skill when:

• The user wants a one-off shell script — use bash, not make
• Railway logs, scale, restart, env edits, or ad-hoc CLI ops are the job → use run-railway
• The job is broad AGENTS hierarchy / REVIEW.md / folder-scoped agent config → use init-agent-config
• The job is hosted-MCP architecture beyond a local MCP control target → use build-mcp-use-server

Three principles (apply without exception)

1. Scenarios beat providers. Don't ask "is this a Vercel project?" — ask "what is this project?" The provider stack (Vercel, Railway, Supabase) falls out of the scenario, never the other way around.
2. Local = real dev builds, never toy builds. Next.js / Turborepo / monorepo projects use the actual dev pipeline. No shortcuts that diverge from production behavior.
3. Exposure is opt-in. make local binds 127.0.0.1. make local-lan binds 0.0.0.0. make tunnel runs Tailscale Serve (tailnet-only). make funnel is PUBLIC and gated behind explicit PUBLIC_FUNNEL=1. Funnel never enables as a side effect of any other command.

Hard rules baked into every generated Makefile

• Max 4 Makefiles per project — root + up to 3 app sub-Makefiles. If a monorepo has more apps, ask which three.
• Every target works with zero arguments. Env vars are overridable (make local PORT=4000) but defaults must work. Sole exception: make supabase-migrate-new name=.
• Universal preamble — SHELL := bash, .SHELLFLAGS := -eu -o pipefail -c, .ONESHELL:, .DELETE_ON_ERROR:, MAKEFLAGS += --warn-undefined-variables --no-builtin-rules, .DEFAULT_GOAL := help. Full preamble in references/makefile-base.md.
• Port hygiene mandatory — use the _free-port-% helper from references/port-hygiene.md. Only kill our own dev processes (node|next-server|turbo|turbopack|next|bun|deno); refuse foreign holders, suggest +10 port.
• Localhost binding by default. LAN binding via make local-lan. Tailscale Serve via make tunnel (tailnet-only). Tailscale Funnel via make funnel (PUBLIC, opt-in only).
• Helper targets prefix with _ (_check-vercel-tokens, _free-port-%, _print-banner-*). They do not appear in make help.
• Replace, don't edit. Never edit a Makefile incrementally — preview, manifest, snapshot, delete, regenerate. The targeted snapshot commit is the safety net.

Scenario classification

Pick exactly one scenario per deployable app. The seven:

| # | Scenario | Primary signal | What's in scope | |---|---|---|---| | A | Frontend-only | next.config.* / vite.config.* / etc.; no backend dir; no Supabase | Local, LAN, tunnel; Vercel deploy by default. Cloudflare Pages is opt-in only — switch to it when (and only when) the user explicitly says "Cloudflare", "Pages", "Wrangler", or names the Pages product. Disk signals alone (a stray wrangler.toml for R2/Workers) never flip the default. | | B | MCP server | @modelcontextprotocol/sdk or mcp-use in deps | Local; no deploy; inspect target | | C | Frontend + backend | A signals + apps/api (or similar) with Express/Hono/Fastify | Frontend + Vercel + Railway | | D | Frontend + Supabase | A signals + @supabase/supabase-js + supabase/ dir | Frontend + Vercel + Supabase CLI ops | | E | Multi-service Railway | Multiple service dirs / railway.toml files | Railway only; parallel deploy where safe | | F | Build-artifact | Cargo / Go / Swift / native CLI; no HTTP framework, no remote target | Build + run locally; no deploy | | G | MacBook ship | .xcodeproj / Package.swift Mac target + remote-Mac SSH alias | Build + ship via rsync + atomic swap + verify |

For single-app projects, the final classification has one tag. For monorepos, each deployable app gets one tag and the root gets a dominant orchestration tag. Use the supported combined tag C+D only when a custom backend deploys separately and Supabase is also in scope.

If detection is ambiguous → ask one targeted question, never guess. Sample disambiguation prompts in references/scenario-detection.md.

Workflow

1. Inspect (read-only)

Capture the project's state before writing anything:

# Package manager
ls bun.lockb pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null

# Framework signals (frontend)
ls next.config.* vite.config.* astro.config.* nuxt.config.* svelte.config.* remix.config.* 2>/dev/null

# Supabase
ls supabase/config.toml 2>/dev/null
jq -r '.dependencies | keys[]?' package.json 2>/dev/null | grep -i supabase

# Monorepo
ls turbo.json pnpm-workspace.yaml apps/ packages/ 2>/dev/null
jq -r '.workspaces' package.json 2>/dev/null

# Backend signals
find apps server services -maxdepth 2 -name "package.json" 2>/dev/null | head

# MCP server
jq -r '.dependencies | keys[]?' package.json 2>/dev/null | grep -E 'modelcontextprotocol|mcp-use'

# Mac signals
ls *.xcodeproj *.xcworkspace Package.swift Info.plist 2>/dev/null

# Existing Make scaffolding
ls Makefile *.mk scripts/dev.sh scripts/deploy.sh 2>/dev/null
find . -maxdepth 3 -name "Makefile" -not -path "./node_modules/*"

# AGENTS.md / CLAUDE.md state
ls -la AGENTS.md CLAUDE.md 2>/dev/null

Then run the bundled detector for a second, low-freedom signal pass. Resolve scripts/scenario-detect.sh relative to this skill directory and pass the downstream project root:

bash scripts/scenario-detect.sh /path/to/project

The detector is read-only and heuristic-only; it prints observed signals and candidate scenarios, not the final answer. Full detection cheat sheet in references/scenario-detection.md; detector implementation notes in scripts/scenario-detect.md.

If a precondition fails (no package.json, no dev script, no SSH alias for Mac scenario), surface it before generating. Do not generate something that breaks on first run.

2. Classify and announce

Before generating files, print this block:

Scenario: 
Scope: 
Confidence: 
Signals: 
Excluded scenarios: 
Provider scope: 
Makefiles to generate: 
Ambiguity resolved: 

3. Preview and read existing scaffolding

Run the bundled wipe preview before touching files. Resolve scripts/preview-makefile-wipe.sh relative to this skill directory and pass the downstream project root:

bash scripts/preview-makefile-wipe.sh /path/to/project
bash scripts/preview-makefile-wipe.sh /path/to/project --paths-only > /tmp/init-makefiles-candidates.txt

The script is read-only. It prints exact paths, match reasons, tracked state, and uncommitted status; implementation notes live in scripts/preview-makefile-wipe.md.

For every candidate Makefile, *.mk, make-*.sh, scripts/dev.sh, and scripts/deploy.sh: read the file before classifying it as scaffold. Note useful patterns the user encoded (custom env handling, project-specific port choices, framework-specific dev commands) — those inform regenerated targets.

Write a deletion manifest containing only paths approved for replacement:

DELETION_MANIFEST=/tmp/init-makefiles-delete-manifest.txt
# write one approved path per line, exactly as printed by the preview

Refuse to continue if a candidate has uncommitted non-scaffold edits the agent cannot classify. If unrelated dirty files exist, leave them untouched and state that they were not snapshotted.

4. Snapshot and wipe from manifest

Create a targeted snapshot commit before deletion. Stage only manifest paths:

git status --porcelain
while IFS= read -r path; do
  [ -n "$path" ] || continue
  git add -- "$path"
done `; `make inspect` returns tool schema
- E: `make deploy-all` deploys services in parallel; `make verify` HTTP-probes each
- F: `make build` produces a binary; `./build/ --version` runs without error
- G: `make ship` rsyncs and `pgrep -x "$(APP_NAME)"` returns a PID after `sleep 2`

Core generation is complete when Makefiles, AGENTS.md sync, and verification are done. The skill remains useful and complete if CI/CD is declined.

### 8. Optional — CI/CD

Ask first: "Generate GitHub Actions deploy wiring locally? (y/n)". If yes, follow `references/ci-cd-workflow.md`:

1. Detect GitHub repo via `gh repo view --json nameWithOwner -q .nameWithOwner`
2. Generate `.github/workflows/deploy.yml` for the providers in scope only
3. Prompt user for ONLY the tokens needed (Vercel / Railway / Supabase)
4. `gh secret set  --body "$pasted"` for each required secret
5. Verify required secrets by name with `gh secret list`
6. Commit the workflow locally
7. Ask for explicit push authorization
8. Push only after that authorization; never force-push

If declined, leave `.github/workflows/` untouched. No half-baked YAML.

## Decision rules

- **Localhost-only by default.** `make local` binds `127.0.0.1`. LAN exposure must be explicit (`make local-lan`).
- **Funnel never auto-enables.** `make funnel` is the only target that uses Funnel, and only with `PUBLIC_FUNNEL=1`.
- **Backends don't run locally by default.** Local hosts the frontend or an MCP server. Backend stays remote in dev unless `LOCAL_BACKEND=1` is set explicitly.
- **Provider scope is conditional.** Vercel only if there's a frontend. Railway only if there's a custom backend. Supabase only if `supabase/` exists. MacBook only if a Mac project + remote-Mac target.
- **No improvised commands.** Inspect first; pick the canonical command from the relevant reference.
- **Replace before regenerating.** Preview, read, manifest, targeted snapshot, print recovery, then delete only manifest paths. Never edit Makefiles incrementally.
- **Max 4 Makefiles.** Ask if there are more apps than slots.
- **Detection ambiguous → ask one question, never guess.**

## Recovery from wipe

```bash
git log --oneline -- Makefile
git show --stat 
git revert 
# or restore a single file:
git restore --source= -- path/to/Makefile

Failure modes (and where to fix them)

| Symptom | Cause | Fix | |---|---|---| | make local fails with "port :PORT held by orbstack" | Foreign port holder; refused per port-hygiene rule | Pick a different port (make local PORT=4000); don't kill OrbStack | | make tunnel reports "tailscale not signed in" | Tailscale daemon up but account not linked | tailscale up interactively; this skill assumes Tailscale is signed in | | make deploy-vercel fails with "Project not found" | .vercel/project.json missing or wrong project name | Re-run vercel link --yes --project --token=$VERCEL_TOKEN | | make deploy-railway returns 502 "Application Failed to Respond" | App listens on localhost:3000 not 0.0.0.0:$PORT | Fix app's bind address; redeploy | | make supabase-migrate-apply no-ops with "no migrations to apply" | Migration files already in remote history | Run make supabase-pull to detect drift | | make ship fails preflight with "ssh alias not found" | Host macbook not in ~/.ssh/config | Add the Host block; make ship re-checks | | AGENTS.md and CLAUDE.md both exist with different content | State 1 of the symlink machine | Skill prompts user; merges into AGENTS.md per references/agents-md-update.md | | gh secret set fails with "auth required" | Not authenticated | gh auth login; CI/CD step re-runs | | Vercel build fails with function over 250 MB | Heavy bundled deps | make build-check surfaces sizes; references/makefile-frontend.md lists mitigations | | make funnel rejects port 3000 | Funnel allows only 443/8443/10000 | Use make funnel TUNNEL_PORT=443 (and PUBLIC_FUNNEL=1) | | make tunnel works but host ..ts.net fails on macOS | macOS DNS quirk: host/nslookup/bare dig bypass system resolver | Use tailscale dns query or dscacheutil -q host -a name |

Final report contract

Return this shape when the downstream project work is done:

Scenario: 
Generated files: 
Deleted/replaced scaffold paths: 
Snapshot: 
AGENTS.md / CLAUDE.md: 
CI/CD: 
Verification: 
Manual verification still required: 

Reference routing

| File | Read when | |---|---| | references/scenario-detection.md | Classifying a project; resolving ambiguity; sample disambiguation prompts | | references/makefile-base.md | Universal preamble, ANSI palette, helper conventions; every Makefile uses this | | references/makefile-frontend.md | Generating Scenarios A / C / D frontend targets (local, local-lan, tunnel, deploy-vercel, verify, env-pull, build-check) | | references/makefile-cloudflare-pages.md | Scenario A Cloudflare Pages variant — opt-in only. Read this reference only when the user explicitly mentions Cloudflare / Pages / Wrangler. The Scenario A default is Vercel (makefile-frontend.md). Contents: deploy-cloudflare, cf-project-init, cf-list, cf-tail, wrangler.toml shape, _redirects proxying, 25 MiB-per-file / 20k-file limit checks. | | references/makefile-r2-bulk.md | Cloudflare R2 media (opt-in when R2 is part of the workflow; works with either Vercel or Pages-hosted frontends): r2-info, r2-cors-apply, single-file r2-put/r2-get/r2-rm, hardlink r2-stage, rclone-configure/rclone-check, r2-sync (rclone copy — additive default for mixed-tenant safety), wrangler-OAuth bulk fallback, public-access audit | | references/makefile-backend.md | Generating Scenarios C / E backend targets (Railway deploy, multi-service parallel, healthcheck rules, railway.toml baseline) | | references/makefile-supabase.md | Generating Scenario D Supabase targets (supabase-link, -migrate-*, -functions, -types, -secrets-*) | | references/makefile-macbook.md | Generating Scenario G ship pipeline (preflights, rsync, atomic swap, kill-then-launch, verify) | | references/makefile-monorepo.md | Multi-Makefile delegation; 4-file ceiling; per-app namespacing; root-Makefile $(MAKE) -C pattern | | references/tailscale-funnel-rules.md | Tunnel/Funnel target generation; macOS DNS quirks; Funnel port restrictions; ACL preflight | | references/port-hygiene.md | The kill-only-our-own pattern; default-port squat list; SIGTERM-then-SIGKILL escalation; banner conventions | | references/agents-md-update.md | The 5-state machine for AGENTS.md / CLAUDE.md; the ## Make targets section template; idempotency rule | | references/ci-cd-workflow.md | Wiring GitHub Actions; gh secret set sequence; concurrency rules; rotation hint | | references/env-vars-conventions.md | Where envs live per scenario; .env.local vs .env.railway; Vercel sensitivity defaults; Railway built-in vars | | references/verification-ladder.md | The 6 rungs; per-target verification; banner template for the user's manual rung-6 step | | scripts/scenario-detect.md | Read-only heuristic detector script; use before final classification and ambiguity questions | | scripts/preview-makefile-wipe.md | Read-only wipe preview script; use before manifest, targ

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yigitkonur
• Source: yigitkonur/skills-by-yigitkonur
• License: MIT

Install and usage instructions live in the source repository linked above.