# Family meal planner

Plan a household's dinners for four weeks, write the grocery list for each week, and swap meals when plans change. Everything comes from the household's own answers. Ask, never assume: a missed allergy or a food someone avoids for religious reasons is a real failure.

## Where this runs

- **Claude Code.** Installed at `~/.claude/skills/meal-planner/`. The user starts it with `/meal-planner` or by asking in their own words.
- **Codex.** Installed at `~/.codex/skills/meal-planner/`. The user starts it by mentioning `$meal-planner`.
- **Chat assistants** (Claude.ai, ChatGPT, others). The user uploads the skill or pastes the all-in-one file into a chat or project instructions. There are no files to save in a chat, so the profile lives with the user (see Step 1).

Bundled files, relative to this skill's folder:
- `references/interview.md`: the first-run questions, in order, and the profile template.
- `references/plan-format.md`: the layout for the rotation, the grocery list and swaps, with a sample.

If you were given this skill as one combined file, those two sections are included below this one.

## Step 1: Load or build the profile

**Tools with file access (Claude Code, Codex).** Read `~/.config/meal-planner/profile.md`.
- If it exists, give the user a three-line summary (who eats, the hard rules, the shopping setup) and ask "Anything changed since last time?" Then go to the request.
- If it does not exist, run the interview.

**Chat assistants.** Ask once: "Do you have a saved meal-planner profile? If so, paste it here." If they paste one, use it. If not, run the interview.

**The interview.** Follow `references/interview.md`. Ask one question at a time and wait for the answer. Accept "none" or "skip" for any question except household members and allergies. Keep it moving: it should take about five minutes.

When the interview is done, read the profile back and ask the user to confirm or fix it. Then save it:
- File access: write it to `~/.config/meal-planner/profile.md` (create the folder if needed) and tell the user where it is.
- Chat: show the full profile in one block and say: "Save this somewhere (a note or a document). Paste it in next time and I'll skip the questions." Repeat this offer whenever the profile changes.

## Step 2: Read the order history (optional)

If the user shares past grocery orders, use them. They might paste the text of an order page, attach a downloaded file (CSV or PDF), forward receipt emails, or attach photos of paper receipts.

1. Keep food and drink only. Drop household goods, personal care, pet items, fees, tips and coupons.
2. Shorten each item to what it is and its size ("whole milk, 1 gallon", "frozen broccoli florets, 2 lb"). Keep a brand name only if the user cares about it; they can tell you during review.
3. Count how often each item appears. Bought in most orders = **staple**. Bought a few times = **regular**. Bought once = **one-off**; leave these out unless they fit a meal.
4. Check every item against the profile's hard rules. If something breaks a rule, ask before dropping it ("I see peanut butter in three orders. Is that for someone outside the allergy?"). It may be for a guest, a lunchbox at school with different rules, or a mistake in the profile.
5. If prices are listed, note the usual price per item. Use them for the budget estimate.
6. Show the user a short summary (top staples, the proteins they buy most, anything flagged) and add a **Usual items** section to the profile.

## Step 3: Build the four-week dinner rotation

Plan 28 dinners: four weeks of seven. Use the layout in `references/plan-format.md`.

Apply rules in this order. Earlier rules always win.

1. **Hard rules.** Allergies, intolerances, foods avoided for health, and religious rules are never broken. Check every ingredient, including the hidden ones: broths, sauces, dressings, seasoning blends, breads, and frying oil. Peanut, tree nut, sesame, shellfish, fish, egg, milk, soy and wheat show up in many ready-made products. When a ready-made item often contains an allergen, say "check the label" next to it.
2. **Cooking time.** Weeknight dinners fit the time the user gave, from start to table. Longer meals go on the nights they named as free. Count oven preheat and marinating.
3. **Budget.** Keep each week's grocery estimate near the budget. Lean on cheaper proteins, beans, eggs, and dishes that stretch, and plan leftovers.
4. **What they like.** Leave out dislikes. Build around the usual items from order history first, then add new meals at the rate the user asked for.
5. **Variety.** No dinner repeats within the four weeks unless the user asked for a fixed night (pizza Friday, tacos Tuesday). The same main protein never runs three nights in a row. Each week mixes cooking styles: sheet pan, one pot, skillet, slow cooker, no-cook.
6. **Less waste.** Plan for a perishable bought for one meal to be used again that week (half a bunch of cilantro, the rest of the spinach). Plan one or two leftover nights or leftover lunches each week.
7. **Kids.** If there are young children, note an easy way to serve a plainer version (sauce on the side, plain noodles set aside).

For each dinner give the name, the main parts, the active and total time, and a short note (leftovers, prep ahead, kid version). Give recipes only when asked; one line of method is enough for familiar dishes.

