Skill: Nutrition Reports

Needs the Cook MCP server (tools like render_report and read_recipe). 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 a nutrition or dietitian-style evaluation of a recipe or meal plan — calories/macros/micronutrients, passed/failed checks against targets, exclusions or allergens, or aggregating nutrition across a .menu plan. Backed by the Cook nutrition service, called through the render_report tool.

This skill is for nutrition specifically. For plain counts, costs (db() datastore) and custom printouts, follow the report-authoring skill; its aisled() / excluding_pantry() / db() functions work inside nutrition templates too.

Access

Nutrition data needs a cook.md login and a Cook Basic or Cook Pro plan. If a render fails with "authentication required", call login and show the user the code and link, then retry. If it fails with "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. auth_status tells you whether the user is logged in and on which plan.

How rendering works

Nutrition reports are Jinja2 templates rendered with render_report (it never edits files). The template calls nutrition functions (below); the service resolves each ingredient. render_report returns { rendered, checks, resolve_failures }: checks are the passed/failed checks the template recorded, resolve_failures the ingredients the service couldn't resolve, each with an error code, message and suggestions.

• Reuse first: saved templates live in reports/ (CookCLI) or config/reports/ (Cook Editor); list_recipes kind: "template" lists both. If one answers the question, check its inline targets/exclusions match the user's, then render it with template_path. If the targets differ, author inline (or offer to update the saved template).
• Otherwise draft inline (template) and iterate: read rendered, fix errors, repeat.
• input_path is the .cook/.menu file as list_recipes returned it (e.g. "plans/Week of May 18.menu"). scale defaults to 1 and scales .cook recipes only.
• Targets and exclusions: define them inline in the template, or point client_profile_path at a profile YAML in the collection. The profile is then available to the template as client:

name: Sara
exclusions: [peanut, shellfish]
targets:
  energy_kcal: { min: 1800, max: 2200 }
  protein_g: { min: 75 }
  sat_fat_g: { max: 20, tol_pct: 10 }

Fixing resolve failures

• ingredient_not_found → try lookup_ingredient with the name and retry with a suggestion, or fix the ingredient name in the recipe. Do not bake qualifiers into names — fresh garlic should be @garlic{}(fresh).
• density_unavailable / unit errors → probe with convert_units; prefer mass units in the recipe when density is missing.
• Fixing the recipe itself is an edit: follow the cooklang-editing skill, and ask first.

Screening a shortlist

"Which of my recipes are over 35% protein?", "find three quick dinners with X" — you are filtering existing files, not evaluating one. render_report takes ONE recipe per call, so a careless screen costs one render per candidate and turns a three-dinner question into a hundred tool calls. Work in three passes:

1. Narrow before you measure. search_recipes (with tag where it helps), folder names, and the pantry tools cut the field on the cheap criteria first — course, time, ingredients on hand, cuisine. Nutrition is the last filter applied, never the first.
2. Cap the candidates at about six, chosen from that shortlist. If six is not enough, say so and screen a second batch — do not pre-emptively measure twenty files.
3. Render, do not read. A render already resolves the recipe's ingredients and macros; reading a file you are about to render buys nothing. Read a recipe only when you need its prose — method, equipment, wording you will quote. Send the same small template for each candidate (in parallel if your client allows).

Emit one machine-readable line per candidate (NAME | kcal | protein_g | pct_protein | OK/FAILED) so each output is a single line. Present the survivors, then hand off — meal-planning to build a .menu from them, nutrition-goals only if a chosen recipe has to be changed to clear the bar.

Presenting results

The rendered report is the answer: show it to the user as it came back, then add at most three lines — the verdict, blockers (FAILED or low-confidence ingredients), the next step. Do not retype or recompute its numbers. For .menu plans the per-day table (each day vs. its targets) lives in the report; the summary names the days that miss which targets. When the user supplied targets earlier in the conversation, use them — do not ask again; with no user targets, frame against daily values (dv_percent) rather than inventing thresholds. A single-number question may be answered in one line from the render. If the user wants the recipe or plan changed to hit the targets, follow nutrition-goals.

