AGENT SKILL
makefile-help
Annotate a Makefile with self-documenting help targets. Adds a `help` target as the default and appends inline descriptions to every user-facing target.
- License 许可
- MIT
- 最近更新
- 2026-09-17
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- makefile-help
- description
- Annotate a Makefile with self-documenting help targets. Adds a `help` target as the default and appends inline descriptions to every user-facing target.
- when_to_use
- annotate makefile, makefile help, document makefile, add makefile comments, self-documenting make targets, onboard makefile
02 资源文件 1
- 参考文档README.md3.4 KB
03 SKILL.md 正文
Annotate Makefile with Self-Documenting Help
Task
Read the Makefile at $filepath (if no path given, look for Makefile or GNUmakefile in the working directory). Add self-documenting help annotations to all user-facing targets.
The Pattern
Every user-facing target gets a ## Description annotation inline on the : line:
target-name: dependencies ## Short description of what this target does
recipe commands
The help target must be the first target in the file (making it the default). It uses this exact recipe:
help: ## Display available targets
@awk 'BEGIN {FS = ":.*## "}; /^[a-zA-Z0-9_-]+:.*## / {printf "\033[36m%-28s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
Rules
helpmust be the first target somakewith no arguments shows help.- Annotate every target that a user would invoke directly.
- Do NOT annotate internal/helper targets prefixed with
_or.. - Descriptions must be:
- A single line, no period at the end
- Imperative mood ("Build the binary" not "Builds the binary")
- Under 60 characters
- Specific enough to distinguish from other targets
- Preserve existing behavior — only add/modify the
## commentportion. Never change target names, dependencies, or recipes. - If
helpalready exists, verify it uses the correct awk pattern and update if needed. - Keep related targets adjacent. Do not reorder unrelated targets.
- If a
.PHONYdeclaration exists, addhelpto it. - If an explicit
.DEFAULT_GOALis set, do not change it. Thehelptarget will still be the first target in the file, but the default goal will remain as specified.
Procedure
- Read the entire Makefile.
- If no
helptarget exists, insert it as the first target (after variable declarations,.PHONY, or includes at the top). - For each user-facing target, determine its purpose from the recipe and add
## Descriptioninline. - Write back the updated Makefile using Edit.
Example
Before:
build:
go build -o bin/app ./cmd/app
test:
go test ./...
lint:
golangci-lint run
After:
help: ## Display available targets
@awk 'BEGIN {FS = ":.*## "}; /^[a-zA-Z0-9_-]+:.*## / {printf "\033[36m%-28s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
build: ## Build the application binary
go build -o bin/app ./cmd/app
test: ## Run the test suite
go test ./...
lint: ## Run the linter
golangci-lint run
Validation
After updating, confirm:
make(no args) would print the help table- Every public target has a
## Description - No internal targets leak into help output
- The awk field separator
:.*##matches all annotated lines