**Lunches (optional).** If the user wants lunches, plan them per week. Lean on leftovers and a few repeatable options rather than seven new recipes, and note which days need a packed lunch.

## Step 4: Write the grocery list

Write one list per week, grouped by store section in the order in `references/plan-format.md`.

- Scale amounts to the household, using the portion guide in `references/plan-format.md` and the units in the profile.
- Combine the same item across meals into one line, with the meals it is for.
- Mark items from order history as "usual".
- Put items most homes already keep (oil, salt, common spices, rice) under **Check the pantry**, so the user can tick off what they have.
- If the profile lists a standing weekly order (milk, bread, fruit for lunches), add it to every week.
- Give a budget estimate. Use the order-history prices when you have them. Otherwise give a rough range and say it is rough: you do not know local prices.
- If the user orders online, keep item names plain and searchable ("boneless skinless chicken thighs, about 2 lb"), so they can type them into the store's search.

## Step 5: Swaps

The user may say an item is out of stock, someone won't eat a meal, a night changed, or they want to use up something in the fridge.

- **Out of stock.** Offer the closest replacement that follows every hard rule and uses the same cooking method, and say whether the time changes.
- **Disliked meal.** Offer two or three replacements of the same effort that reuse ingredients already on that week's list. Add the meal to the profile's dislikes if the user agrees.
- **Night changed.** Move the meals around before replacing any; a slow-cooker meal may suit a busy night better.
- **Use it up.** Build a meal around what they have, then remove what it replaces from the list.

After any swap, show the updated week and the changes to the grocery list (added, removed).

Common swaps are in `references/plan-format.md`. Check each against the profile before offering it.

## Saving and later runs

- **File access.** Save each rotation to the plans folder named in the profile (default `~/Documents/meal-plans/`) as `meal-plan-YYYY-MM-DD.md`, dated the first day of Week 1. Run `date` to get today's date; never guess it. Edit the same file for swaps and tell the user what changed.
- **Chat.** Show the full plan in one block so the user can copy it, and remind them that a pasted plan plus profile lets them pick up where they left off.

Requests on later runs, and what to do:
- "Next week's list": find the current week in the rotation from the start date and write that week's list.
- "Start a new rotation": keep the meals the user rated well, replace the rest.
- "We had this and loved it / hated it": record it in the profile under favorites or dislikes.
- "Update our profile": ask what changed, edit only that part, and read it back.
- "Here's a new order": update the usual items (Step 2).

## Limits

- This skill plans meals. It does not give medical or nutrition treatment advice. If a member has a diet set by a doctor or dietitian (kidney disease, diabetes, a feeding plan), follow the rules the user gives and tell them to check the plan with that clinician.
- Allergies: always tell the user to read labels, because recipes and products change.
- Do not count calories or set weight goals unless the user asks for it.
- Do not invent store prices, store aisles, or product names as fact. Say when something is an estimate.

---

The files named above are included below. Treat each one as the file it is named after.

---

<!-- references/interview.md -->

# First-run interview

Ask one question at a time, in this order. Wait for each answer before asking the next. Use the user's words in the profile. If an answer is vague on a hard rule ("we're kind of off dairy"), ask one follow-up to pin it down: is it an allergy, an intolerance, a health reason, or a preference? That decides how strictly you follow it.

Questions 1 and 2 are required. The rest accept "none" or "skip".

## Questions

1. **Who eats at home?** "Who are you feeding? Give me each person's age, or just 'adult', 'teen' or 'child'. Include anyone who eats with you most nights."
   Record each member on its own line. Use a role or first initial, not a full name, unless the user offers names.

2. **Allergies and intolerances.** "Does anyone have a food allergy or intolerance? Tell me how serious it is, for example a mild stomach upset versus a reaction that needs an epinephrine pen."
   For a serious allergy, ask: "Should I keep it out of every meal for everyone, or only out of that person's plate?" Default to everyone.

3. **Foods avoided for health.** "Is anyone avoiding foods for a health reason, such as low salt, low sugar, gluten-free, or a diet a doctor set?"

4. **Religion, culture, or choice.** "Are there foods your household doesn't eat for religious, cultural or personal reasons? For example no pork, halal or kosher, vegetarian, no meat on certain days, or fasting periods."
   Ask whether it applies to everyone or to one person, and whether it changes during the year.

5. **Dislikes.** "Which foods does anyone refuse or dislike? Kids' dislikes count."
   Separate "won't eat at all" from "only if hidden in something".

6. **Favorites.** "What meals does everyone already like? Name a few you'd happily see every month."

7. **Cooking time.** "On a weeknight, how long do you have from starting to cook to eating? Which nights, if any, have more time?"
   Also ask: "Do you have a slow cooker, pressure cooker or air fryer?"

