# Makefile Development

> This skill should be used when the user asks to "create a Makefile", "write a Makefile", "add a make target", or mentions Makefile conventions.

- Skill: `dwmkerr/makefile-development` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dwmkerr/makefile-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dwmkerr/makefile-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dwmkerr (https://skillmd.com/u/dwmkerr)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/dwmkerr/makefile-development

---


# Makefile Development

Create Makefiles following consistent conventions.

## Template

```makefile
default: help

.PHONY: help
help: # Show help for each of the Makefile recipes.
	@grep -E '^[a-zA-Z0-9 -]+:.*#'  Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done

.PHONY: init
init: # Initialise the development environment.
	./scripts/init.sh
```

## Conventions

| Element | Convention |
|---------|------------|
| Filename | `Makefile` (capitalised, no extension) |
| Default target | `default: help` as the first line |
| `.PHONY` | Declare directly above each target |
| Help comments | Single `#` on the target line: `target: # Description.` |
| Target names | Lowercase, hyphen-separated (`test-e2e`, `type-check`) |
| Complex logic | Delegate to scripts (`./scripts/build.sh`) rather than inline |

## Help Target

The self-documenting help target parses `#` comments and prints sorted, colour-coded output:

```makefile
.PHONY: help
help: # Show help for each of the Makefile recipes.
	@grep -E '^[a-zA-Z0-9 -]+:.*#'  Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done
```

Every target must have a `# Description.` comment or it won't appear in help output.

## Common Targets

| Target | Purpose |
|--------|---------|
| `help` | Show available targets (always present) |
| `init` or `setup` | Install dependencies, configure environment |
| `build` | Compile or bundle artifacts |
| `dev` | Start local development server |
| `test` | Run test suite |
| `lint` | Run linters and formatters |

## Important

After creating or modifying Makefiles, remind the user:

> **Use tabs.** Makefile recipes require literal tab characters for indentation, not spaces.