Skills hiarthur

Search Amazon products and analyze materials, design, and reviews to uncover trade-offs and likely disappointments. See results in an interactive GUI.

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/arthgrab/hiarthur" ~/.claude/skills/clawdbot-skills-hiarthur && rm -rf "$T"

manifest: skills/arthgrab/hiarthur/SKILL.md

source content

HiArthur Product Search and Understanding

Overview

Two-endpoint API for intelligent product search and deep product analysis. Products are sourced from Amazon, but results go far beyond what Amazon returns directly — every product is analyzed through a multi-stage pipeline combining computer vision, LLMs, and symbolic reasoning to evaluate how well each product actually matches what the user is looking for and where it's likely to disappoint.

```
POST https://hiarthur.com/api/agents/search
```
— find products matching a query. Each result is graded for fit against the user's requirements using vision + language models, not just keyword matching.
```
POST https://hiarthur.com/api/agents/product
```
— deep-dive one product for failure-mode analysis (FMEA), feature summary, and review synthesis. Uses LLM reasoning over product details and images to surface likely disappointments.

Base URL:

https://hiarthur.com/api

Results can optionally be handed off to a GUI (e.g. https://hiarthur.com/c/<conversation_id> or https://hiarthur.com/product/f7e2a9c1b3d4) where users can browse results visually and continue the conversation interactively.

When to Use This Skill

Use this skill when you need to:

Find products that match detailed user requirements
Evaluate trade-offs between competing products
Identify likely durability or design problems
Understand why a product might disappoint buyers
Compare products beyond simple ratings or keywords

Quick-Start: End-to-End Flow

Step 1 — Start a new search

POST /api/agents/search

{
  "type": "new",
  "search_query": "noise cancelling headphones for travel",
  "search_top_brands": true
}

Response:

{
  "conversation_id": "a1b2c3d4-...",
  "logical_search_id": "ls_abc123",
  "products": [
    {
      "product": {
        "description": "Sony WH-1000XM5 Wireless Noise Canceling Headphones",
        "brand": "Sony",
        "location": "product/f7e2a9c1b3d4",
        "price": 328.0,
        "rating": 4.6,
        "reviews_count": 12450
      },
      "explainer": "Strong noise canceling with long battery life, well suited for travel.",
      "match_grade": "Excellent"
    }
  ],
  "can_fetch_more": true
}

Step 2 — Fetch more results (pagination)

Reuse

conversation_id

and

logical_search_id

exactly as returned.

POST /api/agents/search

{
  "type": "continue",
  "conversation_id": "a1b2c3d4-...",
  "logical_search_id": "ls_abc123"
}

Repeat while

can_fetch_more

true

. A continue response with

products: []

is valid (more may come on the next continue). Stop when

can_fetch_more

false

Step 3 — Deep-dive a product

Use a

product.location

value exactly as returned by search.

POST /api/agents/product

{
  "location": "product/f7e2a9c1b3d4"
}

Response:

{
  "fmea": {
    "unmitigated_failure_modes": [
      {
        "failure_name": "Headband cushion flattens over time",
        "likelihood": {
          "level": "medium",
          "reasoning": "Foam compression builds with daily wear, so most regular users will notice reduced comfort within months."
        },
        "impact": "annoying",
        "timeline": "within_a_year",
        "summary": "The headband padding can compress with regular use, making the headphones less comfortable for long listening sessions.",
        "evidence": [
          "Foam headband cushion visible in images",
          "No mention of memory foam or replaceable pads"
        ]
      }
    ],
    "mitigated_failure_modes": [
      {
        "failure_name": "Poor noise canceling on wind",
        "ownership_experience": "Multipoint wind-noise reduction",
        "reasoning": "Multiple microphones and adaptive ANC algorithms reduce wind interference compared to single-mic designs.",
        "evidence": [
          "Adaptive ANC with multiple external microphones",
          "Wind noise reduction mode listed in features"
        ]
      }
    ],
    "quality_summary": "These headphones prioritize audio quality and noise canceling performance. Most disappointment comes from comfort degradation over time rather than core functionality."
  },
  "features_summary": "Paragraph summarizing key product features based on listing data.",
  "reviews_summary": "Paragraph synthesizing themes and patterns from customer reviews."
}

Search Endpoint — Full Field Reference

New Search (

type: "new"

)

Full example with all optional fields:

{
  "type": "new",
  "search_query": "noise cancelling headphones for travel",
  "search_top_brands": true,
  "trim_query": "Over-ear wireless headphones with active noise canceling and long battery life for airplane use",
  "brands": ["Sony", "Bose"],
  "search_filters": {
    "price_min": 100,
    "price_max": 400,
    "rating_min": 4.0,
    "reviews_min": 500
  },
  "search_sort": "relevance"
}

Field	Type	Required	Default	Description
`type`	`"new"`	yes	—	Discriminator.
`search_query`	string	yes	—	Broad retrieval query sent to the product catalog. Should be precise, user-intent-aligned, and include all key attributes (color, size, material, use case, gender).
`search_top_brands`	boolean	yes	—	When `true` , restricts results to recognized top brands in the category. Default to `true` for electronics, appliances, clothing, tools, beauty, home/kitchen. Default to `false` for books, media.
`trim_query`	string	no	same as `search_query`	Similarity-trimming query. After retrieval, products with low similarity to this string are removed. Should be a fluent, attribute-rich, natural-language description optimized for matching product titles and images. More descriptive than `search_query` . See examples below.
`conversation_id`	UUID string	no	server-generated	Omit to let the server create a new conversation. Supply to attach this search to an existing conversation.
`brands`	string[]	no	`[]`	Explicit brand-name constraints. Only populate when the user names specific brands. Use canonical names with proper capitalization (e.g., `["Nike", "Adidas"]` ).
`search_filters`	object	no	`null`	All sub-fields optional and nullable: `price_min` (number), `price_max` (number), `rating_min` (number), `reviews_min` (integer). No extra keys allowed.
`search_sort`	enum string	no	`null`	`"relevance"` , `"price_low"` , `"price_high"` , or `"best_sellers"` .

search_query

trim_query

search_query

drives broad catalog retrieval.

trim_query

is applied after retrieval as a similarity filter — products with low similarity to it are removed.

trim_query

should read like a grounded, attribute-rich product description:

"A men's sleeveless hooded vest made of shiny metallic fabric with a full zipper front."
"A 12-pack of chocolate-flavored protein shakes, each bottle containing 20 grams of protein."
"A thick purple yoga mat made of dense non-slip foam, measuring one inch in thickness."
"A 10-inch nonstick frying pan with a ceramic coating and induction-compatible base."
"Wireless Bluetooth 5.3 earbuds with noise-canceling features and at least 40 hours of battery life."

When omitted,

trim_query

defaults to

search_query

. Only set it when you have a more descriptive version.

Continue Search (

type: "continue"

)

Field	Type	Required	Description
`type`	`"continue"`	yes	Discriminator.
`conversation_id`	UUID string	yes	Exact value from the prior search response.
`logical_search_id`	string	yes	Exact value from the prior search response.

Search Response

{
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "logical_search_id": "ls_abc123",
  "products": [
    {
      "product": {
        "description": "Sony WH-1000XM5 Wireless Noise Canceling Headphones",
        "brand": "Sony",
        "location": "product/f7e2a9c1b3d4",
        "price": 328.0,
        "rating": 4.6,
        "reviews_count": 12450
      },
      "explainer": "Strong noise canceling with long battery life, well suited for travel.",
      "match_grade": "Excellent"
    }
  ],
  "can_fetch_more": true
}

Field	Type	Description
`conversation_id`	string	Stable conversation identifier. Reuse for continue requests and frontend handoff.
`logical_search_id`	string	Identifies this search session for pagination. Reuse for continue requests.
`products`	array	`ProductWithExplainer` objects. May be empty (valid on continue).
`can_fetch_more`	boolean	The only pagination signal. `true` = more results available via continue.

Each

products[]

entry:

Field	Type	Description
`product.description`	string	Product title/description.
`product.brand`	string or null	Brand name if known.
`product.location`	string	Opaque product identifier (format: `product/<cache_key>` ). Preserve exactly for `/agents/product` calls and frontend handoff.
`product.price`	number or null	Price in dollars.
`product.rating`	number or null	Star rating (e.g., 4.6).
`product.reviews_count`	integer or null	Number of customer reviews.
`explainer`	string	Human-readable rationale for the fit grade. May be empty.
`match_grade`	string	Canonical fit label. One of: `"Excellent"` , `"Good"` , `"Partial"` , `"Low"` .

Match Grade Semantics

Grade	Meaning
Excellent	All user requirements confirmed by evidence. All numeric constraints pass.
Good	All critical requirements confirmed, none contraindicated. Constraints pass or pass within tolerance.
Partial	At least one critical requirement is unconfirmed, missing, or contraindicated, OR some numeric constraints fail.
Low	Any requirement is contraindicated, OR no requirements could be evaluated.

Product Endpoint — Deep Analysis

Request

{ "location": "product/<cache_key>" }

Use only a

location

value returned by

/api/agents/search

. Never invent locations. Request model uses

extra = "forbid"

Response

Field	Type	Description
`fmea`	object	Failure Mode and Effects Analysis. See structure below.
`features_summary`	string	Paragraph summarizing key product features.
`reviews_summary`	string	Paragraph synthesizing themes from customer reviews.

FMEA Structure

The

fmea

object describes how a product is likely to disappoint a buyer over time, framed as failure modes rather than feature ratings.

unmitigated_failure_modes

— array, typically 3 entries, ordered by expected regret impact (likelihood x impact x immediacy):

Field	Type	Possible Values
`failure_name`	string	Concise description of what goes wrong.
`likelihood.level`	string	`"low"` , `"medium"` , `"high"`
`likelihood.reasoning`	string	Product-specific probability rationale with expected incidence.
`impact`	string	`"cosmetic"` , `"annoying"` , `"performance_loss"` , `"unusable"`
`timeline`	string	`"immediate"` , `"within_a_year"` , `"over_a_year"`
`summary`	string	1–2 sentences on real-use customer impact.
`evidence`	string[]	Concrete cues from listing, specs, or images.

mitigated_failure_modes

— array, 0–3 entries: common category failures that the product's design intentionally addresses.

Field	Type	Description
`failure_name`	string	The common failure that is unlikely here.
`ownership_experience`	string	Short positive reframe (max ~6 words, e.g., "Long cord with easy rewind").
`reasoning`	string	What design choices reduce this risk.
`evidence`	string[]	Concrete cues from listing.

quality_summary

— string: A calm, informed paragraph synthesizing dominant risks, design priorities, disappointment timeline, fixability, and who the product is likely to satisfy vs. frustrate.

Error Handling

Status	Endpoint	Cause	Suggested Action
`400`	`/agents/product`	Invalid location format (empty, malformed, or contains path separators).	Verify the location was copied verbatim from a search result.
`404`	`/agents/search` (continue)	`logical_search_id` not found or expired from cache.	Start a new search with `type: "new"` .
`404`	`/agents/product`	Product cache key or destination not found. May have expired.	Re-run search to get a fresh location.
`422`	Both	Schema validation failure: missing required field, wrong type, or extra key present.	Fix request body. All request models use `extra = "forbid"` .
`500`	Both	Unhandled internal error.	Retry once with backoff. If persistent, report as a service issue.
`502`	`/agents/search`	Search backend did not return a final result, or returned an invalid payload.	Retry once. If persistent, the upstream search service may be degraded.

Safety Rules

Send JSON request bodies only.
Never include extra fields — all request models use
```
extra = "forbid"
```
and will reject unknown keys with
```
422
```
.
Never invent product locations. Only use
```
location
```
values returned by
```
/api/agents/search
```
.
Preserve
```
conversation_id
```
,
```
logical_search_id
```
, and
```
product.location
```
exactly as returned. Do not trim, modify, or regenerate.
For
```
type: "new"
```
, omit
```
conversation_id
```
to let the server generate one.
All endpoints use the base URL
```
https://hiarthur.com/api
```
.

Frontend Handoff

Open
```
c/<conversation_id>
```
in a browser to resume that conversation within a GUI.
Open a returned product location in a browser to open the product information and see product images in a GUI.
Keep all backend-derived IDs and locations unchanged during handoff URL construction.

Recommended Agent Usage Pattern

Call
```
/agents/search
```
with
```
type: "new"
```
.
Inspect the returned
```
products
```
.
If more candidates are needed, call
```
/agents/search
```
with
```
type: "continue"
```
.
When a specific product requires deeper analysis, call
```
/agents/product
```
.

Skills hiarthur

HiArthur Product Search and Understanding

Overview

When to Use This Skill

Quick-Start: End-to-End Flow

Step 1 — Start a new search

Step 2 — Fetch more results (pagination)

Step 3 — Deep-dive a product

Search Endpoint — Full Field Reference

New Search (
`type: "new"`
)

`search_query`
vs
`trim_query`

Continue Search (
`type: "continue"`
)

Search Response

Match Grade Semantics

Product Endpoint — Deep Analysis

Request

Response

FMEA Structure

Error Handling

Safety Rules

Frontend Handoff

Recommended Agent Usage Pattern

Skills hiarthur

HiArthur Product Search and Understanding

Overview

When to Use This Skill

Quick-Start: End-to-End Flow

Step 1 — Start a new search

Step 2 — Fetch more results (pagination)

Step 3 — Deep-dive a product

Search Endpoint — Full Field Reference

New Search (type: "new")

search_query vs trim_query

Continue Search (type: "continue")

Search Response

Match Grade Semantics

Product Endpoint — Deep Analysis

Request

Response

FMEA Structure

Error Handling

Safety Rules

Frontend Handoff

Recommended Agent Usage Pattern

New Search (
`type: "new"`
)

`search_query`
vs
`trim_query`

Continue Search (
`type: "continue"`
)