Skip to content
Skills Library
DevOps & cloud · Building & coding

dev-makefiles

/dev-makefiles

Governs ALL build/automation work in any repo that has (or should have) a Makefile — building, compiling, adding build targets, wiring test/install/run automation. Use when creating or modifying a Makefile, adding make targets, setting up a build system, creating makehelp.sh, migrating to the 2-layer convention, or whenever a plan step builds, compiles, or scripts a repeatable dev task — that work goes through make targets per this skill, not ad-hoc shell commands.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

93/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene13 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Governs ALL build/automation work in any repo that has (or should have) a Makefile — building, compiling, adding build targets, wiring test/install/run automation. Use when creating or modifying a Makefile, adding make targets, setting up a build system, creating makehelp.sh, migrating to the 2-layer convention, or whenever a plan step builds, compiles, or scripts a repeatable dev task — that work goes through make targets per this skill, not ad-hoc shell commands.

Arguments

/dev-makefiles [action] [details]
Original author description

Governs ALL build/automation work in any repo that has (or should have) a Makefile — building, compiling, adding build targets, wiring test/install/run automation. Use when creating or modifying a Makefile, adding make targets, setting up a build system, creating makehelp.sh, migrating to the 2-layer convention, or whenever a plan step builds, compiles, or scripts a repeatable dev task — that work goes through make targets per this skill, not ad-hoc shell commands.

How it works

  1. Task Workflow
  2. The 2-Layer System
  3. The Mantra (3 Rules)
  4. make all — the alias, not a second build path
  5. make run — the target every Makefile ships
  6. Toolchain Adaptation
  7. Complete Makefile Template
  8. Complete makehelp.sh Template
  9. Conventions
  10. Adding New Targets Checklist
Original SKILL.md headings · 523 lines, 3,425 words
SKILL.md preview
---
name: dev-makefiles
description: Governs ALL build/automation work in any repo that has (or should have) a Makefile — building, compiling, adding build targets, wiring test/install/run automation. Use when creating or modifying a Makefile, adding make targets, setting up a build system, creating makehelp.sh, migrating to the 2-layer convention, or whenever a plan step builds, compiles, or scripts a repeatable dev task — that work goes through make targets per this skill, not ad-hoc shell commands.
argument-hint: "[action] [details]"
version: 1.4.0
---

# Building Makefiles

Create and maintain Makefiles using the 2-layer system. If `$ARGUMENTS` is provided, interpret it as the task (e.g., "add test-e2e target", "create new Makefile for Python project", "migrate existing Makefile").

## Task Workflow

Follow these steps in order. The first decision determines which path to take.

### Step 1: Inventory EVERY Makefile in the repo

**Never assume there is one Makefile.** Repos routinely carry several — a root build, an experiment, a subpackage — at different conformance levels. Finding one that already conforms is not a reason to stop looking.

1. Discover them all:
   ```bash
   find . -name Makefile -not -path '*/vendor/*' -not -path '*/node_modules/*' -not -path '*/.git/*'
   ```
2. For each: does a sibling `makehelp.sh` exist, how many `##@` section headers does it have, and **does it define `all` and `run`**?
3. Identify the project's language/toolchain (go.mod, package.json, Cargo.toml, pyproject.toml, etc.)
4. **Print the inventory with a path assigned to each, before changing anything:**

   | Makefile | makehelp.sh | `##@` | `all` | `run` | Path |
   |---|---|---|---|---|---|
   | `./Makefile` | no | 0 | no | no | **C — migrate** |
   | `./experiment/policing/Makefile` | yes | 7 | `proto build` | no | B — maintain (**add `run`**, **normalize `all`**) |

   A missing `all` or `run` is a defect on every row it appears on, including rows that are otherwise
   conforming. Record what an existing `all` actually depends on — anything other than `build` alone needs
   normalizing, not preserving.

Every first-party Makefile gets a path. Vendored and third-party Makefiles are excluded — list them as excluded rather than omitting them silently.

### Step 2: Apply the right path to EACH Makefile

The path is chosen **per Makefile**, not per invocation. A repo with a non-conforming root and a conforming subproject needs Path C *and* Path B in the same run — they are independent, and a conforming Makefile elsewhere never excuses skipping a non-conforming one. Do the Path C migrations first, then the Path B maintenance.