8. **Budget.** "Roughly how much do you want to spend on groceries each week? Skip this if you'd rather not set a number."

9. **Shopping.** "Where and how do you shop? For example one big trip on the weekend, pickup or delivery orders, a warehouse club once a month, or a market for produce."
   Follow up: "Do you buy anything the same every week, like milk, bread or fruit for lunches?" Record this as the standing weekly order.
   If it is not clear from where they live, ask: "Pounds and ounces, or grams and kilograms?"

10. **Lunches.** "Do you want me to plan lunches too, or dinners only? If lunches, who needs a packed lunch and on which days?"

11. **New meals.** "How adventurous should the plan be? Mostly familiar meals, a new one each week, or lots of new ones?"

12. **Order history (optional).** "If you'd like, share some past grocery orders and I'll build meals around what you already buy. You can paste the text from your store's order page, attach a downloaded file, forward receipt emails, or send photos of receipts. Two to six orders is enough."
    If they share orders, follow Step 2 in SKILL.md.

Tools with file access only: 13. **Where to save plans.** "I'll save your plans as files. Is a `meal-plans` folder in your Documents folder OK, or would you like somewhere else?"

## Profile template

Save the confirmed answers in this shape. Leave a section as "none" rather than deleting it, so later runs know the question was asked.

```markdown
# Meal planner profile
Updated: YYYY-MM-DD

## Household
- Adult
- Adult
- Child, 8

## Hard rules (never break)
- Allergy: [food], [who], [how serious], [kept out for everyone / only their plate]
- Intolerance: [food], [who]
- Health: [rule], [who]
- Religion or culture: [rule], [who], [when it applies]

## Preferences
- Dislikes (won't eat): ...
- Dislikes (OK if hidden): ...
- Favorites: ...
- New meals: [mostly familiar / one a week / lots]

## Cooking
- Weeknight time: [minutes], start to table
- Nights with more time: ...
- Equipment: ...

## Shopping
- Weekly budget: [amount or none]
- How they shop: ...
- Standing weekly order: ...
- Units: [lb/oz or g/kg]

## Meals to plan
- Dinners: yes
- Lunches: [no / who and which days]

## Usual items (from order history)
- Staples: ...
- Regulars: ...
- Usual prices: [item, price] (only if the orders showed prices)

## Files (tools with file access only)
- Plans folder: ~/Documents/meal-plans/
- Current rotation: [file name], Week 1 starts YYYY-MM-DD
```

---

<!-- references/plan-format.md -->

# Plan format

Use this layout for every rotation file or chat reply. Keep it plain Markdown so it reads well in a note app, a document, or a chat.

## File layout

```markdown
# Meal plan: 4-week rotation
Week 1 starts YYYY-MM-DD. Profile updated YYYY-MM-DD.

Household: [one line: who eats]
Hard rules: [one line: every allergy, intolerance, health and religious rule]
Weeknights: [time limit]. Longer nights: [days].

## This week
(only when the user says what they already have at home or in the cart)

## Week 1
[dinner table]
[lunch table, if lunches are planned]
[grocery list]

## Week 2
...

## Week 3
...

## Week 4
...

## Standing weekly order
[items bought every week, if any]

## Swaps
[swaps made so far, newest first]
```

## Dinner table

| Day | Dinner | Time (active / total) | Notes |
|---|---|---|---|
| Mon | Dish name: main parts | 15 / 40 min | leftovers, prep ahead, kid version, "check the label" |

Start the week on the day the user shops or the day they name. Mark fixed nights ("Pizza night") and leftover nights in the Dinner column.

## Lunch table (optional)

| Day | Who | Lunch | From |
|---|---|---|---|
| Mon | Child, packed | Turkey and cheese wrap, apple | this week's list |
| Tue | Adults | Leftover chili | Mon dinner |

## Grocery list

Group by store section in this order. Leave out empty sections.

1. Produce
2. Meat and seafood
3. Dairy and eggs
4. Bakery and bread
5. Deli
6. Grains, pasta and beans
7. Canned and jarred
8. Sauces, oils and spices
9. Frozen
10. Snacks and drinks
11. Check the pantry (items most homes keep; the user ticks off what they have)

Each line: item, amount, the meals it is for, and "usual" if it came from order history.

`- Boneless skinless chicken thighs, 2 lb (Mon, Thu) usual`

End each week's list with: `Estimate: [amount or range] ([from your past order prices / rough, local prices vary])`.

## This week view

When the user says what they already have (in the fridge, or already in an online cart):

| Day | Dinner | Already have | Still need |
|---|---|---|---|
| Mon | Sheet-pan chicken and potatoes | potatoes, green beans | chicken thighs 2 lb |

Then list only the items still needed, grouped by section.

## Portion guide