Incomplete coverage — never fail the report

The nutrition database does not resolve every ingredient (regional names, brands, unusual units). A report must still render for the ingredients it can resolve, skip the rest, and list them at the end:

• Build per-ingredient tables and totals from aggregate_nutrition(ingredients). Its items are the resolved ingredients (.ingredient, .amount.value / .amount.unit, .macros.kcal|protein_g|fat_g|carb_g|fiber_g|sat_fat_g|sugar_g, .confidence) and its failures the unresolved ones (.ingredient, .error.message, .error.suggestions). totals — and the macros() / total_calories() shortcuts — already exclude failures; totals.is_partial, totals.included_count and totals.failed_count tell you whether they are complete.
• Do not call nutrition_for(ingredient) in a loop over ingredients: it raises a template error on the first unresolved ingredient or non-numeric quantity ("some", "1–2") and aborts the whole render. Iterate agg.items.
• Do not add your own "coverage must be 100 %" checks or {% raise %}-style guards; partial data is reported, not refused.
• End every nutrition report with a "Not included" section listing each failure and its reason, and say in your summary how many ingredients were skipped. Never present partial totals as complete.

{% set agg = aggregate_nutrition(ingredients) %}
{% set servings = metadata.servings | default(1) | int %}
# Nutrition — {{ metadata.title | default("Recipe") }}

| Ingredient | Amount | kcal | Protein | Carbs | Fat |
|---|---|---|---|---|---|
{% for it in agg.items -%}
| {{ it.ingredient }} | {{ it.amount.value }} {{ it.amount.unit }} | {{ it.macros.kcal | round }} | {{ it.macros.protein_g | round(1) }} g | {{ it.macros.carb_g | round(1) }} g | {{ it.macros.fat_g | round(1) }} g |
{% endfor %}
**Per serving ({{ servings }}):** {{ (agg.totals.macros.kcal / servings) | round }} kcal ·
{{ (agg.totals.macros.protein_g / servings) | round(1) }} g protein ·
{{ (agg.totals.macros.carb_g / servings) | round(1) }} g carbs ·
{{ (agg.totals.macros.fat_g / servings) | round(1) }} g fat
{% if agg.totals.is_partial %}
*Totals cover {{ agg.totals.included_count }} of {{ agg.totals.included_count + agg.totals.failed_count }} ingredients.*

### Not included ({{ agg.failures | length }})
{% for f in agg.failures -%}
- {{ f.ingredient }} — {{ f.error.message }}{% if f.error.suggestions %} (try: {{ f.error.suggestions | join(", ") }}){% endif %}
{% endfor %}
{% endif %}

Meal plans (.menu)

