creating-makefile

Creating Makefiles

Target: $ARGUMENTS

Creates or reviews a rigorous, consistent Makefile following org conventions.

References

• Required structure + patterns: references/makefile-conventions.md
• CI linter script: references/lint-makefile.sh
• Language-specific recipe templates: references/scaffold-*.md

Required Structure (all project types)

Every Makefile must have these elements in order:

# Header comment describing the project
# Run `make` to see all available recipes.

# GNU Make version guard
ifeq ($(filter oneshell,$(.FEATURES)),)
$(error GNU Make >= 3.82 required (.ONESHELL). macOS ships 3.81 — install via: brew install make, then use gmake)
endif

.SILENT:
.ONESHELL:
.PHONY: \
    recipe_a recipe_b \
    help
.DEFAULT_GOAL := help

# -- config --
VERBOSE ?= 0
ifeq ($(VERBOSE),0)
  # quiet flags per tool
endif

Conventions

• snake_case for all recipe names
• ## description comment on every public recipe (for help output)
• # MARK: SECTION to group related recipes
• setup_* prefix for installation recipes (never bare install)
• validate chains lint + test (when both exist)
• Idempotent setup: command -v X >/dev/null || install X
• No hardcoded paths — use variables at top of file
• VERBOSE ?= 0 with conditional quiet flags per tool
• Zero-sudo installs — use ~/.local/bin or ~/.local/share/<tool>, never sudo apt/dnf
• export PATH=... inside recipes that invoke tools installed to a non-default prefix (e.g. user-local npm)

Approach

1. Detect what kind of project this is — look at build files, dependency manifests, and source file types in the working directory. If $ARGUMENTS names a type, use that instead.
2. Find a scaffold — list references/scaffold-*.md in this skill's directory. If one matches the detected project type, read it for language-specific recipe templates. If none matches, build recipes from first principles using the conventions above.
3. Merge the scaffold's recipes with the required structure (version guard, .SILENT, .ONESHELL, .PHONY, help, config variables). The scaffold provides the MARK sections and recipe bodies; the required structure wraps them.
4. Check if a Makefile already exists — if yes, review it against conventions and the scaffold. If no, create one from the merged template.
5. Lint with references/lint-makefile.sh — fix any failures.
6. Verify make help renders all recipes, make validate (or make lint) runs clean.