Improve/skill review optimization

experiments/src/skills/alfworld/alfworld-appliance-navigator/SKILL.md

@@ -1,17 +1,32 @@
 ---
 name: alfworld-appliance-navigator
-description: This skill navigates the agent to a target appliance (like a microwave, stove, or fridge) needed for a task. It should be triggered when the agent has an object that requires processing (heating, cooling, cleaning) and needs to move to the appropriate station. The skill identifies the appliance from the environment and executes the movement action.
+description: Navigates the agent to a target appliance (microwave, stove, fridge, or sinkbasin) needed for object processing. Use when you are holding an object that needs heating, cooling, or cleaning and must move to the correct appliance station. Identifies the required appliance from the task context and executes the movement action.
 ---
 # Instructions
 Use this skill when you are holding an object that needs to be processed (heated, cooled, or cleaned) and you must locate and move to the correct appliance to perform the action.
 
-## Process
-1.  **Identify the Target Appliance:** Determine which appliance is required for the task (e.g., microwave for heating, fridge for cooling, sink for cleaning). The required appliance is implied by the action needed (`heat`, `cool`, `clean`).
-2.  **Locate the Appliance:** Scan the provided environment observation for the target appliance (e.g., `microwave 1`, `fridge 1`, `sinkbasin 1`).
-3.  **Navigate:** Execute the `go to {appliance}` action to move to the identified appliance location.
-4.  **Prepare Appliance (if needed):** Upon arrival, check if the appliance requires preparation (e.g., opening a closed microwave or fridge door). If so, perform the necessary action (`open {appliance}`) before proceeding with the object processing.
+## Workflow
+1. **Identify the Target Appliance:** Determine which appliance is required for the task. Map the action to the appliance: `heat` -> microwave/stoveburner, `cool` -> fridge, `clean` -> sinkbasin.
+2. **Locate the Appliance:** Scan the environment observation for the target appliance (e.g., `microwave 1`, `fridge 1`, `sinkbasin 1`).
+3. **Navigate:** Execute `go to {appliance}` to move to the identified appliance location.
+4. **Prepare Appliance (if needed):** Upon arrival, check if the appliance requires preparation (e.g., opening a closed microwave or fridge door). If so, perform `open {appliance}` before proceeding.
+
+## Example
+
+**Scenario:** You are holding `potato 1` and need to heat it.
+
+```
+Thought: I need to heat this potato. The microwave is the appropriate appliance.
+Action: go to microwave 1
+Observation: The microwave 1 is closed.
+Thought: I need to open the microwave before I can use it.
+Action: open microwave 1
+Observation: You open the microwave 1. The microwave 1 is open. In it, you see nothing.
+```
+
+**Result:** You are now at the open microwave, ready to heat the potato.
 
 ## Key Principles
-*   **Trigger:** The agent is holding an object and the next step in the task is to `heat`, `cool`, or `clean` it.
-*   **Core Action:** The primary output of this skill is the navigation command `go to {target_appliance}`.
-*   **Prerequisite Check:** Always ensure the appliance is accessible (e.g., open) before attempting to use it for processing.
+- **Trigger:** The agent is holding an object and the next step in the task is to `heat`, `cool`, or `clean` it.
+- **Core Action:** The primary output of this skill is the navigation command `go to {target_appliance}`.
+- **Prerequisite Check:** Always ensure the appliance is accessible (e.g., open) before attempting to use it for processing.

experiments/src/skills/alfworld/alfworld-appliance-preparer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alfworld-appliance-preparer
-description: This skill prepares an appliance (like a microwave, oven, or toaster) for use by ensuring it is in the correct open/closed state. Trigger this when the agent needs to use an appliance for heating, cooling, or cooking and must first open or close it. It takes an appliance identifier as input and outputs a confirmation that the appliance is ready.
+description: Prepares a household appliance (microwave, oven, toaster, fridge) for use by ensuring it is in the correct open/closed state. Use when the agent needs to heat, cool, or cook an item and must first open or close the appliance before placing an object inside. Takes an appliance identifier as input and outputs a confirmation that the appliance is ready for the next action.
 ---
 # Instructions
 
@@ -22,5 +22,15 @@ Prepare a specified household appliance for immediate use by ensuring it is in t
 - **Error Handling**: If the action fails (environment outputs "Nothing happened"), the appliance may already be in the desired state. Re-check the observation and proceed.
 - **Trajectory Insight**: Refer to the example in `references/trajectory_example.md` to see a practical application of this skill in the context of a larger task.
 
