/makefile-validator

name: makefile-validator
description: Validate, lint, audit, or check Makefiles and .mk files for errors.

Makefile Validator

Overview

Use this skill to validate Makefiles with a local-first, deterministic flow.

Default validator entrypoint:

bash scripts/validate_makefile.sh <makefile-path>

Validation layers:

1. Dependency preflight (`python3`, `pip3`, `make`) 2. GNU make syntax check (`make -n --dry-run`) when `make` is available 3. `mbake validate` 4. `mbake format --check` 5. Custom security, best-practice, and optimization checks 6. Optional `checkmake` and `unmake` checks when installed

Trigger Guidance

Use this skill when the request includes Makefile quality, linting, validation, hardening, or troubleshooting.

Trigger Phrases

• "Validate this Makefile"
• "Lint my `.mk` file"
• "Find issues in this build Makefile"
• "Check Makefile security problems"
• "Review this Makefile before CI"

Non-Trigger Examples

• Creating a brand new Makefile from scratch (use `makefile-generator`)
• Running build targets as part of delivery
• General shell scripting work unrelated to Makefiles

Deterministic Execution Model

Run from this skill directory for shortest commands:

cd devops-skills-plugin/skills/makefile-validator

Step 1: Preflight

1. Confirm target file exists and is readable. 2. Confirm whether file edits are allowed (`writable`) or only suggestions can be returned (`read-only`). 3. Prefer the default validator path first; use fallbacks only when blocked by environment constraints.

Step 2: Baseline Validation (Default Path)

# From skill directory
bash scripts/validate_makefile.sh <makefile-path>

# From repository root
bash devops-skills-plugin/skills/makefile-validator/scripts/validate_makefile.sh <makefile-path>

Always record:

• command executed
• exit code
• summary counts (`Errors`, `Warnings`, `Info`)
• issue locations reported by tools

Step 3: Interpret Output and Exit Code

| Exit code | Meaning | Expected summary line | Action | | --- | --- | --- | --- | | `0` | no blocking findings | `Validation PASSED` | optional improvements only | | `1` | warning-only result | `Validation PASSED with warnings` | fix recommended; merge policy dependent | | `2` | error result | `Validation FAILED - errors must be fixed` | fix required, then rerun |

Step 4: Progressive Reference Loading

Open only the docs required by the current findings.

| Finding type | Reference doc | | --- | --- | | `.PHONY`, `.DELETE_ON_ERROR`, `.ONESHELL`, variable usage, performance structure | `docs/best-practices.md` | | tabs vs spaces, dependency mistakes, credential patterns, anti-patterns | `docs/common-mistakes.md` | | `mbake` behavior, formatter flags, known `mbake` caveats | `docs/bake-tool.md` |

Step 5: Fix + Rerun Loop

After applying fixes, rerun:

bash scripts/validate_makefile.sh <makefile-path>

Loop rules:

1. Stop only when no new errors are introduced. 2. If warnings remain intentionally, document why they are accepted. 3. Always report the latest rerun exit code.

How to Open Docs

Use explicit file-open commands so paths are unambiguous.

From repository root:

sed -n '1,220p' devops-skills-plugin/skills/makefile-validator/docs/best-practices.md
sed -n '1,220p' devops-skills-plugin/skills/makefile-validator/docs/common-mistakes.md
sed -n '1,220p' devops-skills-plugin/skills/makefile-validator/docs/bake-tool.md
rg -n "PHONY|DELETE_ON_ERROR|ONESHELL|tab|credential|mbake" devops-skills-plugin/skills/makefile-validator/docs/*.md

From `devops-skills-plugin/skills/makefile-validator`:

sed -n '1,220p' docs/best-practices.md
sed -n '1,220p' docs/common-mistakes.md
sed -n '1,220p' docs/bake-tool.md
rg -n "PHONY|DELETE_ON_ERROR|ONESHELL|tab|credential|mbake" docs/*.md

If shell commands are unavailable, use the environment's file-open/read actions on the same paths.

Fallback Behavior

Use these only when the default validator path cannot run fully.

| Constraint | Fallback action | Reporting requirement | | --- | --- | --- | | `python3` or `pip3` unavailable | Run limited checks (`make -f <file> -n --dry-run` if `make` exists, plus focused `grep` checks) | State that `mbake` stages were skipped and coverage is reduced | | `pip3 install mbake` fails (offline/proxy/index issue) | Keep syntax/custom checks that still work; defer formatter/linter stages | Report install failure and request rerun in a network-enabled environment | | `make` unavailable | Continue with non-syntax stages; script already downgrades syntax stage | Explicitly note syntax coverage was skipped | | `checkmake` or `unmake` unavailable | Continue; these are optional stages | Note optional lint/portability coverage not executed | | target file is read-only | Provide patch suggestions only | Mark response as advisory only | | command execution unavailable | Provide static review from file contents and docs | Mark result as non-executed analysis |

Minimal fallback commands:

# Syntax only (when make exists)
make -f <makefile-path> -n --dry-run

# Focused quick checks
grep -n "^\\.DELETE_ON_ERROR:" <makefile-path>
grep -n "^\\.PHONY:" <makefile-path>
grep -nE "^(  |    |        )[a-zA-Z@\\$\\(]" <makefile-path>

Example Outcomes Mapped to Exit Codes

Clean Result (`exit 0`)

Errors:   0
Warnings: 0
Info:     2
✓ Validation PASSED

Warning-Only Result (`exit 1`)

Errors:   0
Warnings: 3
Info:     1
⚠ Validation PASSED with warnings

Error Result (`exit 2`)

Errors:   2
Warnings: 1
Info:     0
⚠ Validation FAILED - errors must be fixed

Troubleshooting Quick Start

1. Verify required tools:

command -v python3 pip3 make

2. Isolate GNU make syntax failures:

make -f <makefile-path> -n --dry-run

3. Check likely tab-indentation violations:

grep -nE "^(  |    |        )[a-zA-Z@\\$\\(]" <makefile-path>

4