Per person, per dinner. Scale up for planned leftovers (one adult portion per leftover lunch).

| | Adult or teen | Child 4 to 10 | Child under 4 |
|---|---|---|---|
| Boneless meat, poultry or fish (raw) | 5 to 6 oz (150 to 170 g) | about half | about a quarter |
| Bone-in meat (raw) | 8 to 10 oz (225 to 280 g) | about half | about a quarter |
| Dry pasta | 3 to 4 oz (85 to 115 g) | about half | about a quarter |
| Dry rice or grains | 1/3 to 1/2 cup (60 to 90 g) | about half | about a quarter |
| Vegetables | 1 cup | 1/2 cup | 1/4 cup |

Teens with big appetites may eat more than an adult portion. Ask if unsure.

## Common swaps

Check every swap against the profile before offering it. A swap that fixes one rule can break another.

| Instead of | Try | Note |
|---|---|---|
| Chicken thighs | Chicken breast, turkey cutlets | Breast cooks faster and dries out sooner |
| Ground beef | Ground turkey, ground chicken, lentils | Add a little oil to lean ground poultry |
| Fresh spinach | Frozen spinach | Squeeze out the water first |
| Fresh herbs | Dried herbs | Use about a third as much |
| Heavy cream | Evaporated milk; full-fat coconut milk if dairy-free | Coconut changes the flavor |
| Peanut sauce | Sunflower seed butter sauce | Only if no seed allergy; check the label |
| Soy sauce | Tamari labeled gluten-free | For wheat or gluten rules |
| Breadcrumbs | Crushed crackers, rolled oats | Check gluten rules for both |
| Wheat pasta | Gluten-free pasta, rice noodles | Cooks faster; watch it |
| Store-bought broth | Low-sodium broth, or water plus spices | For low-salt rules |

## Sample: made-up household

This sample is for the verify run and for showing the format. It is not a default.

```markdown
# Meal plan: 4-week rotation
Week 1 starts 2026-01-05. Profile updated 2026-01-03.

Household: 2 adults, teen (13), child (8)
Hard rules: peanut allergy, serious (child); kept out of every meal for everyone. Low salt (one adult).
Weeknights: 30 minutes. Longer nights: Sunday. Slow cooker: yes.

## Week 1

| Day | Dinner | Time (active / total) | Notes |
|---|---|---|---|
| Mon | Skillet chicken thighs, rice and green beans | 20 / 30 min | Cook all 4 lb: extra is for Tue lunch and Thu |
| Tue | Beef and black bean tacos, corn, salsa | 25 / 25 min | Low-sodium taco seasoning or own spice mix |
| Wed | Pasta with turkey meat sauce, side salad | 20 / 30 min | Double the sauce; freeze half for Week 3 |
| Thu | Egg fried rice with peas, carrots and leftover chicken | 20 / 20 min | Cook rice Wed night; no peanut oil; reduced-sodium soy sauce |
| Fri | Pizza night: homemade flatbread pizzas | 15 / 25 min | Kids top their own |
| Sat | Leftover night | 10 / 10 min | |
| Sun | Slow-cooker pork carnitas bowls, rice, beans, slaw | 20 min / 8 h | Leftovers for Mon lunch |

### Grocery list

Produce
- Green beans, 1.5 lb (Mon)
- Romaine, 1 head (Wed)
- Cabbage slaw mix, 1 bag (Sun)
- Limes, 3 (Tue, Sun)
- Onion, 2 (Tue, Sun)

Meat and seafood
- Boneless skinless chicken thighs, 4 lb (Mon, Thu, Tue lunch) usual
- Ground beef, 1.5 lb (Tue) usual
- Ground turkey, 2 lb (Wed, Week 3)
- Pork shoulder, 3 lb (Sun)

Dairy and eggs
- Eggs, 1 dozen (Thu) usual
- Shredded mozzarella, 8 oz (Fri)
- Shredded cheddar, 8 oz (Tue)

Bakery and bread
- Corn tortillas, 1 pack (Tue)
- Flatbreads, 4 (Fri)

Grains, pasta and beans
- Penne, 1 lb (Wed)
- Black beans, 2 cans (Tue, Sun)

Canned and jarred
- Crushed tomatoes, 2 large cans (Wed)
- Salsa, 1 jar (Tue, Sun) check the label
- Pizza sauce, 1 jar (Fri) check the label

Sauces, oils and spices
- Reduced-sodium soy sauce (Thu) check the label

Frozen
- Peas and carrots, 1 bag (Thu)
- Corn, 1 bag (Tue)

Check the pantry
- Rice, olive oil, cumin, chili powder, garlic powder, oregano

Estimate: rough range, local prices vary.
```

Weeks 2 to 4 follow the same layout.
