AI assistant

AI assistant

ncmake ships a skill file that teaches an AI coding assistant how the Makefile works. It lives at skills/ncmake/SKILL.md in the repository and is not needed for anything else: no build or release target reads it, and an app repository never contains it.

📥 Installing it

In any ncmake app:

make skill-install

It fetches the file from the same NCMAKE_REF as the Makefile, so an app pinned to a tag gets the skill that describes that tag, and puts it into ~/.claude/skills/ncmake/. That location is per machine and covers every ncmake app you work on. skill_dir picks another one, on the command line or in ncmake.mk: make skill-install skill_dir=.claude/skills/ncmake scopes the skill to a single app; keep it out of the commit, or commit it if your team wants it shared. make help shows whether a copy exists in skill_dir.

Without an ncmake app at hand, for example to let the assistant convert an app to ncmake, fetch the file directly:

mkdir -p ~/.claude/skills/ncmake
curl -fsSL https://raw.githubusercontent.com/ernolf/ncmake/main/skills/ncmake/SKILL.md -o ~/.claude/skills/ncmake/SKILL.md

It is plain Markdown with a short YAML front matter, so any assistant that reads project instructions can use it, whether or not it calls them skills.

📚 What it contains

The skill file is written against the live Makefile, not against this wiki:

• how to recognise an ncmake app, and that the stub belongs in the repository root as GNUmakefile
• the ground rules an assistant otherwise gets wrong, starting with make build, which already runs composer install --no-dev and the frontend install and build
• a lookup table from job to target
• the four container images, PHP=min|max and RUNTIME=
• the keep model and what check-build does
• the release order, the developer modules, the App Store module, the workflow manager and the updater
• the four analysers: bundle-report and build-audit on the bundle, consistency-audit and build-verify on the checkout, and that none of them writes into the app
• the workflows ncmake ships, and the three-line contract that adds a workflow source in ncmake.mk
• fourteen failure messages with cause and remedy

🔒 What it does not let an assistant do

One rule in the file separates the targets that only read from the ones that commit, tag, push, sign or write to the App Store. Reading targets are fair game on the assistant's own initiative; everything else runs only when you say so, one step per request. That is the reason to hand the assistant this file rather than let it guess: a wrong guess at make tag or make publish is public.

🔄 Keeping it current

The file tracks main like the rest of ncmake, but unlike the cached Makefile it is a copy, so it does not refresh itself. make skill-install again, best right after make self-update, compares the copy with the current file and replaces it when they differ.

Tip

If your assistant supports project instructions of its own (CLAUDE.md, AGENTS.md or similar), keep them for what is specific to your app and leave ncmake to the skill file. Duplicating target descriptions is how the two drift apart.