Skip to content

Create, Evaluate, and Connect AI Skills

feat: improve 15 ScienceWorld skill scores (+22% avg)

Alan Pope1c3faca6b58e
diff --git a/experiments/src/skills/scienceworld/scienceworld-conditional-placer/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-conditional-placer/SKILL.md
index c46c6b7..d61962c 100644
--- a/experiments/src/skills/scienceworld/scienceworld-conditional-placer/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-conditional-placer/SKILL.md
@@ -1,28 +1,39 @@
---
name: scienceworld-conditional-placer
-description: Places an object into one of several designated containers based on a measured condition, such as a temperature threshold. It is triggered after a measurement or assessment when the task requires sorting or storing the object according to a rule.
+description: Places an object into one of several designated containers based on a measured condition, such as a temperature threshold. Use this skill when you have completed a measurement or assessment and the task requires sorting or storing the object into one of multiple containers according to a rule (e.g., "if temperature > X, place in container A; otherwise container B").
---
# Skill: Conditional Object Placer
## Purpose
-This skill enables an agent to place a target object into a specific container based on a measured condition (e.g., temperature). It is used after a measurement step to complete a conditional sorting or storage objective.
+Place a target object into the correct container based on a measured condition (e.g., temperature threshold, conductivity result). This skill executes the full measure-then-sort workflow.
## Core Workflow
-1. **Locate & Acquire Measurement Tool:** Find and pick up the required measurement device (e.g., thermometer).
-2. **Locate & Acquire Target Object:** Find and pick up the object to be measured and placed (e.g., metal fork).
-3. **Identify Target Containers:** Find the designated containers (e.g., blue box, orange box).
-4. **Perform Measurement:** Use the measurement tool on the target object to obtain the relevant value.
-5. **Evaluate Condition & Execute Placement:** Apply the given rule to the measured value to select the correct container, then move the object into it.
+1. **Locate & Acquire Measurement Tool:** `teleport to LOC` then `pick up` the measurement device (e.g., thermometer).
+2. **Locate & Acquire Target Object:** `teleport to LOC` then `pick up` the object to be measured (e.g., metal fork).
+3. **Identify Target Containers:** Use `look around` to find the designated containers (e.g., blue box, orange box).
+4. **Perform Measurement:** `use OBJ on OBJ` (e.g., `use thermometer on metal fork`) to obtain the value.
+5. **Evaluate Condition & Place:** Compare the measured value against the threshold, then `move OBJ to OBJ` to place the object in the correct container.
-## Key Actions & Logic
-* Use `teleport to LOC` to navigate efficiently between rooms.
-* Use `look around` to survey a room and locate objects.
-* Use `pick up OBJ` to acquire tools and the target object.
-* Use `use OBJ [on OBJ]` to perform the measurement (e.g., `use thermometer on metal fork`).
-* Use `move OBJ to OBJ` to place the target object into the selected container.
-* The decision logic is simple: compare the measured value against the provided threshold and select the corresponding container.
+## Key Actions
+| Action | Purpose |
+|--------|---------|
+| `teleport to LOC` | Navigate between rooms |
+| `look around` | Survey a room for objects |
+| `pick up OBJ` | Acquire tools or target object |
+| `use OBJ on OBJ` | Perform measurement |
+| `move OBJ to OBJ` | Place object into selected container |
+
+## Example
+**Task:** "Measure the temperature of the metal fork. If above 50C, place in the orange box. Otherwise, place in the blue box."
+
+1. `teleport to kitchen`
+2. `look around` — find thermometer and metal fork
+3. `pick up thermometer`
+4. `pick up metal fork`
+5. `use thermometer on metal fork` — reads 72 degrees
+6. 72 > 50, so: `move metal fork to orange box`
## Important Notes
-* All containers are pre-opened. Do not use `open` or `close` actions.
-* The skill assumes the measurement tool and target object can be picked up and are used from the inventory.
-* The specific rooms, object names, threshold value, and container names will vary per task. Adapt the skill steps accordingly.
+* All containers are pre-opened. Do not use `open` or `close` actions.
+* The measurement tool and target object must be picked up and used from inventory.
+* Room names, object names, thresholds, and container names vary per task — adapt accordingly.
diff --git a/experiments/src/skills/scienceworld/scienceworld-container-inspector/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-container-inspector/SKILL.md
index 5d82301..26c9007 100644
--- a/experiments/src/skills/scienceworld/scienceworld-container-inspector/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-container-inspector/SKILL.md
@@ -1,12 +1,9 @@
---
name: scienceworld-container-inspector
-description: This skill performs a 'look at' action to inspect the contents of a specific container or device. It should be triggered when the agent needs to verify what is inside a container (e.g., checking if lead is in the blast furnace) or monitor the state of contents (e.g., solid vs. liquid). The skill outputs a detailed list of contents and their states, providing essential feedback for process monitoring.
+description: Inspects the contents of a container or device using the 'look at' action. Use this skill when you need to verify what is inside a container (e.g., checking if lead is in the blast furnace), monitor the state of contents (e.g., solid vs. liquid phase changes), or confirm that a placement or process step succeeded. Returns a detailed list of contents and their states for process monitoring.
---
# Skill: Container/Device Inspector
-## Purpose
-Execute a `look at` action on a specified container or device to retrieve a detailed observation of its contents and their states. This is a critical monitoring skill for verifying process steps, such as confirming an item is present inside a furnace or checking the phase (solid/liquid) of a substance.
-
## When to Use
Trigger this skill when you need to:
1. **Verify Placement:** Confirm an object has been successfully moved into a target container (e.g., "Is the metal pot in the blast furnace?").
@@ -48,5 +45,3 @@ This skill is often used in a sequence:
- If the container door is closed, you must `open` it before using this skill.
- The skill only inspects; it does not manipulate contents. Use `pick up`, `move`, or `use` for manipulation.
----
-*For detailed examples of container interactions and state transitions, see the reference documentation.*
diff --git a/experiments/src/skills/scienceworld/scienceworld-container-transfer/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-container-transfer/SKILL.md
index 8d06dbc..903dec3 100644
--- a/experiments/src/skills/scienceworld/scienceworld-container-transfer/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-container-transfer/SKILL.md
@@ -1,33 +1,33 @@
---
name: scienceworld-container-transfer
-description: Moves a substance or object from one container to another (e.g., moving lead to a metal pot). Triggered when the agent needs to prepare materials for processing, such as transferring a substance into a heat-resistant container for heating experiments.
+description: Moves a substance or object from one container to another (e.g., moving lead to a metal pot). Use this skill when you need to prepare materials for processing, such as transferring a substance into a heat-resistant container before heating, or reorganizing materials between vessels for mixing or measurement.
---
# Skill: Container Transfer
## Purpose
-This skill orchestrates the transfer of a target substance or object from a source container to a destination container. It is a foundational step for preparing materials for subsequent operations like heating, mixing, or measurement.
+Transfer a target substance or object from a source container to a destination container. This is a foundational step for preparing materials for heating, mixing, or measurement.
-## Core Logic
-The skill is executed when the agent's goal requires moving a material to a more suitable container. The primary sequence, derived from the trajectory, is:
-1. **Identify & Locate:** Confirm the presence of the target substance and the destination container in the current environment.
-2. **Execute Transfer:** Use the `move OBJ to OBJ` action, where the first object is the target substance and the second is the destination container.
-3. **Verify:** Confirm the transfer was successful by examining the destination container's contents.
+## Core Workflow
+1. **Assess Need:** Determine if the current container is unsuitable for the next operation (e.g., tin cup is not heat-resistant for a furnace).
+2. **Locate Items:** Use `look around` and `look at OBJ` to find the target substance and a suitable destination container.
+3. **Execute Transfer:** `move <SUBSTANCE> to <DESTINATION>`.
+4. **Verify:** `look at <DESTINATION>` to confirm the substance is now inside.
-## Instructions
-Follow this decision flow to perform a container transfer:
+## Key Actions
+| Action | Purpose |
+|--------|---------|
+| `look around` | Survey room for containers and substances |
+| `look at OBJ` | Inspect container contents |
+| `move OBJ to OBJ` | Transfer substance to destination |
-1. **Assess the need for transfer.** Is the target substance in a container unsuitable for the next planned operation (e.g., a tin cup is not heat-resistant for a furnace)?
-2. **Locate the target substance and a suitable destination container** (e.g., `lead` in a `tin cup` and an empty `metal pot`). Use `look around` and `look at OBJ` actions.
-3. **Execute the transfer command:** `move <SUBSTANCE_NAME> to <DESTINATION_CONTAINER>`.
- * Example: `move lead to metal pot`
-4. **Verify the transfer** by looking at the destination container: `look at <DESTINATION_CONTAINER>`.
- * Expected observation: The container now lists the target substance in its contents.
+## Example
+**Task:** Transfer lead from a tin cup to a heat-resistant metal pot for furnace heating.
-## Key Parameters
-* `<SUBSTANCE_NAME>`: The name of the substance or object to be moved (e.g., `lead`).
-* `<DESTINATION_CONTAINER>`: The name of the container to receive the substance (e.g., `metal pot`).
+1. `look around` — spot `tin cup (containing lead)` and `metal pot`
+2. `move lead to metal pot`
+3. `look at metal pot` — confirms: "a metal pot (containing a substance called lead)"
-## Notes
-* This skill assumes containers are already open, as per the environment rules.
-* The skill is context-aware; the destination container should be chosen based on the properties needed for the next step (e.g., heat resistance for a furnace).
-* If the transfer fails (e.g., "You can't do that"), check the object names and ensure the destination container is accessible and capable of holding the substance.
+## Important Notes
+* All containers are pre-opened. Do not use `open` or `close` actions.
+* Choose the destination container based on properties needed for the next step (e.g., heat resistance for furnace use).
+* If the transfer fails ("You can't do that"), verify object names with `look around` and ensure the destination is accessible.
diff --git a/experiments/src/skills/scienceworld/scienceworld-device-activator/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-device-activator/SKILL.md
index 4e8a6be..0f544a7 100644
--- a/experiments/src/skills/scienceworld/scienceworld-device-activator/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-device-activator/SKILL.md
@@ -1,37 +1,38 @@
---
name: scienceworld-device-activator
-description: This skill activates a device (e.g., blast furnace, stove) to initiate a process like heating. It should be triggered when the agent has placed materials in a device and needs to start the device's operation. The skill takes a device name as input and outputs a confirmation of activation, which is critical for progressing tasks that require energy or processing.
+description: Activates a device (e.g., blast furnace, stove) to initiate a process like heating. Use this skill when you have placed materials inside a device and need to start its operation. Takes a device name as input and outputs a confirmation of activation, enabling tasks that require energy input or material processing to progress.
---
-# Device Activation Skill
+# Skill: Device Activator
## Purpose
-Activate a specific device to begin its operation (e.g., heating, processing). This is a critical step when materials have been placed into a device and require energy input to proceed with an experiment or task.
-
-## When to Use
-- You have confirmed that the target materials are properly placed inside the device.
-- The device is in a deactivated or "off" state.
-- The next step in your task requires the device to be operating (e.g., heating lead in a blast furnace).
-
-## Core Instruction
-Execute the `activate` action on the target device.
-
-**Action Format:** `activate <DEVICE_NAME>`
-
-**Example:** `activate blast furnace`
-
-## Prerequisites
-1. **Material Placement:** Ensure the target material(s) are inside the device. Use `look at <DEVICE_NAME>` to verify contents.
-2. **Device State:** Confirm the device is deactivated. The observation will typically indicate "which is turned off" or "which is deactivated."
-3. **Safety Check:** Ensure the device door is open if required for loading. Most devices in this environment are pre-opened.
-
-## Post-Activation Steps
-1. **Verification:** After activation, check the device state with `look at <DEVICE_NAME>` or `examine <DEVICE_NAME>` to confirm it's now "turned on" or "activated."
-2. **Monitoring:** Use appropriate measurement tools (e.g., thermometer) on the materials inside the device to track progress.
-3. **Deactivation:** Remember to deactivate the device when the process is complete using `deactivate <DEVICE_NAME>`.
-
-## Common Devices & Context
-- **Blast Furnace:** For high-temperature melting (e.g., metals like lead).
-- **Stove/Oven:** For general heating tasks.
-- **Other Devices:** Any device with an observable on/off state that requires activation to function.
-
-For detailed device specifications and safety guidelines, see the reference documentation.
+Activate a device (turn it on, start it, fire it up) to begin its operation — typically heating, processing, or powering a task step.
+
+## Core Workflow
+1. **Verify Contents:** `look at <DEVICE_NAME>` to confirm materials are placed inside.
+2. **Check State:** Observation should show "which is turned off" or "which is deactivated."
+3. **Activate:** `activate <DEVICE_NAME>`
+4. **Verify Activation:** `look at <DEVICE_NAME>` — confirm it now reads "turned on" or "activated."
+5. **Monitor (if needed):** Use measurement tools (e.g., `use thermometer on <MATERIAL>`) to track progress.
+6. **Deactivate When Done:** `deactivate <DEVICE_NAME>`
+
+## Key Actions
+| Action | Purpose |
+|--------|---------|
+| `look at <DEVICE>` | Verify contents and device state |
+| `activate <DEVICE>` | Turn on / start the device |
+| `deactivate <DEVICE>` | Turn off the device when done |
+| `use TOOL on OBJ` | Monitor material state during processing |
+
+## Example
+**Task:** Melt lead in a blast furnace.
+
+1. `look at blast furnace` — confirms: metal pot with lead inside, furnace is turned off
+2. `activate blast furnace`
+3. `look at blast furnace` — confirms: "which is turned on"
+4. `use thermometer on lead` — monitor temperature
+5. `look at blast furnace` — observe: "a substance called liquid lead" (melting complete)
+6. `deactivate blast furnace`
+
+## Important Notes
+* Most devices are pre-opened. Do not use `open` or `close` unless the observation indicates a closed door.
+* Always verify activation succeeded before proceeding to the next task step.
diff --git a/experiments/src/skills/scienceworld/scienceworld-instruction-reader/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-instruction-reader/SKILL.md
index 837ebf3..b5f8d50 100644
--- a/experiments/src/skills/scienceworld/scienceworld-instruction-reader/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-instruction-reader/SKILL.md
@@ -1,19 +1,32 @@
---
name: scienceworld-instruction-reader
-description: This skill reads a recipe or note from the inventory using the 'read' action. It should be triggered after acquiring a recipe or document to extract explicit instructions, ingredient lists, or procedural steps. The skill parses the text content and outputs the key information needed to execute the task, such as required components and their combinations.
+description: Reads a recipe or note from the inventory using the 'read' action and extracts key information. Use this skill when you have acquired a recipe, note, or readable document in your inventory and need to extract explicit instructions, ingredient lists, or procedural steps before executing a task.
---
-# Instructions
-Use this skill when you have acquired a recipe, note, or any readable document in your inventory and need to understand its contents to proceed with a task.
+# Skill: Instruction Reader
-## Core Action
-1. **Read the Document:** Use the `read OBJ` action on the document in your inventory.
- * **Example:** `read recipe in inventory`
+## Purpose
+Read and parse a document (recipe, note, or instructions) from your inventory to extract the information needed to execute the current task.
-## Skill Logic
-After reading, analyze the text to identify:
-* **Goal:** The final product or objective (e.g., "make salt water").
-* **Required Components:** A list of items or substances needed (e.g., "sodium chloride, water").
-* **Procedural Steps:** Any explicit actions or combinations described (e.g., "mix sodium chloride, water").
+## When to Use
+- After picking up a recipe, note, or readable document.
+- When the task requires following written instructions (e.g., mixing chemicals, assembling components).
+- Before starting a multi-step procedure that depends on written directions.
-## Output Format
-Present the extracted information clearly. For example:
+## Core Workflow
+1. **Read the Document:** `read OBJ` on the document in your inventory.
+2. **Extract Key Information:**
+ - **Goal:** The final product or objective (e.g., "make salt water").
+ - **Required Components:** Items or substances needed (e.g., "sodium chloride, water").
+ - **Procedural Steps:** Actions or combinations described (e.g., "mix sodium chloride, water").
+3. **Plan Next Actions:** Use the extracted information to determine which skills and actions to invoke next.
+
+## Example
+**Task:** Follow a recipe to make salt water.
+
+1. `pick up recipe` — acquire the document
+2. `read recipe in inventory` — output: "To make salt water, mix sodium chloride and water in a glass jar."
+3. **Extracted info:**
+ - Goal: salt water
+ - Components: sodium chloride, water
+ - Procedure: mix in glass jar
+4. Proceed to fetch sodium chloride, water, and glass jar, then mix.
diff --git a/experiments/src/skills/scienceworld/scienceworld-inventory-manager/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-inventory-manager/SKILL.md
index 46de0fc..5c57c30 100644
--- a/experiments/src/skills/scienceworld/scienceworld-inventory-manager/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-inventory-manager/SKILL.md
@@ -1,37 +1,37 @@
---
name: scienceworld-inventory-manager
-description: This skill handles picking up objects from the environment into the agent's inventory or moving them out. It should be triggered when the agent needs to acquire an object for later use or place an object into a container. The input is an object name and location, and the output is the object being transferred to or from inventory.
+description: Handles picking up objects from the environment into the agent's inventory or moving them out to containers. Use this skill when you need to acquire an object for later use (pick up) or place an object into a specific container as part of a task requirement (move). Takes an object name and location as input and confirms the transfer to or from inventory.
---
-# Instructions
+# Skill: Inventory Manager
## Purpose
-Use this skill to manage the agent's inventory by picking up objects from the environment or placing them into containers. This is a foundational action for acquiring tools, materials, or evidence needed for tasks.
-
-## When to Use
-- You need to acquire an object for later use in an experiment or task.
-- You need to place an object into a specific container (e.g., a box, a table, a room) as part of a task requirement.
-- The object's location is known or can be inferred from context.
-
-## Core Action Pattern
-The primary action is `pick up OBJ` to acquire an object or `move OBJ to OBJ` to place it into a container. The exact syntax may vary slightly based on the environment's action space (e.g., `pick up metal pot containing nothing in kitchen` vs. `move metal pot to blue box`).
-
-## Procedure
-1. **Locate the Object:** Ensure you are in the correct room or that the object is in your immediate vicinity. Use `look around` or `examine` if needed.
-2. **Acquire the Object:** If the object is not in your inventory, use the `pick up` action with the correct object identifier and location.
-3. **Place the Object (if required):** If the task requires placing the object into a container, use the `move` action with the target container's name.
-
-## Key Considerations
-- **Object State:** Some objects may be described as "containing nothing." Include this in the action if the environment's grammar requires it (e.g., `pick up metal pot containing nothing in kitchen`).
-- **Container Targets:** When moving an object to a container like a box, use the container's name and color if specified (e.g., `blue box`, `orange box`).
-- **Inventory Management:** You can only hold one item in your inventory at a time in the provided trajectory. Plan your actions accordingly.
-
-## Example from Trajectory
-**Goal:** Acquire the metal pot from the kitchen.
-- Action: `pick up metal pot containing nothing in kitchen`
-- Result: "You move the metal pot to the inventory."
-
-**Goal:** Place the conductive metal pot into the correct box.
-- Action: `move metal pot to blue box`
-- Result: The object is transferred from inventory (or the room) to the specified container.
-
-For complex object interactions or environment-specific grammar, consult the bundled reference.
+Manage the agent's inventory: pick up objects from the environment or place them into containers.
+
+## Core Workflow
+1. **Locate Object:** Use `look around` to confirm the object is present and note its exact name.
+2. **Acquire:** `pick up OBJ` to move the object into your inventory.
+3. **Place (if needed):** `move OBJ to OBJ` to transfer the object to a container.
+4. **Verify:** Check the observation feedback to confirm the action succeeded. If it fails, verify exact object names with `look around`.
+
+## Key Actions
+| Action | Purpose |
+|--------|---------|
+| `look around` | Find objects and confirm names |
+| `pick up OBJ` | Move object to inventory |
+| `move OBJ to OBJ` | Place object into a container |
+
+## Examples
+
+**Acquiring an object:**
+1. `look around` — see "a metal pot containing nothing" in the kitchen
+2. `pick up metal pot containing nothing in kitchen`
+3. Result: "You move the metal pot to the inventory."
+
+**Placing an object:**
+1. `move metal pot to blue box`
+2. Result: Object transferred to the blue box.
+
+## Important Notes
+* Some objects include state descriptions in their name (e.g., "metal pot containing nothing"). Use the full name as shown in the environment.
+* Use container color and name as specified in the task (e.g., `blue box`, `orange box`).
+* Inventory capacity is limited — plan pick up and place actions to avoid conflicts.
diff --git a/experiments/src/skills/scienceworld/scienceworld-item-fetcher/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-item-fetcher/SKILL.md
index da27844..e64a9c7 100644
--- a/experiments/src/skills/scienceworld/scienceworld-item-fetcher/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-item-fetcher/SKILL.md
@@ -1,6 +1,6 @@
---
name: scienceworld-item-fetcher
-description: This skill picks up a specified object from the environment and moves it into the agent's inventory. It should be triggered when the agent identifies a required tool or material (e.g., thermometer, metal pot) that needs to be collected for later use. The skill takes an object name as input and confirms the item's transfer to inventory, facilitating object manipulation across locations.
+description: Picks up a specified object from the environment and moves it into the agent's inventory. Use this skill when you identify a required tool or material (e.g., thermometer, metal pot) that needs to be collected for later use in an experiment or task. Takes an object name as input and confirms the item's transfer to inventory.
---
# Skill: Fetch and Inventory Item
diff --git a/experiments/src/skills/scienceworld/scienceworld-liquid-pourer/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-liquid-pourer/SKILL.md
index 4d8c741..8bea819 100644
--- a/experiments/src/skills/scienceworld/scienceworld-liquid-pourer/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-liquid-pourer/SKILL.md
@@ -1,27 +1,39 @@
---
name: scienceworld-liquid-pourer
-description: This skill transfers the contents of a source liquid container into a target container for mixing or preparation. It should be triggered when combining multiple substances, such as paints or chemicals, into a single vessel.
+description: Transfers the contents of a source liquid container into a target container for mixing or preparation. Use this skill when you need to combine multiple substances (such as paints or chemicals) into a single vessel, or when a liquid must be moved from one container to another before processing.
---
-# Instructions for Liquid Pouring
+# Skill: Liquid Pourer
-This skill orchestrates the transfer of a liquid from a source container to a target container, typically as a preparatory step for mixing or chemical combination.
+## Purpose
+Transfer a liquid from a source container to a target container, typically as a preparatory step for mixing or chemical combination.
-## Core Action
-The primary action is `pour OBJ into OBJ`. Use this to transfer the contents.
+## When to Use
+- Combining multiple liquids or substances into one vessel for mixing.
+- Moving a liquid to a more suitable container before heating or processing.
+- Preparing ingredients for a recipe that requires pouring.
-## Execution Flow
-1. **Identify Containers:** Locate the source container (holding the liquid to be transferred) and the target container (the destination vessel).
-2. **Perform Transfer:** Execute the `pour` action with the correct object identifiers.
-3. **Verify (Optional):** If necessary, examine the target container to confirm the transfer was successful.
+## Core Workflow
+1. **Identify Containers:** Use `look around` to locate the source container (with the liquid) and the target container (destination vessel).
+2. **Perform Transfer:** `pour OBJ into OBJ` with precise object identifiers.
+3. **Verify:** `look at OBJ` on the target container to confirm the transfer succeeded.
-## Key Considerations
-* Ensure the target container is empty or can receive the new substance without adverse reaction (e.g., contamination).
-* The skill is often used in sequence with other skills, such as `mix`, to achieve a final compound.
-* Object identifiers (e.g., `wood cup (containing red paint)`) must be precise. Use `look around` and `examine` actions to confirm object states and contents if unsure.
+## Key Actions
+| Action | Purpose |
+|--------|---------|
+| `look around` | Locate source and target containers |
+| `pour OBJ into OBJ` | Transfer liquid contents |
+| `look at OBJ` | Verify transfer success |
+| `mix OBJ` | Combine contents (separate skill, used after pouring) |
-## Example Usage
-* **Goal:** Create orange paint by mixing red and yellow.
-* **Procedure:**
- 1. `pour wood cup (containing red paint) into jug`
- 2. `pour wood cup (containing yellow paint) into jug`
- 3. `mix jug` (This is a separate mixing skill, not part of the pour operation).
+## Example
+**Task:** Create orange paint by mixing red and yellow paint.
+
+1. `look around` — find `wood cup (containing red paint)`, `wood cup (containing yellow paint)`, and `jug`
+2. `pour wood cup (containing red paint) into jug`
+3. `pour wood cup (containing yellow paint) into jug`
+4. `mix jug` — produces orange paint
+
+## Important Notes
+* Object identifiers must be precise (e.g., `wood cup (containing red paint)`). Use `look around` or `examine` to confirm exact names.
+* Ensure the target container can receive the substance without contamination.
+* Pouring only transfers contents — use `mix` as a separate step to combine them.
diff --git a/experiments/src/skills/scienceworld/scienceworld-living-entity-identifier/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-living-entity-identifier/SKILL.md
index bf3d248..4df9695 100644
--- a/experiments/src/skills/scienceworld/scienceworld-living-entity-identifier/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-living-entity-identifier/SKILL.md
@@ -1,25 +1,40 @@
---
name: scienceworld-living-entity-identifier
-description: Analyzes room observations to identify potential living things (e.g., eggs, plants, animals) among listed objects. Processes observation text, flags candidate living items based on domain knowledge, and outputs a focused target for subsequent actions.
+description: Analyzes room observations to identify potential living things (e.g., eggs, plants, animals) among listed objects. Use this skill when a task involves finding, focusing on, or interacting with a living thing, biological entity, or organism. Processes observation text, flags candidate living items based on domain knowledge, and outputs a focused target for subsequent actions like focus on or pick up.
---
# Skill: Living Entity Identifier
## Purpose
-Use this skill when the task involves finding, focusing on, or interacting with a "living thing," "biological entity," "organism," or similar target. The skill analyzes the textual observation of a room to identify candidate objects that are likely to be living or contain life (e.g., eggs, plants, animals).
+Identify living things (eggs, plants, animals) from room observations and focus on them for task progression.
-## Core Logic
-1. **Trigger:** The task description mentions a living entity.
-2. **Analyze:** Parse the current room's observation text.
-3. **Identify:** Flag objects from a known list of living entity indicators (see `references/living_indicators.md`).
-4. **Output:** Select the most suitable candidate and formulate the next action (typically `focus on [TARGET]` or `examine [TARGET]`).
+## Core Workflow
+1. **Survey Room:** `look around` to get the observation text listing all objects.
+2. **Identify Candidates:** Scan the object list for living entity indicators:
+ - **Animals:** dove, giant tortoise, bee, frog, fish
+ - **Eggs:** dove egg, chicken egg, turtle egg
+ - **Plants:** flower, tree, moss, fern, algae
+ - **Other biological:** mushroom, seed, pollen
+3. **Focus on Target:** `focus on [IDENTIFIED_OBJECT]` to signal task progress.
+4. **Transport (if needed):** `pick up [OBJECT]` then `move [OBJECT] to [CONTAINER]`.
-## Primary Workflow
-1. **Look Around:** First, use `look around` to get the room's observation text.
-2. **Run Analysis:** Process the observation using the logic in `scripts/analyze_observation.py`.
-3. **Execute Focus:** If a candidate is found, perform `focus on [IDENTIFIED_OBJECT]`.
-4. **Handle Inventory/Transport:** If the task requires moving the entity, proceed with `pick up` and `move` actions to the specified destination.
+## Key Actions
+| Action | Purpose |
+|--------|---------|
+| `look around` | Survey room for objects |
+| `teleport to LOC` | Move to rooms with biological likelihood |
+| `focus on OBJ` | Signal identification to task system |
+| `pick up OBJ` | Acquire entity for transport |
-## Key Rules
-* Prioritize explicit living things (e.g., "dove egg," "giant tortoise") over ambiguous substances (e.g., "air," "water").
-* If the initial room lacks candidates, teleport to rooms with higher biological likelihood (e.g., `outside`, `greenhouse`, `bedroom`).
-* The `focus on` action is critical for signaling task progress. Use it immediately after identification.
+## Example
+**Task:** "Find a living thing in the environment."
+
+1. `teleport to outside`
+2. `look around` — observation lists: "a dove egg", "a rock", "soil"
+3. Identify "dove egg" as the living entity candidate
+4. `focus on dove egg`
+5. If transport required: `pick up dove egg` then `move dove egg to blue box`
+
+## Important Notes
+* Prioritize explicit living things (e.g., "dove egg," "giant tortoise") over ambiguous substances (e.g., "air," "water").
+* If the current room lacks candidates, `teleport to` rooms with higher biological likelihood: `outside`, `greenhouse`, `bedroom`.
+* Always use `focus on` immediately after identification — it signals task progress.
diff --git a/experiments/src/skills/scienceworld/scienceworld-object-locator/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-object-locator/SKILL.md
index 772ba7c..f2cbb10 100644
--- a/experiments/src/skills/scienceworld/scienceworld-object-locator/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-object-locator/SKILL.md
@@ -1,6 +1,6 @@
---
name: scienceworld-object-locator
-description: This skill searches for a specific target object across multiple rooms by systematically teleporting to likely locations and examining each room. It should be triggered when the agent needs to find an object whose exact location is unknown. The skill involves iterating through candidate rooms, using room exploration to check for the object, and continues until the target is found, providing the object's location as output.
+description: Searches for a specific target object across multiple rooms by systematically teleporting to likely locations and examining each room. Use this skill when you need to find an object whose exact location is unknown. Iterates through candidate rooms using teleport and look around, checks for the object, and continues until found, returning the object's location.
---
# Instructions
@@ -28,6 +28,15 @@ Locate a specific target object within the ScienceWorld environment when its loc
- `examine <OBJECT>` (if more detail is needed to confirm identity)
- `pick up <OBJECT>` (if the goal is to acquire the object, not just locate it)
+## Example
+**Task:** Find the thermometer in the environment.
+
+1. `teleport to kitchen`
+2. `look around` — no thermometer found
+3. `teleport to workshop`
+4. `look around` — observation includes "a thermometer, currently reading a temperature of 10 degrees celsius"
+5. Thermometer located in workshop. `pick up thermometer` if needed.
+
## Notes & Best Practices
- **Efficiency:** Always `look around` immediately after teleporting to get the full room state.
- **Parsing:** Observations list objects after "you see:". Check this list for the target object's name.
diff --git a/experiments/src/skills/scienceworld/scienceworld-object-placer/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-object-placer/SKILL.md
index db395bd..4e0130b 100644
--- a/experiments/src/skills/scienceworld/scienceworld-object-placer/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-object-placer/SKILL.md
@@ -1,32 +1,34 @@
---
name: scienceworld-object-placer
-description: Moves a specified object from the environment or inventory into a target container based on a classification decision. It should be triggered when a task requires sorting or storing an object in a specific location after an assessment.
+description: Moves a specified object from the environment or inventory into a target container based on a classification decision. Use this skill when a task requires sorting or storing an object in a specific location after an assessment (e.g., placing a conductive object in the blue box or a non-conductive object in the orange box).
---
-# Instructions
+# Skill: Object Placer
-This skill orchestrates the final step of a conditional workflow: moving an object to a designated container after its properties have been assessed.
+## Purpose
+Move an object into the correct container based on a prior classification or assessment result. This is the final step in conditional sorting workflows.
-## When to Use
-Use this skill when the primary task involves:
-1. **Classifying an object** (e.g., testing for conductivity, checking material type, verifying a state).
-2. **Conditionally placing the object** based on the classification result (e.g., "if property X, place in Container A; else, place in Container B").
+## Core Workflow
+1. **Confirm Assessment Result:** Know which container corresponds to which classification (e.g., "blue box" = conductive, "orange box" = non-conductive).
+2. **Acquire Object (if needed):** `pick up OBJ` if the target is not already in inventory.
+3. **Execute Placement:** `move OBJ to OBJ` — place the object in the correct container.
+4. **Verify Placement:** `look at <CONTAINER>` to confirm the object is now inside.
-## Core Action
-The skill's primary action is `move OBJ to OBJ`. Ensure the target object is identified and the correct destination container is selected based on the prior assessment.
+## Key Actions
+| Action | Purpose |
+|--------|---------|
+| `pick up OBJ` | Acquire object if not in inventory |
+| `move OBJ to OBJ` | Place object into destination container |
+| `look at OBJ` | Verify placement succeeded |
-## Prerequisites
-Before executing this skill, the following must be true:
-* The target object has been located and is accessible (in the environment or inventory).
-* The classification test or assessment has been completed.
-* The result of the assessment is known and the corresponding destination container has been identified.
+## Example
+**Task:** "Determine if metal pot is electrically conductive. If conductive, place in the blue box. If nonconductive, place in the orange box."
-## Execution Flow
-1. **Confirm Context:** Verify the assessment result and the identity of the destination container (e.g., "blue box" for conductive, "orange box" for non-conductive).
-2. **Acquire Object:** If the target object is not already in your inventory, use `pick up OBJ` to acquire it.
-3. **Execute Placement:** Use the `move OBJ to OBJ` action to transfer the object to the correct container.
-4. **Verify:** Optionally, look at the container to confirm the object was placed inside.
+1. Assessment complete: circuit test confirmed metal pot is conductive.
+2. `pick up metal pot` (if not already held)
+3. `move metal pot to blue box`
+4. `look at blue box` — confirms: "In the blue box is: a metal pot"
-## Example from Trajectory
-* **Task:** "Determine if metal pot is electrically conductive. If conductive, place it in the blue box. If nonconductive, place it in the orange box."
-* **Assessment:** A circuit test confirmed the metal pot was conductive.
-* **Skill Execution:** `move metal pot to blue box`
+## Important Notes
+* The classification or assessment must be completed before invoking this skill.
+* Always verify placement with `look at` — do not assume success.
+* Container names vary per task (blue box, orange box, etc.) — match them to the task instructions.
diff --git a/experiments/src/skills/scienceworld/scienceworld-object-retriever/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-object-retriever/SKILL.md
index 02f3092..dd154fd 100644
--- a/experiments/src/skills/scienceworld/scienceworld-object-retriever/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-object-retriever/SKILL.md
@@ -1,20 +1,33 @@
---
name: scienceworld-object-retriever
-description: This skill acquires a specified object by moving it from the environment into the agent's inventory. It should be triggered when a task requires an object to be manipulated, tested, or transported. The skill uses the 'pick up OBJ' action on a target object identified in the room, making it available for further actions in the inventory.
+description: Acquires a specified object by moving it from the environment into the agent's inventory using 'pick up OBJ'. Use this skill when a task requires an object to be manipulated, tested, or transported and it is not yet in your inventory. Makes the object available for further actions like testing, measuring, or placing.
---
-# Instructions
+# Skill: Object Retriever
-## Primary Objective
-Acquire a specified target object from the environment and place it into your inventory.
+## Purpose
+Acquire a target object from the environment and place it into your inventory for further use.
-## Core Procedure
-1. **Locate the Object:** Use the `look around` action to survey the current room. Identify the target object from the description.
-2. **Acquire the Object:** Use the `pick up OBJ` action on the identified target object. Replace `OBJ` with the exact name of the object as seen in the environment description.
-3. **Verification:** Confirm the object is now in your inventory by checking the observation feedback from the `pick up` action.
+## When to Use
+- You need an object for testing, measuring, or transporting.
+- The object is visible in the room but not yet in your inventory.
+- A downstream skill (e.g., tool-user, object-placer) requires the object in inventory.
-## Key Notes
-* This skill is the foundational step for any task requiring physical interaction with an object (e.g., testing, moving, using).
-* Ensure you are in the correct room containing the object before attempting to pick it up. Use `teleport to LOC` if necessary.
-* The object must be accessible and not inside a closed container. If a container is closed, use `open OBJ` first.
-* If the initial `look around` does not reveal the object, you may need to `examine` specific containers or furniture (e.g., `examine table`) to find it.
-* After acquisition, the object is ready for the next skill in the task sequence (e.g., testing conductivity, placing in a specific box).
+## Core Workflow
+1. **Navigate:** `teleport to LOC` if needed to reach the room containing the object.
+2. **Survey:** `look around` to confirm the object is present and identify its exact name.
+3. **Acquire:** `pick up OBJ` using the exact name from the environment description.
+4. **Verify:** Check the observation feedback confirms "You move the [object] to the inventory."
+
+## Example
+**Task:** Retrieve a metal fork from the kitchen for conductivity testing.
+
+1. `teleport to kitchen`
+2. `look around` — see "a metal fork" on the counter
+3. `pick up metal fork`
+4. Observation: "You move the metal fork to the inventory."
+
+## Important Notes
+* Ensure you are in the correct room before attempting `pick up`. Use `teleport to LOC` if necessary.
+* If `look around` does not reveal the object, use `examine` on containers or furniture (e.g., `examine table`).
+* If a container is closed, use `open OBJ` first.
+* After acquisition, the object is ready for the next skill in the task sequence.
diff --git a/experiments/src/skills/scienceworld/scienceworld-room-explorer/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-room-explorer/SKILL.md
index f3dc764..d5c466e 100644
--- a/experiments/src/skills/scienceworld/scienceworld-room-explorer/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-room-explorer/SKILL.md
@@ -1,6 +1,6 @@
---
name: scienceworld-room-explorer
-description: This skill performs an initial survey of a specified room to identify all visible objects and their states. It should be triggered when the agent first enters a new location or needs to refresh its understanding of the environment. The skill uses the 'look around' action and returns a detailed observation of the room's contents, which serves as the foundational context for subsequent object interaction tasks.
+description: Performs an initial survey of a room to identify all visible objects, containers, devices, and their states using the 'look around' action. Use this skill when you first enter a new location, need to refresh your understanding of the environment, or must identify available resources before planning a sequence of actions. Returns a detailed observation that serves as foundational context for subsequent tasks.
---
# Instructions
@@ -25,6 +25,14 @@ Execute the `look around` action. This is the only action required for this skil
* **Connections:** Note any pre-existing wire connections or object placements.
* **Exits:** Identify doors to other rooms and their state (open/closed).
+## Example
+**Scenario:** Agent teleports to the kitchen and needs to identify available resources.
+
+1. `teleport to kitchen`
+2. `look around`
+3. Observation: "This room is called the kitchen. In it, you see: a fridge (containing chocolate, milk), a metal pot, a thermometer, a counter, a stove (which is turned off). You also see: a door to the hallway (which is open)."
+4. **Parsed inventory:** fridge (open, contains chocolate and milk), metal pot, thermometer, counter, stove (off), exit to hallway.
+
## Integration with Other Skills
The observation generated by this skill is essential context for downstream tasks. Before performing actions like `pick up`, `connect`, or `use`, always ensure your understanding of object locations and states is current by running this skill if needed.
diff --git a/experiments/src/skills/scienceworld/scienceworld-substance-fetcher/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-substance-fetcher/SKILL.md
index 734e292..474cd4c 100644
--- a/experiments/src/skills/scienceworld/scienceworld-substance-fetcher/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-substance-fetcher/SKILL.md
@@ -1,6 +1,6 @@
---
name: scienceworld-substance-fetcher
-description: This skill locates and retrieves a target substance or material from a container in the environment. It should be triggered when the core task involves processing a specific substance (e.g., chocolate, a chemical). The skill finds the substance, often inside a fridge or cupboard, and acquires it via a pick-up or move action.
+description: Locates and retrieves a target substance or material from a container in the environment. Use this skill when the task requires processing a specific substance (e.g., chocolate, sodium chloride, a chemical) and you need to find and acquire it. Searches rooms and containers (fridge, cupboard, counter) and retrieves the substance via pick up or move actions.
---
# Skill: Substance Fetcher
diff --git a/experiments/src/skills/scienceworld/scienceworld-tool-user/SKILL.md b/experiments/src/skills/scienceworld/scienceworld-tool-user/SKILL.md
index 012bc25..e5bc376 100644
--- a/experiments/src/skills/scienceworld/scienceworld-tool-user/SKILL.md
+++ b/experiments/src/skills/scienceworld/scienceworld-tool-user/SKILL.md
@@ -1,14 +1,38 @@
---
name: scienceworld-tool-user
-description: Uses a tool from inventory on a target object or location to perform a specific environmental interaction, such as digging or cutting. Activate this skill when a task requires modifying the environment or manipulating materials, like using a shovel to dig soil. It takes the tool and target as inputs and outputs the result of the interaction, enabling physical task progression.
+description: Uses a tool from inventory on a target object or location to perform a specific environmental interaction, such as digging, cutting, or measuring. Use this skill when a task requires modifying the environment or manipulating materials with a tool (e.g., using a shovel to dig soil, a thermometer to measure temperature, or an axe to cut wood). Takes the tool and target as inputs and outputs the result of the interaction.
---
-# Instructions
+# Skill: Tool User
-Use this skill when you need to perform a physical action on the environment using a tool you possess. The core action is `use TOOL on TARGET`.
+## Purpose
+Perform a physical action on the environment using a tool from your inventory. The core action is `use TOOL on TARGET`.
-## 1. Prerequisites
-* **Tool in Inventory:** Ensure the required tool (e.g., `shovel`, `axe`) is in your inventory. Use `pick up OBJ` if it is not.
-* **Clear Target:** Identify the exact target object or location name (e.g., `ground`, `tree`).
+## When to Use
+- A task requires modifying the environment (digging, cutting, heating).
+- You need to measure a property of an object (temperature, conductivity).
+- A tool-based interaction is the next step in your experiment workflow.
-## 2. Core Action
-Execute the interaction with the command:
+## Core Workflow
+1. **Ensure Tool in Inventory:** The required tool (e.g., `shovel`, `thermometer`, `axe`) must be in your inventory. Use `pick up OBJ` if it is not.
+2. **Identify Target:** Determine the exact target object or location name (e.g., `ground`, `tree`, `metal fork`).
+3. **Execute:** `use TOOL on TARGET`.
+4. **Interpret Result:** Read the observation output to determine the outcome (e.g., temperature reading, state change).
+
+## Key Actions
+| Action | Purpose |
+|--------|---------|
+| `pick up OBJ` | Acquire tool if not in inventory |
+| `use OBJ on OBJ` | Perform tool interaction |
+| `look around` | Confirm target identity and location |
+
+## Example
+**Task:** Measure the temperature of a metal fork using a thermometer.
+
+1. `pick up thermometer` — ensure tool is in inventory
+2. `use thermometer on metal fork`
+3. Observation: "a thermometer, currently reading a temperature of 72 degrees celsius"
+
+## Important Notes
+* The tool must be in your inventory before use. The `pick up` action is a prerequisite.
+* Use exact object names as they appear in the environment description.
+* Some tools produce measurable outputs (thermometer readings); others produce state changes (shovel digs soil). Interpret accordingly.