+## Example
+
+**Input:** `appliance_identifier: microwave 1`
+
+**Sequence:**
+1. `go to microwave 1` → Observation: "You are at microwave 1. The microwave 1 is closed."
+2. `open microwave 1` → Observation: "You open the microwave 1. The microwave 1 is open."
+
+**Output:** "The microwave 1 is open and ready for use."
+
 ## Output
 A confirmation that the appliance is ready, typically in the form of the agent's `Thought` summarizing the prepared state and the environment's observation.

experiments/src/skills/alfworld/alfworld-clean-object/SKILL.md

@@ -1,28 +1,36 @@
 ---
 name: alfworld-clean-object
-description: This skill cleans a specified object using an appropriate cleaning receptacle (e.g., sink). It should be triggered when a task requires an object to be in a clean state (e.g., 'clean potato') before proceeding. The skill involves navigating to the cleaning location and performing the clean action, outputting confirmation that the object is now clean.
+description: Cleans a specified object using an appropriate cleaning receptacle (e.g., sinkbasin). Use when a task requires an object to be in a clean state (e.g., "clean potato", "wash apple") before proceeding. Navigates to the cleaning location, performs the clean action, and confirms the object is now clean.
 ---
 # Instructions
 
-## When to Use
-Use this skill when your task requires an object to be in a "clean" state before proceeding (e.g., "clean potato", "wash apple"). The skill is specifically designed for the ALFWorld environment.
+Clean an object you are holding using a sinkbasin. The object must be in your inventory before cleaning.
 
-## Prerequisites
-1. You must already possess the target object in your inventory.
-2. You must have identified an appropriate cleaning receptacle (typically a sinkbasin).
-
-## Core Procedure
-1. **Navigate to Cleaning Location**: Go to the identified cleaning receptacle (e.g., `sinkbasin 1`).
-2. **Execute Clean Action**: Perform the `clean` action using the format: `clean {object_name} with {receptacle_name}`.
-3. **Confirm Success**: Verify the environment's observation confirms the object has been cleaned.
+## Workflow
+1. **Navigate:** `go to sinkbasin 1` (or the appropriate sinkbasin in the environment)
+2. **Clean:** `clean {object} with sinkbasin 1` -- verify observation confirms "You clean the {object}"
+3. **Proceed:** The object is now clean. Continue with the next task step
 
 ## Action Format
-- Use the exact ALFWorld action: `clean {obj} with {recep}`
-- Example: `clean potato 1 with sinkbasin 1`
+- `clean {obj} with {recep}` (e.g., `clean potato 1 with sinkbasin 1`)
+
+## Error Recovery
+- "Nothing happened": Check (1) you are holding the object, (2) you are at the sinkbasin, (3) object and receptacle names are correct
+- Not at sinkbasin: execute `go to sinkbasin 1` first
+
+## Example
+
+**Scenario:** You are holding `potato 1` and need to clean it.
+
+```
+Thought: I need to clean this potato. I should go to the sinkbasin.
+Action: go to sinkbasin 1
+Observation: On the sinkbasin 1, you see nothing.
+Action: clean potato 1 with sinkbasin 1
+Observation: You clean the potato 1 using the sinkbasin 1.
+```
 
-## Error Handling
-- If the action fails (e.g., "Nothing happened"), consult the troubleshooting guide in the references.
-- Ensure you are at the correct receptacle and the object is in your inventory before attempting to clean.
+**Result:** The potato is now in a clean state and ready for the next task step.
 
 ## Post-Condition
-After successful execution, the object will be in a clean state. You may proceed with the next step of your task (e.g., placing the clean object in a microwave).
+After successful execution, the object will be in a clean state. You may proceed with the next step of your task (e.g., placing the clean object on a shelf or in a microwave).

experiments/src/skills/alfworld/alfworld-device-operator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alfworld-device-operator
-description: This skill operates a device or appliance (like a desklamp) to interact with another object. It should be triggered when the task requires using a tool on a target item (e.g., 'look at laptop under the desklamp'). The skill assumes the target object and the operating device are co-located, and it executes the appropriate use action (e.g., toggle, heat, clean).
+description: Operates a device or appliance (like a desklamp, microwave, or fridge) to interact with another object. Use when the task requires using a tool on a target item (e.g., "look at laptop under the desklamp", "heat potato with microwave"). Locates both the device and target object, co-locates them, and executes the appropriate use action (toggle, heat, cool, or clean).
 ---
 # Instructions
 
@@ -42,3 +42,24 @@ Follow this sequence when the skill is triggered:
 *   **Co-location Required:** The skill assumes the final action requires the target object and the operating device to be in the same location (on the same receptacle).
 *   **Device First:** Prioritize finding the device before extensively searching for the target object, as the device's location is often a fixed landmark.
 *   **Invalid Actions:** If the environment responds with "Nothing happened," re-evaluate your object/device names and your location. Ensure you are using the correct action verb for the device type.