**Path A — New Makefile (no Makefile exists):**
1. Identify the project's toolchain from existing config files
2. Set the Variables section using the Toolchain Adaptation table below
3. Generate both `Makefile` and `makehelp.sh` from the templates
4. Replace all `myapp` placeholders with the actual binary/project name
5. **Decide what `run` does** using the run ladder below, and write that into the target's help text
6. Confirm `all: build` is present — the template ships it; don't delete it as redundant
7. Make makehelp.sh executable: `chmod +x makehelp.sh`

**Path B — Add/modify targets (Makefile exists and follows 2-layer convention):**
0. **If `all` or `run` is missing, adding it is part of this pass** — not a follow-up. An `all` that depends
   on anything besides `build` gets normalized now (see `all` below)
1. Read the existing Makefile and makehelp.sh
2. Identify the correct `##@` section for the new target
3. Add the target with `.PHONY`, `## help text`, and recipe
4. If the recipe needs >10 lines or OS branching, delegate to makehelp.sh
5. If delegating: add both the `cmd_function()` and dispatcher entry in makehelp.sh

**Path C — Migrate existing Makefile (exists but doesn't follow 2-layer convention):**
1. Read the existing Makefile thoroughly — preserve ALL existing targets and behavior
2. Reorganize targets into the seven `##@` sections (General, Build, Test, Quality, Install, Development, Cleanup)
3. Add `.PHONY` declarations and `## help text` to every target
4. Add the `help` target and awk recipe
5. Extract any inline shell logic >10 lines into a new makehelp.sh
6. Create makehelp.sh with dispatcher if any logic was extracted
7. **Add `run` if the Makefile doesn't have one** — the run ladder below picks what it does
8. **Reconcile `all`**: absent, add `all: build`; present and depending on more than `build`, fold those
   prerequisites into `build` and reduce `all` to the alias
9. Verify: every original target still works the same way — `make all` included, which now goes through `build`

### Step 3: Validate

Validate **each** Makefile from the Step 1 inventory:

- Run `make help` to verify help output renders correctly
- Confirm all `##@` sections appear with their targets
- **Run `make all` and confirm it builds everything**, and that it is the alias, not a second build path
- **Confirm `run` appears in `make help`, and that its help text names the actual thing it runs** — "Run development version" is not a passing help line
- **Actually run `make run`.** It must build and reach the software's working state. For a long-running process, start it under a timeout (`timeout 15 make run`) and confirm it reaches its ready line rather than waiting for it to exit; kill it and confirm the terminal is clean
- If makehelp.sh was created/modified, verify it's executable and the dispatcher covers all delegated targets

Then **re-print the Step 1 inventory with an outcome on every row** — `migrated`, `maintained`, `already conforming`, `excluded (vendored)`, or `untouched (<reason>)`. A Makefile that appeared in the inventory and has no outcome is an incomplete run, not a finished one.

## The 2-Layer System

```
+-------------------------------------+
|           Makefile                   |  <- Declarative interface (WHAT)
|  targets, dependencies, help text   |     Short commands, readable
+-----------+-------------------------+
            | delegates via @./makehelp.sh <cmd>
+-----------v-------------------------+
|          makehelp.sh                 |  <- Imperative logic (HOW)
|  OS branching, multi-step ops,      |     Testable, maintainable
|  anything >10 lines                 |
+-------------------------------------+
```

## The Mantra (3 Rules)

1. **"If it's a build-time operation, it's in make"** — compiling, testing, linting, formatting, installing dev tools
2. **"If it's a runtime operation, it's in the CLI"** — daemon management, service lifecycle, version queries
3. **"Complex shell logic belongs in makehelp.sh, not inline"** — anything >10 lines, OS branching, multi-step ops

## `make all` — the alias, not a second build path

`build` is this convention's build-everything target and `.DEFAULT_GOAL := help` means bare `make` prints
help — but GNU convention, CI scripts and `make && make install` habits all type `all`. So **every Makefile
ships `all` as a one-line alias for `build`**, under `##@ Build`, no recipe:

```makefile
.PHONY: all
all: build  ## Alias for build — builds everything
```

**Never give `all` prerequisites of its own.** `all: check-tools build` and `all: proto build` are the failure
mode: `make all` and bare `make` then produce different results and nobody can say which one CI should call.
Whatever an existing `all` does beyond `build` belongs *in* `build`. One build path, two names for it.

`all` is never the `.DEFAULT_GOAL` — `help` is. Help text calling `all` "the default target" is the artifact
a migration leaves behind most often.

## `make run` — the target every Makefile ships

Two commands tell a stranger what a repo is: `make help` lists what they *can* do, and **`make run` shows them
the software doing its job**. `run` is therefore mandatory — in a new Makefile, in a migration, in a
maintenance pass on a Makefile that somehow never had one.

**The contract:**

- `run` depends on `build`, so it always exercises current code.
- `run` performs **the most common thing the software is designed to do** — the thing the README leads with,
  the reason someone installed it. Not `--help`. Not `--version`. Not a test suite standing in for a demo.
- `run` needs no arguments to be useful. `make run` with nothing after it does something real.
- `run` accepts `ARGS` for everything else: `make run ARGS="vm list --json"`.
- Its help text names the actual behavior: `## Run the dashboard at http://localhost:8080`, not
  `## Run development version`.

### The run ladder — pick the first row that matches the project

| Project shape | `make run` does |
|---|---|
| Single app or CLI binary | Runs it with the invocation the README leads with |
| Long-running service / server / daemon | Starts it in the foreground in dev mode, on its default port, printing the URL; `Ctrl-C` exits clean |
| CLI with subcommands | The most common subcommand (`serve`, `status`, `list`), overridable via `ARGS` |
| TUI / interactive app | Launches the interface |
| Multiple binaries | The **primary** one — the binary named after the repo, or the one the README leads with; each other binary gets its own `run-<name>` |
| Web frontend | The dev server (`npm run dev`), printing the URL |
| Data pipeline / batch job | One representative run against sample or fixture data — never against production inputs |
| Library with an example/demo | The canonical example program |
| Library with nothing runnable | The smoke path that proves the library works (a doc example, an example test), with one line saying that's what it is |

When two rows are arguable, pick the one a new contributor would want after `make build` — and record the
choice in the target's help text so nobody re-litigates it.

### Rules

- **Never leave `run` out**, and never stub it with `@echo "nothing to run"`. Every project can demonstrate
  itself; the bottom row of the ladder is the floor, not an excuse.
- **Never make `run` destructive.** It must be safe to type blind — no production endpoints, no writes
  outside the repo and its normal dev state, no `sudo`. Destructive work lives behind its own named target.
- **`run` fails loudly and usefully.** Missing config, missing service, missing credential → say which one and
  print the exact command that fixes it. Never a stack trace, never a silent exit 0.
- **Keep `run` in `##@ Development`** alongside `dev` and `cycle`.

## Toolchain Adaptation

When creating a Makefile, set the Variables section based on the project's language. Use this table:

| Variable | Go | Node/TypeScript | Python | Rust | Generic |
|----------|----|----|--------|------|---------|
| `BUILD_CMD` | `go build` | `npm run build` | `python -m build` | `cargo build` | `echo "no build step"` |
| `TEST_CMD` | `go test ./...` | `npm test` | `pytest` | `cargo test` | `echo "no tests"` |
| `LINT_CMD` | `golangci-lint run` | `eslint .` | `ruff check .` | `cargo clippy` | `echo "no linter"` |
| `FMT_CMD` | `gofmt -w .` | `prettier --write .` | `ruff format .` | `cargo fmt` | `echo "no formatter"` |
| `BINARY_DIR` | `./bin` | `./dist` | `./dist` | `./target` | `./build` |
| `COVERAGE_FILE` | `coverage.out` | `coverage/lcov.info` | `htmlcov/` | `tarpaulin-report.html` | `coverage/` |
| `CLEAN_EXTRAS` | `vendor` | `node_modules` | `__pycache__ *.egg-info .venv` | `target` | _(none)_ |

For the `build` target recipe, adapt accordingly:
- **Go**: `@$(BUILD_CMD) -o $(BINARY_DIR)/myapp ./cmd/myapp`
- **Node**: `@$(BUILD_CMD)`
- **Python**: `@$(BUILD_CMD)` (or skip if no build step)
- **Rust**: `@$(BUILD_CMD) --release` (for production)

Omit sections that don't apply (e.g., no `build-production` for a pure Python library), but keep the `##@` section header with at least one target in each section.

## Complete Makefile Template

**Include ALL seven ##@ sections. Adapt commands to the project's toolchain.**

```makefile
# ============================================================================
# Project Makefile
# ============================================================================
# 2-Layer System: This Makefile defines WHAT to do.
# Complex logic (>10 lines, OS branching) goes in makehelp.sh (HOW to do it).
# ============================================================================

.DEFAULT_GOAL := help

# ---------------------------------------------------------------------------
# Variables — adapt to your language/toolchain (see Toolchain Adaptation table)
# ---------------------------------------------------------------------------

# Tools
BUILD_CMD := go build
TEST_CMD := go test
LINT_CMD := golangci-lint run
FMT_CMD := gofmt -w .

# Paths
BINARY_DIR := ./bin
COVERAGE_FILE := coverage.out

# Derived
VERSION := $(shell git describe --tags 2>/dev/null || echo "0.0.0-dev")

# ---------------------------------------------------------------------------
# Targets
# ---------------------------------------------------------------------------

##@ General

.PHONY: help
help:  ## Display this help message
	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} \
		/^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } \
		/^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) }' $(MAKEFILE_LIST)

.PHONY: prereqs
prereqs:  ## Check and install prerequisites
	@./makehelp.sh prereqs

##@ Build

.PHONY: all
all: build  ## Alias for build — builds everything

.PHONY: build
build:  ## Build for local platform (debug mode)
	@$(BUILD_CMD) -o $(BINARY_DIR)/myapp ./cmd/myapp

.PHONY: build-production
build-production:  ## Build optimized production binaries
	@./makehelp.sh build-production $(VERSION)

##@ Test

.PHONY: test
test:  ## Run all tests
	@$(TEST_CMD) ./...

.PHONY: test-unit
test-unit:  ## Run unit tests only (fast, no external deps)
	@$(TEST_CMD) -short ./...

.PHONY: test-integration
test-integration:  ## Run integration tests (requires infrastructure)
	@$(TEST_CMD) -run Integration ./...

##@ Quality

.PHONY: lint
lint:  ## Run linter
	@$(LINT_CMD) ./...

.PHONY: fmt
fmt:  ## Format code
	@$(FMT_CMD)

.PHONY: check
check: lint test  ## Run lint + test together

##@ Install

.PHONY: install
install: install-dev  ## Alias for install-dev

.PHONY: install-dev
install-dev: build  ## Build and install as symlinks (for development)
	@./makehelp.sh install-dev

.PHONY: install-production
install-production: build-production  ## Build and install as copies (for production)
	@./makehelp.sh install-production

.PHONY: uninstall
uninstall:  ## Remove all installed files
	@./makehelp.sh uninstall

##@ Development

.PHONY: dev
dev: fmt test build  ## Format, test, and build

.PHONY: cycle
cycle: uninstall clean build install  ## Full clean rebuild and install

.PHONY: run
run: build  ## Run <what this software actually does> (ARGS="..." to pass arguments)
	@./makehelp.sh run $(ARGS)

##@ Cleanup

.PHONY: clean
clean:  ## Remove build artifacts
	@rm -rf $(BINARY_DIR) $(COVERAGE_FILE)

.PHONY: clean-all
clean-all: clean  ## Deep clean including vendor and cache
	@rm -rf vendor
	@$(BUILD_CMD) clean -cache 2>/dev/null || true
```

## Complete makehelp.sh Template

**Every target that delegates to makehelp.sh must have a matching function and dispatcher entry.**

```bash
#!/usr/bin/env bash
set -euo pipefail

# ============================================================================
# makehelp.sh — Complex logic extracted from Makefile
# ============================================================================
# The Makefile defines WHAT; this script implements HOW for anything too
# complex for inline make recipes (>10 lines, OS branching, multi-step ops).
# ============================================================================

BINARY_DIR="./bin"
INSTALL_DIR="${HOME}/.local/bin"

# ---------------------------------------------------------------------------
# Helper functions
# ---------------------------------------------------------------------------

check_command() {
    if ! command -v "$1" &>/dev/null; then
        echo "Error: $1 is required but not installed" >&2
        return 1
    fi
}

# ---------------------------------------------------------------------------
# Command functions
# ---------------------------------------------------------------------------

cmd_prereqs() {
    echo "Checking prerequisites..."
    case "$(uname -s)" in
        Darwin)
            echo "macOS detected"
            check_command brew || { echo "Install Homebrew first: https://brew.sh" >&2; exit 1; }
            # Adapt: replace with your project's toolchain packages
            brew install go golangci-lint
            ;;
        Linux)
            echo "Linux detected"
            if command -v apt-get &>/dev/null; then
                sudo apt-get update && sudo apt-get install -y golang
            elif command -v dnf &>/dev/null; then
                sudo dnf install -y golang
            fi
            ;;
        *)
            echo "Unsupported OS: $(uname -s)" >&2
            exit 1
            ;;
    esac
    echo "All prerequisites satisfied"
}

cmd_run() {
    # `run` = the most common thing this software does (see the run ladder).
    # Any ARGS the user passed arrive here as "$@" and replace the default invocation.
    local binary="${BINARY_DIR}/myapp"
    if [[ ! -x "$binary" ]]; then
        echo "Error: $binary not found (run 'make build' first)" >&2
        exit 1
    fi
    if [[ $# -gt 0 ]]; then
        exec "$binary" "$@"
    fi
    # Replace with this project's headline invocation — the one the README leads with.
    exec "$binary" serve --port 8080
}

cmd_build_production() {
    local version="${1:-$(git describe --tags 2>/dev/null || echo "0.0.0-dev")}"
    local ldflags="-s -w -X main.Version=${version}"
    local platforms=(
        "darwin/amd64"
        "darwin/arm64"
        "linux/amd64"
        "linux/arm64"
    )

    for platform in "${platforms[@]}"; do
        IFS='/' read -r os arch <<< "$platform"
        output="${BINARY_DIR}/myapp-${os}-${arch}"
        echo "Building ${output}..."
        CGO_ENABLED=0 GOOS=$os GOARCH=$arch go build -ldflags="${ldflags}" -o "$output" ./cmd/myapp
    done
}

cmd_install_dev() {
    # install-dev creates SYMLINKS so rebuilds work without reinstalling
    mkdir -p "$INSTALL_DIR"
    local binary="${BINARY_DIR}/myapp"
    ln -sf "$(pwd)/${binary}" "${INSTALL_DIR}/myapp"
    echo "Installed: ${INSTALL_DIR}/myapp -> $(pwd)/${binary} (symlink)"
}

cmd_install_production() {
    # install-production COPIES binaries (self-contained, works after source removal)
    mkdir -p "$INSTALL_DIR"
    local os arch binary
    os="$(uname -s | tr '[:upper:]' '[:lower:]')"
    arch="$(uname -m)"
    [[ "$arch" == "x86_64" ]] && arch="amd64"
    [[ "$arch" == "aarch64" ]] && arch="arm64"
    binary="${BINARY_DIR}/myapp-${os}-${arch}"

    cp -f "$binary" "${INSTALL_DIR}/myapp"
    chmod +x "${INSTALL_DIR}/myapp"
    echo "Installed: ${INSTALL_DIR}/myapp (copy)"
}

cmd_uninstall() {
    rm -f "${INSTALL_DIR}/myapp"
    echo "Uninstalled: ${INSTALL_DIR}/myapp"
}

# ---------------------------------------------------------------------------
# Dispatcher — one entry per makehelp.sh-delegated target
# ---------------------------------------------------------------------------

case "${1:-}" in
    prereqs)            cmd_prereqs ;;
    run)                shift; cmd_run "$@" ;;
    build-production)   cmd_build_production "${2:-}" ;;
    install-dev)        cmd_install_dev ;;
    install-production) cmd_install_production ;;
    uninstall)          cmd_uninstall ;;
    *)
        echo "Usage: $0 {prereqs|run|build-production|install-dev|install-production|uninstall}" >&2
        exit 1
        ;;
esac
```

## Conventions

### Naming
- **Lowercase with hyphens**: `test-unit`, `build-production`, `install-dev`
- **Not**: `testUnit`, `build_production`, `TEST`

### Help Annotations
```makefile
##@ Section Name                    # Section header in help output
.PHONY: target-name
target-name:  ## Short description  # Help text for this target
	@command
```

### When to Delegate to makehelp.sh
- More than ~10 lines of shell in a single target
- OS-specific branching (Darwin vs Linux)
- Multi-step operations with user prompts
- Reusable logic needed by multiple targets

### Key Target Relationships
- `all` is always an **alias** for `build` (via dependency, no recipe, no extra prerequisites)
- `install` is always an **alias** for `install-dev` (via dependency, no recipe)
- `install-dev` depends on `build` (builds first, then symlinks)
- `install-production` depends on `build-production` (builds optimized, then copies)
- `run` depends on `build` (always runs current code) and is **mandatory in every Makefile**
- `check` depends on `lint` and `test` (runs both)
- `dev` depends on `fmt`, `test`, `build` (developer workflow chain)
- `cycle` depends on `uninstall`, `clean`, `build`, `install` (full rebuild)
- `clean-all` depends on `clean` (extends it)

## Adding New Targets Checklist

1. Choose the right `##@` section (General, Build, Test, Quality, Install, Development, Cleanup)
2. Use `lowercase-with-hyphens` naming
3. Add `.PHONY` declaration
4. Add `## Description` help annotation
5. Decide: inline command or `@./makehelp.sh target-name`?
6. If makehelp.sh: add `cmd_target_name()` function AND dispatcher entry

## Edge Cases

**Empty ##@ section**: Keep the section header even if there's only a placeholder target. All seven sections must appear for consistency. Use a comment like `# No targets yet` only as last resort — prefer adding at least the standard target for that section.

**Project has no build step** (e.g., pure scripting language): Replace the `build` target recipe with `@echo "No build step required"` but keep the target so `all`, `dev` and `cycle` chains still work.

**Project has no installable binary**: Remove `install-dev`, `install-production`, and `uninstall` target *recipes* but keep stub targets with `@echo "Nothing to install"` so `cycle` doesn't break.

**Multiple binaries**: Add one `build-<name>` target per binary under `##@` Build, and have the main `build` target depend on all of them: `build: build-foo build-bar` — which is what keeps `all` a plain alias. `run` runs the primary binary; each other binary gets `run-<name>`.

**Nothing obvious to run** (pure library, config repo, docs site): the run ladder's bottom rows still apply — the canonical example, or the smoke path that proves the thing works, with one line of output saying so. `run` is never omitted and never a no-op echo.

**`run` needs a service or credential**: `run` checks for it first and fails with the exact fix (`Error: no database at $DATABASE_URL — start one with: make dev-db`). It never starts production dependencies and never prompts for a secret.

**Makefile includes other Makefiles**: The help awk recipe uses `$(MAKEFILE_LIST)` so included targets will appear in help automatically. Ensure included files use the same `##@` and `##` conventions.

**Windows compatibility**: makehelp.sh is bash-only. If Windows support is needed, note it in the Makefile header and provide PowerShell alternatives in a separate `makehelp.ps1`, delegated the same way.

## What NOT to Do

- **Don't stop at the first Makefile you find** — inventory the whole repo (Step 1). A conforming subproject Makefile does not mean the repo conforms.
- **Don't silently leave a non-conforming Makefile untouched.** If you have been told not to modify one, honor that — then report it as non-conforming *and name where the constraint came from*: the user's instruction in this session, or the file and line that states it. An "off limits" you cannot source is not a constraint; verify it before letting it block a migration.
- **Don't ship a Makefile without `all`** — and don't give it prerequisites `build` doesn't have; that splits one build into two commands that disagree
- **Don't ship a Makefile without `run`** — it's mandatory, and a migration that leaves it out is unfinished
- **Don't let `run` print a help screen or a version string** — it runs the software doing its actual job
- **Don't put runtime operations in make** — daemon start/stop, service management, and version queries belong in the CLI
- **Don't inline complex shell in Makefile recipes** — if it's >10 lines or has `if/case`, move it to makehelp.sh
- **Don't use tabs inconsistently** — Makefile recipes MUST use tabs, not spaces
- **Don't skip `.PHONY`** — every target that doesn't produce a file needs it
- **Don't omit `## help text`** — every target must appear in `make help` output

## See Also

- `REFERENCE.md` — Install modes explained, optional targets, worked application example
Files in this package (2)
  • REFERENCE.md 9 KB
  • SKILL.md 24 KB

Versions

The database has no other skills named dev-makefiles.

Database snapshot: 13.11.2026 · package version 8a7f7a3c3f4d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95makefile
    GNU Make automation and build system guidance. Use when creating or maintaining Makefiles, writing Make targets and recipes, or configuring GNU Make build automation. Keywords: Makefile, GNU Make, targets, recipes, build automation.
  • 100init-makefiles
    Use if scaffolding Makefile targets for dev, tunnels, deploys, R2, Supabase, Railway, Vercel.
  • 100makefile-pro
    Generate, scaffold, validate and lint Makefiles and .mk files: .PHONY targets, build automation, common mistakes. Use for any Makefile work.
  • 100makefile-authoring-and-validation
    Authors Makefiles as a build/automation entry point for ops tasks — `.PHONY` target conventions, dependency graphs between targets, variable/default handling, and self-documenting `help` targets — and validates them with `make -n` (dry-run) and `checkmake`/shellcheck-style…
  • 100makefile
    Use when creating Makefiles for process lifecycle management with PID tracking, logging, and status monitoring. Triggers on: 'use makefile mode', 'makefile', 'create makefile', 'process management', 'background jobs', 'start/stop services'. Full access mode - can create/modify Makefiles.
  • 100makefile-generation
    Generates Makefiles with testing, linting, formatting, and automation targets. Use when starting a project or standardizing build automation.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.