makefile

name	makefile
description	Create or update a project's `Makefile` with standard developer targets. Use when the user asks for a Makefile, wants `make build`, `make test`, `make run`, `make check`, or `make help`, or wants plain `make` to print help by default. Inspect the repo first and wrap existing project commands instead of inventing a new workflow.
metadata	{"last-reviewed":"2026-04-15"}

Makefile

Create the smallest correct Makefile for the current project.

Goals

• Always provide build, test, run, check, format and help.
• Make help the default target with .DEFAULT_GOAL := help.
• Prefer thin wrappers around commands the project already uses.
• Keep check non-destructive.
• If a Makefile already exists, update it surgically instead of rewriting unrelated targets.

Workflow

1. Inspect the repo before editing.
2. Infer canonical commands from existing project files and docs:
   • package.json scripts and lockfiles
   • pyproject.toml, uv.lock, and test configuration
   • Cargo.toml
   • go.mod
   • existing CI config, README snippets, or task runners
3. Reuse the package manager or toolchain already present.
4. Prefer the project's named commands over ad hoc shell pipelines.
5. Ask only when a required target cannot be inferred safely and a fallback stub would be misleading.

Target Semantics

• build: compile, bundle, or package the project.
• test: run the automated test suite.
• run: start the main app, service, CLI, or dev server.
• check: run non-destructive verification. Prefer the project's existing check, lint, typecheck, vet, or similar commands. If there is no dedicated check command, combine the safest existing validations, usually build and test or lint and test.
• help: print documented targets.

Required Makefile Shape

Use documented targets with ## comments and an awk-based help target.

.DEFAULT_GOAL := help

.PHONY: help build test run check

help: ## Show available targets
	@printf "Available targets:\n"
	@awk 'BEGIN {FS = ":.*## "}; /^[a-zA-Z0-9_.-]+:.*## / {printf "  %-12s %s\n", $$1, $$2}' $(MAKEFILE_LIST)

build: ## Build the project
	...

test: ## Run tests
	...

run: ## Run the project
	...

check: ## Run project checks
	...

Stack Hints

• Node.js: prefer the detected package manager and existing scripts such as build, test, dev, start, lint, typecheck, or check.
• Python: prefer uv when present. Reuse existing entry points or documented commands instead of inventing a module path.
• Rust: prefer cargo build, cargo test, cargo run, cargo fmt --check, and cargo clippy -- -D warnings when those fit the repo.
• Go: prefer go build ./..., go test ./..., go run ., and non-mutating checks already used by the project.

Fallbacks

• Every required target must exist.
• If one target cannot be inferred, prefer an explicit failing stub over a fake success.
• Example last-resort stub:

run: ## Run the project
	@printf "No run command could be inferred for this project.\n" >&2
	@exit 1

Call out any fallback targets clearly in the final response.

Gotchas

• Do not make check run formatters that rewrite files.
• Do not hardcode secrets, ports, or machine-specific absolute paths.
• Do not replace existing, project-specific targets with generic ones unless the user asked for that.
• If the repo already has a help target, preserve its intent while ensuring plain make still shows help.

Validation

After editing:

1. Run make and confirm it prints help.
2. Run make help if you need a narrower check.
3. Run any inferred targets you changed when practical.
4. If a target cannot be verified because it needs external services or unavailable dependencies, say so explicitly.

Before major revisions, re-check https://agentskills.io/ for the current spec and guidance.

Agents

Agents should update thier knowledge (AGENT.md, CLAUDE.md etc) to prefer using make targets, especially make test