---

name: yerevan-city description: Order groceries from yerevan-city.am — search products, manage delivery addresses, build a cart. Use when the user asks to order groceries, buy food in Yerevan, add products to their yerevan-city cart, or mentions yerevan-city.am / City Supermarket. allowed-tools: [Bash, Read]

Yerevan City Grocery Skill

Build a grocery cart on yerevan-city.am from conversation.

Safe by design: never places an order or pays — only builds the cart. Checkout and payment always stay with the user, in their own browser or app.

When to Use

• "Order milk and bread" / "добавь молоко в корзину"
• "What's in my yerevan-city cart?"
• "Find tomatoes on yerevan-city"
• Any grocery shopping request for Yerevan City / City Supermarket

Setup

All commands run through one script (Python 3 stdlib only, no install needed):

SCRIPT="$CLAUDE_PROJECT_DIR/scripts/yerevan_city.py"   # or path where this skill is installed
python3 "$SCRIPT" --help

If the skill is installed under ~/.claude/skills/yerevan-city/, use python3 ~/.claude/skills/yerevan-city/scripts/yerevan_city.py.

Login Flow (one-time)

Session persists in ~/.yerevan-city-skill/session.json; an existing yerevan-city-mcp session is reused automatically. Only log in when a command fails with "No active yerevan-city.am session".

1. Ask the user for their Armenian phone number.
2. python3 "$SCRIPT" login-request --phone +37441234567
3. Ask the user for the SMS code they received.
4. python3 "$SCRIPT" login-confirm --phone +37441234567 --code 1234

Never guess the code. Never trigger login-request repeatedly — each call sends a real SMS.

Commands

python3 "$SCRIPT" search --query "milk" [--page 1]        # free-text catalogue search
python3 "$SCRIPT" account                                  # profile: name, bonus card, default address
python3 "$SCRIPT" addresses                                # saved delivery addresses
python3 "$SCRIPT" address-add --city Yerevan --street Tumanyan --building 1 \
    --apartment 1 --floor 1 --lat 40.1811 --lng 44.5136    # create address (become session default)
python3 "$SCRIPT" address-update --id 45 ...               # same flags as address-add, plus --id
python3 "$SCRIPT" add --product-id 123 --count 2 --address-id 45     # piece-counted product
python3 "$SCRIPT" add --product-id 456 --grams 500 --address-id 45   # weight-based product
python3 "$SCRIPT" remove --product-id 123 --address-id 45
python3 "$SCRIPT" cart --address-id 45
python3 "$SCRIPT" logout

Rules to Follow

1. Address first. The cart is scoped to a delivery address. Login stores the account's default address in the session automatically; run addresses to check. If the list is empty, ask the user for their address (city, street, building, apartment, floor) and create it with address-add — geocode lat/lng first (e.g. Nominatim: https://nominatim.openstreetmap.org/search?q=<street>+<building>,+Yerevan&format=json). Pass the address id as --address-id to add/remove/cart calls (or rely on the session default).
2. Count vs grams. Products with isKilogram: false are added with --count (pieces). Products with isKilogram: true are added with --grams; respect minimumWeight and weightStep from search results (both in grams) — fresh meat is typically 1000g minimum, loose produce 300–800g. If the user asks for less than the minimum, tell them the forced minimum and get their OK before adding.
3. Check isMissing after every add. The API accepts adds for out-of-stock products and only reports it via isMissing on the returned addedItem. If isMissing is true, the product will NOT be delivered: immediately remove it, tell the user it's unavailable (mention availableCount/availableWeight if partial stock exists), and suggest an alternative from search results if there's an obvious one. Never leave an out-of-stock item in the cart silently.
4. Always report totals. After adding items or showing the cart, state totalPrice and deliveryFee together as the full amount to pay (prices are in Armenian drams, AMD).
5. Before declaring the cart ready, run cart and clean up any item with isMissing: true via remove.
6. Never place an order. The script cannot check out, and you must not try to via the website. Tell the user to finish checkout in their own browser or app.

Example Session

User: order 2 bottles of milk and half a kilo of cheese

1. python3 "$SCRIPT" addresses                 → default address id 45
2. python3 "$SCRIPT" search --query "milk"     → pick product, isKilogram false
3. python3 "$SCRIPT" add --product-id 111 --count 2 --address-id 45
   → check addedItem.isMissing, note totalPrice
4. python3 "$SCRIPT" search --query "cheese"   → pick product, isKilogram true
5. python3 "$SCRIPT" add --product-id 222 --grams 500 --address-id 45
6. python3 "$SCRIPT" cart --address-id 45      → verify, report total + delivery fee

Notes

• Product names come in three languages (nameEn, nameRu, nameArm) — match against whichever language the user used. English queries sometimes miss items that Russian ones find (e.g. "стейк", "чеснок", "вырезка") — retry in another language before concluding a product doesn't exist.
• The shop API misspells two address fields: buliding and appartment. The script's --building/--apartment flags map to them — don't "fix" the spelling in the API payloads.
• The user's bonus card lives on the account profile (account command, bonusCardNumber) and applies at checkout automatically — no cart action needed.
• Unofficial, educational project; not affiliated with Yerevan City / City Supermarket. Non-commercial license — see LICENSE.