A .menu is read through plan, not ingredients: plan.days (each with .name, .date, .meals and the day's scaled .ingredients), plan.all_ingredients, plan.servings (people eating, from the menu's frontmatter) and plan.missing_recipes (references that didn't resolve — report them). Per-day totals:

{% set people = plan.servings | default(1) %}
| Day | kcal / person | Protein / person |
|---|---|---|
{% for day in plan.days -%}
{% set t = aggregate_nutrition(day.ingredients).totals.macros %}
| {{ day.name or day.date }} | {{ (t.kcal / people) | round }} | {{ (t.protein_g / people) | round(1) }} g |
{% endfor %}

Non-English recipes

The nutrition database currently resolves English ingredient names; other languages are not translated yet. When the failures are mostly non-English names (e.g. Dutch havermout, volkorenbrood), still render the report as above and tell the user in your summary, once:

Nutrition lookups currently understand English ingredient names — <language> isn't supported yet, so those ingredients are listed under "Not included". If you'd like your language added sooner, email support@cook.md.

You may offer to re-run with English equivalents (nutrition_for_amount("rolled oats", 40, "g")) for the skipped rows, clearly marked as translated by you — it errors too if the English name is unknown, so drop that row rather than retry.

Function cheatsheet

Nutrition functions (full reference at https://nutrition.cook.md/docs/guides/functions):

Check macros — {% import "ck" as ck %}, then each macro records a check and renders a line:

ck.min/max/range/within take a target object ({min, max, tol_pct}); ck.between takes scalar bounds. Recorded checks also come back in render_report's checks. category_servings and plan-wide aggregation are covered at https://nutrition.cook.md/docs/guides/plan; provenance/estimate quality at https://nutrition.cook.md/docs/guides/confidence.

For a quick single-ingredient question ("how much protein in 200 g tofu?") you do not need a template: get_nutrition answers it directly, and aggregate_nutrition the tool sums a hand-made list.

Worked template (inline targets)

{% import "ck" as ck %}
{# Targets inline; or set client_profile_path and use client.targets. #}
{% set targets = {
  "energy_kcal": {"min": 1800, "max": 2200},
  "protein_g":   {"min": 75},
  "sat_fat_g":   {"max": 20},
  "fiber_g":     {"min": 25}
} %}
{% set exclusions = ["peanut", "shellfish"] %}

# Nutrition check — {{ metadata.title | default("Recipe") }}

{% set t = macros(ingredients) %}
- Energy: {{ t.kcal | round }} kcal
- Protein: {{ t.protein_g | round }} g
- Saturated fat: {{ t.sat_fat_g | round(1) }} g
- Fiber: {{ t.fiber_g | round(1) }} g

## Checks
{{ ck.range(t.kcal, targets.energy_kcal, "Daily kcal") }}
{{ ck.min(t.protein_g, targets.protein_g, "Protein (g)") }}
{{ ck.max(t.sat_fat_g, targets.sat_fat_g, "Saturated fat (g)") }}
{{ ck.min(t.fiber_g, targets.fiber_g, "Fiber (g)") }}
{% for ex in exclusions %}{{ ck.absent(ex) }}
{% endfor %}

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

Showing % daily value

When the user wants nutrients framed against a daily target, use dv_percent (or reference_intake for the raw figure) instead of inventing reference numbers. The standard defaults to "fda"; use "eu"/"uk" for European labels. A nutrient with no published DV returns undefined — pre-assign the result and guard with is defined so the row is skipped (piping undefined through | round raises a template error):

{% set t = macros(ingredients) %}
{% set sodium = nutrient_total(ingredients, "sodium_mg") %}
{% set sodium_dv = dv_percent("sodium_mg", sodium) %}
{% set fiber_dv = dv_percent("fiber_g", t.fiber_g) %}
{% if sodium_dv is defined %}
- Sodium: {{ sodium | round }} mg ({{ sodium_dv | round }}% DV)
{% endif %}
{% if fiber_dv is defined %}
- Fiber: {{ t.fiber_g | round(1) }} g ({{ fiber_dv | round }}% DV)
{% endif %}

Workflow: reuse a saved template by template_path if one fits → else draft inline → render_report → read rendered / resolve_failures / fix errors → repeat → show the report once → ≤3-line summary.

When the render errors

render_report returns an error result on failure. Read it:

• "authentication required": call login, show the user the code and link, retry once they've approved.
• "subscription required": nutrition data needs Cook Basic or Cook Pro — show the user the pricing link from the error. Do not keep retrying.
• Template error (minijinja reports the line): fix the template and render again.

Saving a reusable template

When the user wants to keep the report, save it as a .jinja file:

• Save it where the collection already keeps templates (reports/ for CookCLI, config/reports/ for Cook Editor); default reports/.
• Encode the output format in the inner extension: nutrition.md.jinja → markdown.
• Save it with write_config (path e.g. reports/nutrition.md.jinja) and tell the user where.
• From then on, render it with template_path rather than re-sending the source.

Render inline for one-off questions; offer once to save a template, and save only if the user accepts.