Skill: Nutrition Goals

Needs the Cook MCP server (tools like render_report and validate). If these tools are missing, the Cook MCP server isn't connected: if you installed the cooklang plugin or extension, check that its cook server is running (e.g. /mcp) or reinstall it; otherwise add it from https://github.com/cook-md/cook-mcp. Never estimate nutrition from your own knowledge instead.

Use when the user wants to change a recipe or meal plan so it hits numeric nutrition targets — "make this 600 kcal per serving", "get my week to 150 g protein per day", "more protein, same calories". You measure with the Cook nutrition service (through render_report), choose edits, verify them before saving, save, and confirm.

Nutrition data needs a cook.md login and Cook Basic or Cook Pro. On "authentication required" call login; on "subscription required" show the user the pricing link from the error. The direct nutrition tools (get_nutrition, aggregate_nutrition, lookup_ingredient, …) return JSON login_required (call login) or plan_required (show the user checkout_url) instead.

This skill changes food to reach numbers. For evaluation-only questions where no change is wanted ("is this healthy?", "how much protein is in this?"), follow the nutrition-reports skill instead.

Not for selection. "Find me three dinners over 35% protein", "which of my recipes are high protein", "plan a week that averages 150 g protein from what I already have" are screening requests: nothing gets edited, and the number is a filter over existing files. Running this skill's per-file measure-and-edit loop over a candidate list is how a three-dinner question turns into a hundred tool calls. Follow nutrition-reports (its "Screening a shortlist" section) and, if a .menu is wanted at the end, meal-planning. Come back here only once a specific file has been chosen and has to change to hit the number.

The loop

1. Pin down the target (nutrient, value, basis, tolerance).
2. Measure the baseline and per-ingredient contributions.
3. Choose edits — tiered, minimally invasive.
4. Verify the edited text BEFORE saving.
5. Save the edit and present current → new vs target.
6. Re-measure the saved file to confirm.
7. Offer to save the targets as a reusable checks template.

1. Pin down the target

• Nutrient keys: macro keys are kcal, protein_g, fat_g, sat_fat_g, carb_g, sugar_g, fiber_g; micros/vitamins by key via nutrient_total (e.g. "sodium_mg", "iron_mg"). nutrient_total returns 0 for an unknown key — if a micro baseline reads 0 for an ingredient list that plainly contains it, suspect the key, not the food.
• Basis: per serving, whole recipe, or per day (for .menu plans). If the recipe declares servings and the user just says "600 kcal", per-serving vs total is genuinely ambiguous — ask. Otherwise don't ask; state your reading.
• Tolerance: default ±5 % (within_tol(value, target, 5)); use the user's figure when given. For "keep X the same", hold X within ±5 % of its current value.
• Already given: targets, restrictions or servings the user stated earlier in the conversation (including in a prompt they ran) count as provided. Do not ask for them again — restate your reading and proceed.

2. Measure the baseline

Read the file with read_recipe (you need its source to edit it), then render it with render_report (input_path = the file). Emit machine-readable lines — the ITEM lines are your lever map (which ingredients dominate which nutrient):

{% set t = macros(ingredients) %}
{% set servings = metadata.servings | default(1) | int %}
TOTAL kcal={{ t.kcal | round(1) }} protein={{ t.protein_g | round(1) }} fat={{ t.fat_g | round(1) }} carb={{ t.carb_g | round(1) }} fiber={{ t.fiber_g | round(1) }}
PER_SERVING ({{ servings }}) kcal={{ (t.kcal / servings) | round(1) }} protein={{ (t.protein_g / servings) | round(1) }}
{% set agg = aggregate_nutrition(ingredients) %}
{% for it in agg.items -%}
ITEM {{ it.ingredient }} | {{ it.amount.value }} {{ it.amount.unit }} | kcal={{ it.macros.kcal | round(1) }} protein={{ it.macros.protein_g | round(1) }} | {{ it.confidence }}
{% endfor -%}
{% for f in agg.failures -%}
FAILED {{ f.ingredient }} — {{ f.error.message }}
{% endfor -%}

FAILED ingredients contribute nothing to the totals — tell the user the numbers exclude them rather than silently trusting the total. Flag estimated confidence items when they dominate a target nutrient.

