cmd-makefile

Files (37)

• SKILL.md
• colors.mk · modules/
• common.mk · modules/
• help.mk · modules/
• gen_todo.py · modules/todo-scripts/
• todo.mk · modules/
• reference.md
• base.mk · templates/
• build.mk · templates/chrome-extension-modules/
• colors.mk · templates/chrome-extension-modules/
• common.mk · templates/chrome-extension-modules/
• dev.mk · templates/chrome-extension-modules/
• env.mk · templates/chrome-extension-modules/
• test.mk · templates/chrome-extension-modules/
• chrome-extension.mk · templates/
• build.mk · templates/electron-modules/
• colors.mk · templates/electron-modules/
• common.mk · templates/electron-modules/
• dev.mk · templates/electron-modules/
• lint.mk · templates/electron-modules/
• electron.mk · templates/
• build.mk · templates/flutter-modules/
• colors.mk · templates/flutter-modules/
• common.mk · templates/flutter-modules/
• deploy.mk · templates/flutter-modules/
• dev.mk · templates/flutter-modules/
• lint.mk · templates/flutter-modules/
• flutter.mk · templates/
• go.mk · templates/
• nodejs.mk · templates/
• .template.env · templates/postgres-env/
• postgres.mk · templates/
• .template.env · templates/python-fastapi-env/
• export_openapi_spec.py · templates/python-fastapi-scripts/
• python-fastapi.mk · templates/
• python-uv.mk · templates/
• static-site.mk · templates/

SKILL.md (first lines)

# Makefile Helper

Create Makefiles that are simple, discoverable, and maintainable.

## Core Principles

1. **Default to rich help** - Use categorized help with emoji headers unless user requests minimal
2. **Default Chrome extensions to modular** - Use the modular `makefiles/*.mk` layout with shared colors/help for Chrome extension projects unless the repo is truly tiny
3. **Ask about structure upfront** - For new Makefiles, ask: "Flat or modular? Rich help or minimal?"
4. **Follow existing conventions** - Match the project's style if Makefile already exists
5. **Don't over-engineer** - Solve the immediate need, not hypothetical futures
6. **Use `uv run`** - Always run Python commands via `uv run` for venv context
7. **Explain decisions** - If choosing flat/minimal, explain why before generating

## When to Use This Skill

- Creating a new Makefile for a project
- Adding specific targets to an existing Makefile
- Improving/refactoring an existing Makefile
- Setting up CI/CD make targets
- Distributing pre-built binaries via GitHub Releases

## Quick Start

For new projects, use the appropriate template:

| Project Type | Template | Complexity | Asks upfront |
|-------------|----------|------------|------|
| Any project | `templates/base.mk` | Minimal | — |
| Python with uv | `templates/python-uv.mk` | Standard | — |
| Python FastAPI | `templates/python-fastapi.mk` | Full-featured | test split? prod target? `HEALTH_PATH`? |
| PostgreSQL + Alembic | `templates/postgres.mk` | Standard | `PG_PORT` (5433 default)? soft vs HARD reset? |
| Node.js | `templates/nodejs.mk` | Standard | — |
| Go | `templates/go.mk` | Standard | — |
| Chrome Extension | `templates/chrome-extension.mk` | Modular | — |
| Flutter App | `templates/flutter.mk` | Modular | — |
| Electron App | `templates/electron.mk` | Modular | — |
| Static Site (HTML/CSS/JS) | `templates/static-site.mk` | Standard | `DEPLOY_MODE` (rsync/gh-pages/netlify/vercel/none)? |

For templates in the "Asks upfront" column, run the Phase 2 interactive questions in §"Interaction Pattern" before scaffolding. Companion files:

- `templates/python-fastapi-env/.template.env` → project's `.template.env`
- `templates/python-fastapi-scripts/export_openapi_spec.py` → `scripts/export_openapi_spec.py`
- `templates/postgres-env/.template.env` → merge into project's `.template.env` (don't ship two)

### Chrome Extension Structure

The chrome extension template uses a modular structure:

```
Makefile                              # Main file with help + includes
makefiles/
  colors.mk                           # ANSI colors & print helpers
  common.mk                           # Shell flags, VERBOSE mode, guards
  build.mk                            # Build zip, version bump, releases
  dev.mk                              # Lint, clean, install
  test.mk                             # Unit tests, E2E tests, coverage
  env.mk                              # Environment setup, dependency checks
```

Copy from `templates/chrome-extension-modules/` to your project's `makefiles/` directory.

**Key features:**
- Use `makefiles/colors.mk` for ANSI color output and header helpers.
- Use `makefiles/common.mk` for shell flags, guard rails, and shared variables.
- Use `makefiles/env.mk` for environment checks and dependency sanity.
- Use `makefiles/build.mk` for build/package/release targets.
- Use `makefiles/dev.mk` for install, watch, clean, and other local workflows.
- Use `makefiles/test.mk` for typecheck, unit, and E2E targets when present.
- `build-release` - Version bump menu (major/minor/patch) + zip for Chrome Web Store
- `build-beta` - (Optional) GitHub releases with `gh` CLI
- `test-unit` / `test-e2e` - Vitest + Playwright testing
- `test-unit-<module>` / `test-e2e-<module>` - Per-module test targets
- `VERBOSE=1 make <target>` - Show commands for debugging

### Flutter App Structure

```
Makefile                    # Main file with help + includes
makefiles/
  colors.mk                # ANSI colors & print helpers
  common.mk                # Shell flags, VERBOSE mode, guards
  dev.mk                   # Setup, run simulator/device, devices, clean
  build.mk                 # iOS/Android builds (IPA, APK, AAB)
  deploy.mk                # TestFlight upload
  lint.mk                  # Dart analyze & format
```

Copy from `templates/flutter-modules/` to your project's `makefiles/` directory.

**Key features:**
- `flutter-run-ios` auto-boots simulator and waits for it
- `flutter-run-android` auto-launches emulator and waits for it
- `flutter-run-device` auto-detects or uses `FLUTTER_IOS_DEVICE` / `FLUTTER_ANDROID_DEVICE`
- `flutter-build-ipa` + `flutter-export-ipa` + `flutter-deploy-testflight` full iOS release workflow
- `flutter-export-ipa` re-exports IPA from existing archive without rebuilding
- `_check-asc-app` pre-flight App Store Connect validation (with ASC_API_KEY/ASC_API_ISSUER)
- `flutter-lint FIX=true` Dart formatting with FIX pattern
- `VERBOSE=1 make <target>` show commands for debugging

### Electron App Structure

```
Makefile                    # Main file with help + includes
makefiles/
  colors.mk                # ANSI colors & print helpers
  common.mk                # Shell flags, VERBOSE mode, guards
  dev.mk                   # Setup, dev server, debug, clean
  build.mk                 # Pack-check, dist (mac/win/linux), publish
  lint.mk                  # ESLint, Prettier, TypeScript, tests
```

Copy from `templates/electron-modules/` to your project's `makefiles/` directory.

**Key features:**
- `electron-dev` starts dev mode with hot-reload
- `electron-debug` launches with DevTools open
- `electron-clean` single target that removes artifacts, node_modules, and lock file
- `electron-pack-check` smoke-tests that the app loads without errors

From Olshansk/agent-skills, MIT.

More from Olshansk/agent-skills