+
+## Example
+
+**Scenario:** Task is "look at laptop under the desklamp."
+
+```
+Thought: I need to find the desklamp first. It's likely on a sidetable or desk.
+Action: go to sidetable 1
+Observation: On the sidetable 1, you see a desklamp 1.
+Thought: Found the desklamp. Now I need to find the laptop.
+Action: go to desk 1
+Observation: On the desk 1, you see a laptop 1, a pen 2.
+Action: take laptop 1 from desk 1
+Observation: You pick up the laptop 1 from the desk 1.
+Action: go to sidetable 1
+Observation: On the sidetable 1, you see a desklamp 1.
+Action: use desklamp 1
+Observation: You turn on the desklamp 1.
+```
+
+**Result:** The laptop is now being examined under the desklamp, completing the task.

experiments/src/skills/alfworld/alfworld-environment-scanner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alfworld-environment-scanner
-description: Performs an initial scan of the Alfworld environment to identify all visible objects and receptacles. Processes raw observation text into a structured list of entities to build a mental map for planning.
+description: Performs an initial scan of the ALFWorld environment to identify all visible objects and receptacles. Use when you first enter an environment and need to build a mental map for task planning. Processes raw observation text into a structured list of entities, categorizing them as objects or receptacles.
 ---
 # Instructions
 

experiments/src/skills/alfworld/alfworld-heat-object-with-appliance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alfworld-heat-object-with-appliance
-description: This skill uses a heating appliance (e.g., microwave, stove) to apply heat to a specified object. It should be triggered when the task requires warming or cooking an item, and the appliance is available and properly prepared (e.g., empty, closed). The input is the object name and appliance name, and the output is the object being heated, changing its state to fulfill task goals like 'heat some egg'.
+description: Uses a heating appliance (microwave, stoveburner, oven) to apply heat to a specified object. Use when the task requires warming or cooking an item (e.g., "heat some egg", "warm the mug") and a heating appliance is available. Takes the object name and appliance name as input and outputs the object in a heated state, ready for placement at the task's target location.
 ---
 # Skill: Heat Object with Appliance
 
@@ -24,6 +24,23 @@ Follow this sequence of actions. Use the bundled `validate_and_plan.py` script t
 *   **Object Location:** The object may not be at the initial location. Be prepared to search other receptacles (e.g., fridge, countertop, cabinet) if not found.
 *   **Alternative Appliances:** If the primary appliance (e.g., microwave) is unavailable or broken, consider alternatives like a stoveburner.
 
+## Example
+
+**Task:** "Heat some egg and put it on the diningtable."
+
+**Input:** `object: egg 1`, `appliance: microwave 1`, `target: diningtable 1`
+
+**Sequence:**
+1. `go to fridge 1` → Observation: "You are at fridge 1."
+2. `open fridge 1` → Observation: "You open the fridge 1. You see egg 1, ..."
+3. `take egg 1 from fridge 1` → Observation: "You pick up the egg 1 from the fridge 1."
+4. `go to microwave 1` → Observation: "You are at microwave 1."
+5. `heat egg 1 with microwave 1` → Observation: "You heat the egg 1 using the microwave 1."
+6. `go to diningtable 1` → Observation: "You are at diningtable 1."
+7. `put egg 1 in/on diningtable 1` → Observation: "You put the egg 1 in/on the diningtable 1."
+
+**Output:** The egg 1 is heated and placed on the diningtable 1. Task complete.
+
 ## Bundled Resources
 *   `scripts/validate_and_plan.py`: A utility to check the initial environment state against the skill's prerequisites.
 *   `references/common_heating_appliances.md`: A list of typical appliances and their properties in the ALFWorld environment.

experiments/src/skills/alfworld/alfworld-inventory-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alfworld-inventory-management
-description: This skill tracks which objects have been collected and which remain to be found for multi-object tasks. It should be triggered when working with tasks requiring multiple instances of the same object type. The skill maintains a count of collected vs. needed objects and guides the search for remaining items.
+description: Use when the agent must collect and track multiple instances of the same object type in ALFWorld (e.g., "put two cellphone in bed"). This skill maintains a count of collected versus needed objects, guides systematic searching through receptacles, and ensures each found object is placed at the target before searching for the next.
 ---
 # Inventory Management Skill
 
@@ -14,19 +14,69 @@ Activate this skill when:
 
 ### 1. Initialize Inventory
 - Parse the task description to identify:
-  - Target object type (e.g., "cellphone")
-  - Required quantity (e.g., "two")
+  - **Target object type** (e.g., "cellphone")
+  - **Required quantity** (e.g., "two" = 2)
+  - **Target receptacle** (e.g., "bed 1")
 - Initialize counters: `collected = 0`, `needed = <quantity>`
 - Create empty list for searched locations
 
 ### 2. Systematic Search Pattern
 Follow this search priority:
-1. **Visible surfaces** (desks, dressers, beds) - check first
-2. **Closed containers** (drawers, cabinets) - open and inspect
-3. **Return to known locations** if inventory incomplete
+1. **Visible surfaces** (desks, dressers, beds, countertops) - check first
+2. **Closed containers** (drawers, cabinets, safes) - open and inspect
+3. **Less common locations** (shelves, side tables, garbage cans)
+4. **Return to known locations** if inventory incomplete
 
-**Critical Rule:** After finding an object, immediately place it at the target location before searching for the next one.
+**Critical Rule:** After finding an object, immediately place it at the target location before searching for the next one. Do not attempt to carry multiple objects simultaneously.
 
 ### 3. Action Decision Logic
-Use this decision tree:
+Use this decision tree at each step:
 
+```
+Is target object visible in current observation?
+├── YES → Take it, go to target receptacle, put it down
+│         └── Increment collected counter
+│             ├── collected == needed → TASK COMPLETE
+│             └── collected < needed → Continue searching
+└── NO → Have all receptacles been searched?
+          ├── YES → Revisit receptacles (objects may have been missed)
+          └── NO → Go to next unsearched receptacle
+```
+
+### 4. Per-Object Cycle
+For each object instance found, follow this exact sequence:
+1. `take {object} from {current_receptacle}`
+2. `go to {target_receptacle}`
+3. `put {object} in/on {target_receptacle}`
+4. Update counter: `collected += 1`
+5. If `collected < needed`, navigate to next unsearched receptacle
+
+## Example
+
+**Task:** "Put two cellphone in bed 1."
+
+```
+> go to desk 1
+On the desk 1, you see a cellphone 2, a pen 1.
+> take cellphone 2 from desk 1
+You pick up the cellphone 2 from the desk 1.
+> go to bed 1
+On the bed 1, you see a pillow 1.
+> put cellphone 2 in/on bed 1
+You put the cellphone 2 in/on the bed 1.
+[collected: 1/2]
+> go to dresser 1
+On the dresser 1, you see a cellphone 3, a keychain 1.
+> take cellphone 3 from dresser 1
+You pick up the cellphone 3 from the dresser 1.
+> go to bed 1
+On the bed 1, you see a cellphone 2, a pillow 1.
+> put cellphone 3 in/on bed 1
+You put the cellphone 3 in/on the bed 1.
+[collected: 2/2 — TASK COMPLETE]
+```
+
+## Error Handling
+- **Object not at expected location**: Mark location as searched, proceed to next receptacle
+- **"Nothing happened"**: The action syntax may be wrong; verify object name and receptacle
+- **Counter mismatch**: Re-examine the target receptacle to confirm how many objects are already placed

experiments/src/skills/alfworld/alfworld-locate-target-object/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alfworld-locate-target-object
-description: This skill navigates to a suspected location and identifies a target object. It should be triggered when the agent's goal requires finding a specific object (e.g., 'potato', 'plate') and its location is not immediately known. The skill involves moving to a relevant receptacle (like a fridge or cabinet) and checking its contents, outputting the object's location or confirming its absence.
+description: Navigates to a suspected location and identifies a target object. Use when your goal requires finding a specific object (e.g., "potato", "plate") and its location is not immediately known. Moves to a relevant receptacle (like a fridge or cabinet), checks its contents, and outputs the object's location or confirms its absence.
 ---
 # Skill: Locate Target Object
 
@@ -36,5 +36,19 @@ Follow this sequence of actions and reasoning.
 *   **Sequential Access:** You must `go to` a location before you can `open` it.
 *   **Visual Confirmation:** Only trust the `Observation` after opening a receptacle to confirm an object's presence or absence.
 
+## Example
+
+**Scenario:** You need to find a potato for a heating task.
+
+```
+Thought: I need to find a potato. Potatoes are commonly stored in the fridge.
+Action: go to fridge 1
+Observation: The fridge 1 is closed.
+Action: open fridge 1
+Observation: You open the fridge 1. The fridge 1 is open. In it, you see a potato 1, a lettuce 2.
+```
+
+**Result:** The potato has been located in `fridge 1`. You can now `take potato 1 from fridge 1` and proceed.
+
 ## Next Steps
 After successfully locating the object, you will typically need to `take` it or interact with it, which is outside the scope of this skill. If the object is not found, trigger this skill again with a new suspected location.