For .menu plans the template reads plan.days (each day's scaled .ingredients) instead of ingredients; see the "Meal plans" section of nutrition-reports and https://nutrition.cook.md/docs/guides/plan.

3. Choose edits — tiered

Prefer the least invasive tier that can reach the target; move down only when the current tier cannot:

1. Quantities & servings — scale ingredient amounts, or plan servings.
2. Swaps that preserve the dish — yogurt → Greek yogurt, half the oil plus broth, white rice → lentils. lookup_ingredient finds catalog names, check_category keeps a swap in its category (e.g. oily fish), and get_nutrition compares per-amount profiles before you commit.
3. Add/remove ingredients — or recipes in a plan — last.

Keep the dish's character: a few decisive changes beat many tiny ones. Round to practical cooking amounts and keep the recipe's existing unit style. The cooklang://syntax resource covers the edit mechanics for .cook and .menu files.

4. Verify BEFORE saving

Write the full edited file text, then render it with render_report using input (the edited text) and kind ("cook" or "menu") instead of input_path — the same measuring template, so numbers are comparable. Nothing is saved yet. Refine at most ~3 rounds; if the targets stay unreachable within the allowed tiers, stop and present the closest achievable numbers with a plain explanation of the gap (e.g. "without swapping the rice, 40 g protein forces ~750 kcal").

To compare a few alternatives quickly without writing each one out, sum nutrition_for_amount over a candidate list (item shape — macros live under .macros); it raises a template error when an ingredient can't be resolved, so fix the name/unit and re-render:

{% set candidate = [
  {"name": "chicken breast", "amount": 300, "unit": "g"},
  {"name": "olive oil", "amount": 1, "unit": "tbsp"},
  {"name": "basmati rice", "amount": 150, "unit": "g"}
] %}
{% set servings = 2 %}
{% set ns = namespace(kcal=0.0, protein=0.0) %}
{% for c in candidate %}
{% set n = nutrition_for_amount(c.name, c.amount, c.unit) %}
{% set ns.kcal = ns.kcal + n.macros.kcal %}
{% set ns.protein = ns.protein + n.macros.protein_g %}
{% endfor %}
CANDIDATE total kcal={{ ns.kcal | round(1) }} protein={{ ns.protein | round(1) }}
CANDIDATE per-serving kcal={{ (ns.kcal / servings) | round(1) }}
KCAL_OK={{ within_tol(ns.kcal / servings, 600, 5) }}

5. Save the edit

• Run validate on the edited text, then save with write_recipe (.cook) or write_menu (.menu), always the full file content. This overwrites the user's file: if they asked to see options first, or the change is large (tier 3), confirm before saving.
• Tell the user what you changed in one or two lines per ingredient (olive oil 3 tbsp → 1 tbsp), not a full diff, and where you saved it.
• Present current → new vs target (per serving/day and total, from steps 2 and 4) as a small table.

6. Confirm on the saved file

Re-render the saved file with input_path and the same measuring template. If the numbers differ from step 4, say so and fix — the saved file is what the user will cook from.

7. Offer to persist the goals

Offer (don't push) to save the targets as a reusable checks template so future edits can be re-validated (the nutrition-reports flow), at reports/goals.<recipe-slug>.md.jinja (or under config/reports/ if that is where the collection keeps its templates — Cook Editor does), with write_config:

{% import "ck" as ck %}
{% set t = macros(ingredients) %}
{% set servings = metadata.servings | default(1) | int %}
# Goals — {{ metadata.title | default("Recipe") }}

- Energy: {{ (t.kcal / servings) | round }} kcal per serving
- Protein: {{ (t.protein_g / servings) | round(1) }} g per serving

{{ ck.between(t.kcal / servings, 570, 630, "kcal per serving") }}
{{ ck.min(t.protein_g / servings, {"min": 40}, "Protein per serving (g)") }}

{% set checks = all_checks() %}
**{{ checks | selectattr("ok") | list | length }} of {{ checks | length }} checks passed.**

Render it later with template_path: "reports/goals.<recipe-slug>.md.jinja".

(ck.min/ck.max/ck.range take a target object like {"min": 40}; ck.between takes scalar bounds.)

Function cheatsheet (condensed)

Full reference at https://nutrition.cook.md/docs/guides/functions.

Guardrails

• Every number comes from the service. Never estimate nutrition from your own knowledge — not for baselines, not for candidate verification.
• Surface FAILED and low-confidence ingredients; never present totals that silently exclude them. Measure with aggregate_nutrition / macros (both skip unresolved ingredients; aggregate_nutrition lists them under failures), never with nutrition_for(ingredient) in a loop — that aborts on the first miss.
• Non-English recipes: the nutrition database resolves English ingredient names only. When the FAILED list is mostly non-English names, tell the user once — "Nutrition lookups currently understand English ingredient names — <language> isn't supported yet; email support@cook.md if you'd like it added sooner" — and offer to proceed with English equivalents via nutrition_for_amount, clearly marked as translated by you.
• Keep proposed quantities practical (no "137 g chicken"; prefer 140 g).

When the render errors

render_report returns an error result on failure:

• "authentication required": call login, show the user the code and link, retry once they've approved.
• "subscription required": nutrition math needs Cook Basic or Cook Pro — show the pricing link from the error. You may still make a qualitative edit if the user wants, clearly labelled as unverified. Do not keep retrying.
• Template error (minijinja reports the line): fix the template, render again.