Cmd Makefile

Makefile Helper

Create Makefiles that are simple, discoverable, and maintainable.

Core Principles

1. Default to rich help - Use categorized help with emoji headers unless user requests minimal
2. Default Chrome extensions to modular - Use the modular makefiles/*.mk layout with shared colors/help for Chrome extension projects unless the repo is truly tiny
3. Ask about structure upfront - For new Makefiles, ask: "Flat or modular? Rich help or minimal?"
4. Follow existing conventions - Match the project's style if Makefile already exists
5. Don't over-engineer - Solve the immediate need, not hypothetical futures
6. Use uv run - Always run Python commands via uv run for venv context
7. Explain decisions - If choosing flat/minimal, explain why before generating

When to Use This Skill

• Creating a new Makefile for a project
• Adding specific targets to an existing Makefile
• Improving/refactoring an existing Makefile
• Setting up CI/CD make targets
• Distributing pre-built binaries via GitHub Releases

Quick Start

For new projects, use the appropriate template:

| Project Type | Template | Complexity | Asks upfront | |-------------|----------|------------|------| | Any project | templates/base.mk | Minimal | — | | Python with uv | templates/python-uv.mk | Standard | — | | Python FastAPI | templates/python-fastapi.mk | Full-featured | test split? prod target? HEALTH_PATH? | | PostgreSQL + Alembic | templates/postgres.mk | Standard | PG_PORT (5433 default)? soft vs HARD reset? | | Node.js | templates/nodejs.mk | Standard | — | | Go | templates/go.mk | Standard | — | | Chrome Extension | templates/chrome-extension.mk | Modular | — | | Flutter App | templates/flutter.mk | Modular | — | | Electron App | templates/electron.mk | Modular | — | | Static Site (HTML/CSS/JS) | templates/static-site.mk | Standard | DEPLOY_MODE (rsync/gh-pages/netlify/vercel/none)? |

For templates in the "Asks upfront" column, run the Phase 2 interactive questions in §"Interaction Pattern" before scaffolding. Companion files:

• templates/python-fastapi-env/.template.env → project's .template.env
• templates/python-fastapi-scripts/export_openapi_spec.py → scripts/export_openapi_spec.py
• templates/postgres-env/.template.env → merge into project's .template.env (don't ship two)

Chrome Extension Structure

The chrome extension template uses a modular structure:

Makefile                              # Main file with help + includes
makefiles/
  colors.mk                           # ANSI colors & print helpers
  common.mk                           # Shell flags, VERBOSE mode, guards
  build.mk                            # Build zip, version bump, releases
  dev.mk                              # Lint, clean, install
  test.mk                             # Unit tests, E2E tests, coverage
  env.mk                              # Environment setup, dependency checks

Copy from templates/chrome-extension-modules/ to your project's makefiles/ directory.

Key features:

• Use makefiles/colors.mk for ANSI color output and header helpers.
• Use makefiles/common.mk for shell flags, guard rails, and shared variables.
• Use makefiles/env.mk for environment checks and dependency sanity.
• Use makefiles/build.mk for build/package/release targets.
• Use makefiles/dev.mk for install, watch, clean, and other local workflows.
• Use makefiles/test.mk for typecheck, unit, and E2E targets when present.
• build-release - Version bump menu (major/minor/patch) + zip for Chrome Web Store
• build-beta - (Optional) GitHub releases with gh CLI
• test-unit / test-e2e - Vitest + Playwright testing
• test-unit- / test-e2e- - Per-module test targets
• VERBOSE=1 make - Show commands for debugging

Flutter App Structure

Makefile                    # Main file with help + includes
makefiles/
  colors.mk                # ANSI colors & print helpers
  common.mk                # Shell flags, VERBOSE mode, guards
  dev.mk                   # Setup, run simulator/device, devices, clean
  build.mk                 # iOS/Android builds (IPA, APK, AAB)
  deploy.mk                # TestFlight upload
  lint.mk                  # Dart analyze & format

Copy from templates/flutter-modules/ to your project's makefiles/ directory.

Key features:

• flutter-run-ios auto-boots simulator and waits for it
• flutter-run-android auto-launches emulator and waits for it
• flutter-run-device auto-detects or uses FLUTTER_IOS_DEVICE / FLUTTER_ANDROID_DEVICE
• flutter-build-ipa + flutter-export-ipa + flutter-deploy-testflight full iOS release workflow
• flutter-export-ipa re-exports IPA from existing archive without rebuilding
• _check-asc-app pre-flight App Store Connect validation (with ASCAPIKEY/ASCAPIISSUER)
• flutter-lint FIX=true Dart formatting with FIX pattern
• VERBOSE=1 make show commands for debugging

Electron App Structure

Makefile                    # Main file with help + includes
makefiles/
  colors.mk                # ANSI colors & print helpers
  common.mk                # Shell flags, VERBOSE mode, guards
  dev.mk                   # Setup, dev server, debug, clean
  build.mk                 # Pack-check, dist (mac/win/linux), publish
  lint.mk                  # ESLint, Prettier, TypeScript, tests

Copy from templates/electron-modules/ to your project's makefiles/ directory.

Key features:

• electron-dev starts dev mode with hot-reload
• electron-debug launches with DevTools open
• electron-clean single target that removes artifacts, node_modules, and lock file
• electron-pack-check smoke-tests that the app loads without errors
• electron-dist-mac / electron-dist-win / electron-dist-linux cross-platform builds
• electron-dist-all builds for all platforms in one shot
• electron-publish publishes to GitHub Releases (requires GH_TOKEN)
• electron-lint FIX=true ESLint + Prettier with auto-fix pattern
• electron-typecheck TypeScript type checking
• VERBOSE=1 make show commands for debugging

Static Site (HTML/CSS/JS)

Plain static sites — landing pages, marketing pages, docs — with no bundler or SSR. Uses npx --yes for tooling so contributors don't need a local package.json or node_modules.

Copy templates/static-site.mk to your project root as Makefile.

Targets use site-* and dev-* prefixes (per §"Naming Conventions"). The template is deliberately slim — lint/link-check/image-optimization targets were cut because they're rarely run locally on a marketing page and collapse under the "too many granular dev-* quality targets" pitfall. Add them back only if a specific project needs them.

Key features:

• site-serve - local HTTP server via python3 -m http.server (falls back to npx serve). Override with make site-serve PORT=9000 HOST=0.0.0.0.
• site-open - open $(ENTRY) (default index.html) in the default browser (macOS open / Linux xdg-open).
• site-status - print site dir, entry, detected HTML pages, and tooling availability.
• dev-format - prettier --write across HTML/CSS/JS via npx --yes. No global install required, no FIX=true gate — always writes (formatting check-only is CI's job, not a local ergonomic).
• dev-asset-report - top 20 largest files (finds accidentally-committed hero images, uncompressed GIFs).
• dev-build - copies site into $(BUILD_DIR) (default dist/) via rsync with sensible excludes, then optionally minifies HTML/CSS/JS via html-minifier-terser (silently skipped if unavailable).
• dev-deploy - depends on dev-build; dispatches on DEPLOY_MODE (rsync | gh-pages | netlify | vercel | none). Fails fast with install hint if the selected tool is missing.
• dev-clean - removes $(BUILD_DIR)/.

Config knobs (?= — override on command line): SITE_DIR, PORT, HOST, ENTRY, BUILD_DIR, DEPLOY_MODE, RSYNC_DEST.

PostgreSQL + Alembic

Standalone template for database operations. Use alongside python-fastapi.mk for a full stack, or independently for any Python project with PostgreSQL.

Copy templates/postgres.mk to your project root (or include it from your main Makefile).

Key features:

• db-start / db-stop / db-clean via plain docker run (default) with health-check wait loop. Docker Compose variant is commented at the bottom of the template for multi-service setups.
• db-init composite target (start + migrate).
• db-reset has two flavors via HARD flag:
• HARD=false (default): kill connections → DROP DATABASE → CREATE → migrate. Fast, preserves container+volume.
• HARD=true: docker rm -f container + docker volume rm -f + re-init. Use when container/volume itself is in a broken state.
• db-migrate / db-revision Alembic migrations via uv run alembic; all Alembic recipes inline-source .env (via _check-env guard) so a stale shell DATABASE_URL can't override the configured value.
• db-migration-current / db-migration-history / db-migration-check introspection.
• db-shell (psql) / db-pgcli / db-pgweb shell access.
• db-pgcli strips the SQLAlchemy +psycopg dialect marker before handing the URL to pgcli (pgcli doesn't understand dialect markers).
• env-template bootstrap target that copies .template.env → .env without overwriting.
• db-logs / db-seed utilities.
• All config via ?= variables (PG_CONTAINER, PG_DB, PG_USER, PG_PASSWORD, PG_PORT=5433, PG_IMAGE).
• Port 5433 by default to dodge host Homebrew Postgres on 5432. Override with make db-start PG_PORT=5432 if your machine is clean.
• Driver: template targets psycopg[binary]>=3 (psycopg3). SQLAlchemy needs the postgresql+psycopg:// dialect marker; add a pydantic-settings validator that normalizes postgres:// / postgresql:// → postgresql+psycopg:// so Render's managed DB URL works verbatim.

Interaction Pattern (Phased)

Run these phases top-to-bottom on any Makefile scaffolding / refactor request. Do Phase 2 (Interactive questions) BEFORE writing any file — the answers drive which template variants to emit.

Phase 1 — Discovery

1. Is there already a Makefile? Read it first — match its conventions.
2. What stack / language? (Python+uv, FastAPI+Postgres, Node, Go, …)
3. What's the deployment target? (Render, Fly, Vercel, self-hosted, …) — affects run-api-prod.
4. How big is the project today, and how big will it reasonably grow? (≥5 targets expected → modular.)

Phase 2 — Interactive questions (ask in ONE batch via AskUserQuestion)

Ask up front rather than iterating. Typical questions:

• Structure: flat single file or modular (makefiles/*.mk)?
• Help style: rich categorized help with emoji headers, or minimal?
• Postgres port (if Postgres used): 5433 (default, dodges host Homebrew Postgres on 5432) or 5432?
• Test granularity: single dev-test (small/medium projects) or split test-unit / test-integration / test-e2e (larger projects)?
• Prod runtime: need a run-api-prod target against a remote DB (Render/Fly/etc.)?
• OpenAPI spec export (FastAPI): always include api-export-spec unless user declines — enables client SDK generation and spec-diff in CI.

Skip questions whose answer is already implied by an existing Makefile or strong project signal.

Phase 3 — Scaffold

Emit (in this order):

1. Makefile + makefiles/*.mk (if modular).
2. .template.env at repo root (committed).
3. .env is NOT created — leave that to make env-template. Add .env to .gitignore if not already there.
4. .env.prod — if run-api-prod was requested, confirm .env.prod is in .gitignore (it MUST be — production credentials).
5. scripts/export_openapi_spec.py (if FastAPI + api-export-spec).

Phase 4 — Verify

• make help — clean categorized output.
• make help-unclassified — should be empty or minimal.
• make -n run-api-local db-migrate api-export-spec — dry-run the critical paths.
• Grep for any _check-env / _check-postgres guards you added to confirm they fire when expected.

Naming Conventions

Use kebab-case with consistent prefix-based grouping:

# Good - consistent prefixes (hyphens, not underscores)
build-release, build-zip, build-clean    # Build tasks
dev-run, dev-clean                       # Development tasks
db-start, db-stop, db-migrate            # Database tasks
env-local, env-prod, env-show            # Environment tasks

# Internal targets - prefix with underscore to hide from help
_build-zip-internal, _prompt-version     # Not shown in make help

# Bad - inconsistent
run-dev, localEnv, test_net
build_release, dev_test                  # Underscores - don't use

Exception — universal unprefixed names. A handful of names are so de-facto standard across ecosystems (npm, cargo, go, make itself) that prefixing them with dev- adds noise without adding signal. Keep these unprefixed:

• test (not dev-test)
• build (not dev-build) — only if the project has no competing build-* group
• run (not dev-run) — same caveat
• format / lint — same caveat; if you have dev-format already, stay consistent within the project

Rule of thumb: if the unprefixed name would collide with a prefix group you already have (e.g., already have build-release, build-zip), keep the dev- prefix for consistency. Otherwise, drop it.

Name targets after the action, not the tool:

# Good - describes what it does
remove-bg          # Removes background from image
format-code        # Formats code
lint-check         # Runs linting

# Bad - names the tool
rembg              # What does this do?
prettier           # Is this running prettier or configuring it?
eslint             # Unclear

Key Patterns

Binary Distribution

For projects distributed as pre-built binaries via GitHub Releases:

GITHUB_REPO ?= owner/repo
OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
ARCH := $(shell uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')

.PHONY: install-cli
install-cli: ## Download and install CLI from latest GitHub release
	@RELEASE=$$(curl -fsSL https://api.github.com/repos/$(GITHUB_REPO)/releases/latest | grep tag_name | cut -d'"' -f4); \
	echo "Installing $$RELEASE for $(OS)/$(ARCH)..."; \
	curl -fsSL -o ~/.local/bin/cli \
		"https://github.com/$(GITHUB_REPO)/releases/download/$$RELEASE/cli-$(OS)-$(ARCH)"; \
	chmod +x ~/.local/bin/cli

Key considerations:

• Detect OS and architecture automatically
• Download from GitHub Releases (no Python/uv required)
• Install to ~/.local/bin (user-writable, in PATH)
• Preserve existing config files during updates

Always Use uv run for Python

# Good - uses uv run with ruff (modern tooling)
dev-check:
	uv run ruff check src/ tests/
	uv run ruff format --check src/ tests/
	uv run mypy src/

dev-format:
	uv run ruff check --fix src/ tests/
	uv run ruff format src/ tests/

# Bad - relies on manual venv activation
dev-format:
	ruff format .

Use uv sync (not pip install)

For Python projects, treat pyproject.toml and uv.lock as the source of truth. Do not add pip install or requirements.txt fallback guidance to uv-based templates.

env-install:
	uv sync  # Uses pyproject.toml + lock file

Categorized Help (for 5+ targets)

help:
	@printf "$(BOLD)=== 🚀 API ===$(RESET)\n"
	@printf "$(CYAN)%-25s$(RESET) %s\n" "api-run" "Start server"
	@printf "%-25s $(GREEN)make api-run [--reload]$(RESET)\n" ""

Makefile ordering rule - help targets go LAST, just before catch-all:

1. Configuration (?= variables)
2. HELP_PATTERNS definition
3. Imports (include ./makefiles/*.mk)
4. Main targets (grouped by function)
5. help: and help-unclassified: targets
6. Catch-all %: rule (absolute last)

Preflight Checks

_che

…

## Source & license

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

- **Author:** [Olshansk](https://github.com/Olshansk)
- **Source:** [Olshansk/agent-skills](https://github.com/Olshansk/agent-skills)
- **License:** MIT

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