Add extract-review-insights skill

skills/extract-review-insights/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: extract-review-insights
+description: >-
+  Extracts patterns from customer reviews: what they like, dislike, useful
+  language, and which product claims hold up.
+license: Apache-2.0
+---
+
+# Extract Review Insights
+
+This skill reads customer reviews for one product and pulls out the patterns
+that matter: what customers consistently like, what they consistently dislike,
+the specific language they use, and whether the reviews support or undercut
+the product's marketing claims.
+
+The skill works from the reviews only. It does not invent themes, fabricate
+customer segments, estimate counts beyond what the data shows, or guess at
+root causes. When evidence is thin or mixed, it says so.
+
+For reference on the expected output, see
+[references/example-output.md](references/example-output.md).
+
+## Voice and Approach
+
+Be direct and concise. Report what the reviews say without editorializing.
+Use plain language. Do not narrate your internal process or over-explain
+your methodology. When transitioning between steps, keep it brief and
+natural. The user wants the analysis, not a walkthrough of how you arrived
+at it.
+
+## Conversation Flow
+
+### Turn 1: Collect Reviews
+
+The skill needs reviews for one product. Accept any format: pasted text,
+CSV export (Shopify, Yotpo, Bazaarvoice, PowerReviews, Judge.me, Stamped,
+or similar), or a document (PDF, Word, text file).
+
+Optionally, the user may also provide:
+
+- Product/brand name
+- Product data (feed entry, PDP content, or product description) -- this
+  gives the skill concrete claims and features to check reviews against
+- Review metadata (star ratings, dates, verified purchase flags)
+
+Let the user know what you need and what's optional. Don't over-explain
+the process.
+
+### Turn 2: Clarify (if needed)
+
+Only ask follow-up questions if something is genuinely ambiguous:
+
+- CSV columns aren't obvious (which column is the review body?)
+- Reviews appear to cover multiple products
+- Something else prevents you from starting
+
+If everything is clear, skip this turn and go straight to the analysis.
+
+### Turn 3: Deliver the Analysis
+
+Produce the full analysis as a Markdown document using the output structure
+below. Offer to adjust groupings, go deeper on a theme, or reframe
+anything.
+
+### Turn 4+: Revise
+
+Edit individual sections in place. Do not regenerate the entire document
+for a single correction.
+
+## Analysis Instructions
+
+### Core principles
+
+- **Use only what the reviews say.** Every insight must trace back to
+  specific reviews. Do not infer themes that aren't explicitly stated or
+  clearly implied by multiple reviewers.
+- **Focus on repetition.** A single reviewer's opinion is an anecdote. A
+  pattern appears when multiple reviewers independently say the same thing.
+  Note when a theme appears in many reviews vs. a few.
+- **Report the evidence, not the cause.** If customers say the zipper
+  breaks, report that. Do not speculate on why the zipper breaks.
+- **Be honest about weak evidence.** If only 2-3 reviews mention something,
+  say so. If reviews contradict each other on a point, report the split.
+  Do not smooth over mixed signals to make the analysis feel cleaner.
+- **Preserve customer language.** When quoting or paraphrasing, stay close
+  to the words customers actually used. Their phrasing is often more useful
+  than a polished summary.
+
+### How to identify themes
+
+1. Read all reviews. Note every distinct positive and negative point.
+2. Group points that describe the same thing, even when worded differently.
+   "Runs small," "had to size up," and "tight through the shoulders" are
+   the same theme (sizing).
+3. Count how many reviews touch each theme. Use plain language for
+   frequency: "mentioned in many reviews," "a few reviewers noted," "one
+   reviewer mentioned." Do not fabricate exact counts unless you can
+   actually count them accurately from the data.
+4. Rank themes by frequency. Lead each section with the most-repeated
+   patterns.
+
+### How to handle product data
+
+When product data (feed entry or PDP content) is provided:
+
+- Extract the product's stated claims, features, and selling points.
+- In the Claims Supported / Claims to Be Careful With section,
+  cross-reference each claim against what reviewers actually say.
+- A claim is "supported" when multiple reviewers independently confirm it.
+- A claim needs caution when reviewers contradict it, when evidence is
+  mixed, or when no reviewers mention it at all (absence is worth noting
+  but is not contradiction).
+
+When no product data is provided:
+
+- Work from claims implied in the reviews themselves (e.g., if many
+  reviewers say "this is waterproof," treat waterproofness as an implied
+  claim).
+- Note in the Claims section that you're working without the brand's own
+  product data and that providing it would strengthen the analysis.
+
+## Output Structure
+
+```
+# Review Insights: [Product Name]
+
+## Overview
+[Product name, review count, rating distribution if metadata is available.
+One paragraph summarizing the overall picture: what the dominant sentiment
+is and what the key takeaways are. Keep it to 3-5 sentences.]
+
+## What Customers Like
+[Grouped by theme, ordered by frequency. Each theme gets a short heading,
+a plain-language description of what reviewers say, and a note on how
+common the theme is. Include short review snippets only when they add
+something the summary doesn't. Do not list every positive comment --
+group and summarize.]
+
+## What Customers Don't Like
+[Same structure as above. If a negative theme is minor or mentioned by
+very few reviewers, say so. If a theme has mixed signals (some love it,
+some don't), note the split.]
+
+## Useful Customer Language
+[Specific words, phrases, and descriptions customers use that are worth
+borrowing for product copy, PDP content, ads, or email. Group by theme
+if helpful. These should be the customers' actual words, not polished
+marketing rewrites.]
+
+## Claims Supported / Claims to Be Careful With
+[If product data provided: cross-reference each identifiable claim against
+review evidence. If no product data: work from claims implied in the
+reviews. For each claim, note whether it's supported, contradicted, mixed,
+or not mentioned. Be specific about the evidence.]
+
+## Confidence Notes
+[Flag which parts of the analysis are based on strong patterns (many
+reviews, consistent signal) and which are based on thin evidence (few
+reviews, mixed signals). If the review set is small, note that the
+analysis may not be representative.]
+```
+
+## Important Behaviors
+
+- Produce the analysis as a single Markdown document.
+- Use the product name in the document title. If no product name is
+  provided, use "Untitled Product" and ask the user to confirm.
+- When quoting customer reviews, use their actual words. Do not clean up
+  grammar or rephrase unless the original is unintelligible.
+- When editing, change only the requested section.
+
+## Edge Cases
+
+### Small review set (fewer than 10 reviews)
+
+Produce the analysis but shorten it. With fewer than 10 reviews, most
+"themes" are really just individual opinions. Note this prominently in the
+Confidence Notes section: "This analysis is based on N reviews. Patterns
+identified here may not hold across a larger sample." Keep What Customers
+Like and What Customers Don't Like to the points that appear more than
+once.
+
+### Large review set (more than 500 reviews)
+
+Use up to 500 reviews, prioritizing the most recent when dates are
+available. Let the user know how many reviews were included and that
+older reviews were excluded. If the user wants to focus on a specific
+time period or segment instead, offer to re-run with a different subset.
+
+### Mixed or contradictory reviews
+
+When reviewers disagree on the same point (e.g., half say it runs large,
+half say it fits true to size), report the split. Do not average
+conflicting opinions into a lukewarm summary. Note the disagreement and,
+if possible, note whether different reviewer contexts (use case, body type,
+expectations) explain the split.
+
+### Reviews with no clear patterns
+
+If the reviews are all over the place with no repeated themes, say so.
+Produce the analysis with whatever individual points are most notable, but
+be clear in Confidence Notes that no strong patterns emerged. This is a
+valid finding, not a failure.
+
+### CSV with unexpected columns
+
+If the CSV doesn't have obvious review body, rating, or date columns, ask
+the user which columns to use. Common column names to look for: "Review
+Body," "Review Text," "Comment," "Content," "Body," "review_body,"
+"review_text." For ratings: "Rating," "Stars," "Score," "review_rating."
+
+### Reviews in multiple languages
+
+If reviews are in multiple languages, analyze all of them but note which
+language each quoted review is in. If translation is needed for the user
+to understand a quote, provide it in brackets.
+
+## Closing
+
+Provide the analysis as a Markdown document. Let the user know a few ways
+the output might be useful: the Useful Customer Language section is good
+raw material for PDP copy and ad creative, the Claims section can inform
+how confidently a product page leans into specific features, and the
+Likes/Dislikes sections can surface product improvement opportunities or
+FAQ content.

skills/extract-review-insights/references/example-output.md

@@ -0,0 +1,76 @@
+# Review Insights: Cascade Rain Shell - Men's
+
+## Overview
+
+**Product:** Cascade Rain Shell - Men's (Great Outdoors Co.)
+**Reviews analyzed:** 20
+**Rating distribution:** 14 five-star, 3 four-star, 1 three-star, 1 two-star, 1 one-star
+
+The Cascade Rain Shell is well-liked overall. The dominant pattern is that customers buy it as a step up from cheap rain jackets and are satisfied with the upgrade. Waterproofing, comfort, and durability over multiple seasons come up repeatedly. The main friction points are fit (runs large for slimmer builds) and pocket placement that conflicts with backpack hip belts. A small number of reviewers report waterproofing issues, though most describe the jacket holding up well over time.
+
+## What Customers Like
+
+### Waterproofing that holds up
+
+The most common positive theme. Reviewers describe staying dry in sustained rain, including multi-hour hikes. Several mention the jacket performing well across multiple seasons, with water still beading after repeated washing. One reviewer described it as "still beads water like day one" after two seasons.
+
+### A reliable upgrade from cheap rain gear
+
+Many reviewers frame the purchase as replacing a cheaper jacket that failed. The $149 price point comes up as a value -- not cheap, but worth it compared to burning through a $40 jacket every year.
+
+### Comfortable enough for everyday use
+
+Reviewers describe wearing it for dog walks, commutes, and daily use from fall through spring. The fabric being quiet (no loud swishing) and lightweight enough to pack down into a daypack are mentioned as reasons it gets grabbed often.
+
+### Breathability is adequate for the price
+
+Pit zips get specific praise. A few reviewers note some clamminess on steep uphills but describe it as a fair tradeoff at this price. Nobody describes breathability as a serious problem.
+
+## What Customers Don't Like
+
+### Runs large, especially for slim builds
+
+The most repeated negative. Multiple reviewers describe the fit as roomier than expected, with one noting even the small was "way too roomy" at 5'8" and 145 lbs. Others find the extra room fine for layering a fleece. This is a split: the fit works for people who layer, but not for slim builds or people who want a closer fit.
+
+### Pocket placement conflicts with hip belts
+
+A few reviewers note the hand pockets sit exactly where a backpack hip belt goes, making them unusable on the trail. One reviewer specifically asked for a chest pocket. This is a design issue for hikers carrying packs.
+
+### Waterproofing durability (isolated reports)
+
+One reviewer reported shoulder seams leaking on the third wear (likely defective -- returned it). Another described waterproofing fading after three months of regular weekend use, partially restored by washing and drying per care instructions. These are a small minority against many positive waterproofing reports, but worth noting.
+
+### Stiff zipper out of the box
+
+One reviewer noted the main zipper was stiff and hard to operate with cold hands when new, but improved with use. Only mentioned once.
+
+## Useful Customer Language
+
+**Describing the purchase decision:** "finally done replacing cheap rain jackets," "should have spent the $149 a long time ago," "the jacket I grab without thinking about it"
+
+**Describing performance:** "beads water like day one," "completely dry after a two-hour hike in steady rain," "survived a full day of rain in Vermont," "don't overheat on the uphill"
+
+**Describing everyday use:** "I wear this almost every day from October through April," "packs down small enough to shove in my daypack," "this is all the rain jacket most people need"
+
+**Describing the fabric:** "doesn't make that loud swishing sound," "soft and quiet"
+
+## Claims Supported / Claims to Be Careful With
+
+Product data was provided (PDP content for the Cascade Rain Shell).
+
+**Supported by reviews:**
+
+- *Waterproof/breathable fabric with fully taped seams* -- Strongly supported. Most reviewers confirm staying dry in sustained rain. Two isolated reports of seam or waterproofing issues do not undermine the pattern.
+- *Pit zips for quick venting* -- Supported. Multiple reviewers specifically mention pit zips helping with heat management.
+- *Packs into its own pocket* -- Supported. Several reviewers describe packing it into a daypack easily.
+- *Quiet fabric* -- Supported. Mentioned by name as a differentiator by at least one reviewer, implicitly confirmed by others describing comfort.
+- *PFAS-free DWR finish* -- Not mentioned by any reviewer. Neither confirmed nor contradicted.
+
+**Be careful with:**
+
+- *Two hand pockets sit above a hipbelt or harness* -- The PDP claims pockets are positioned above a hip belt. Multiple reviewers contradict this, saying pockets sit right where the hip belt goes. This claim may not match the men's version, or the pocket placement may not work for all pack styles.
+- *Regular fit (room for a light midlayer)* -- Reviewers consistently describe the fit as generous or boxy, not just "room for a midlayer." The sizing note to "size up for layering" may lead to an overly large fit for some customers. Several reviewers suggest sizing down.
+
+## Confidence Notes
+
+This analysis is based on 20 reviews, which is enough to identify the strongest patterns (waterproofing, fit, everyday comfort) but not enough to draw firm conclusions on less-mentioned topics. The waterproofing durability complaints (2 out of 20) could be isolated incidents or early signs of a broader issue -- a larger review set would clarify. The pocket placement conflict with hip belts appears in a few reviews and is worth investigating but shouldn't be treated as a universal problem from this sample size alone.

skills/extract-review-insights/skillshelf.yaml

@@ -0,0 +1,34 @@
+version: "1.0"
+category: customer-research
+level: intermediate
+primitive: false
+certified: true
+platforms:
+  - platform-agnostic
+tags:
+  - reviews
+  - voice-of-customer
+  - product-insights
+  - customer-language
+  - claim-validation
+
+author:
+  name: Tim Petrella
+  url: https://www.linkedin.com/in/timpetrella/
+
+faq:
+  - question: How many reviews does this skill need to be useful?
+    answer: >-
+      It works with any number, but patterns are more reliable with 15+
+      reviews. With fewer than 10, the analysis will flag that most findings
+      are individual opinions rather than trends.
+  - question: What review formats does it accept?
+    answer: >-
+      Pasted text, CSV exports from common review platforms (Yotpo,
+      Bazaarvoice, PowerReviews, Judge.me, Stamped, Shopify), or documents
+      (PDF, Word, text files).
+  - question: Do I need to provide product data?
+    answer: >-
+      No. Product data (a feed entry or PDP content) is optional but
+      strengthens the Claims section by giving the skill specific claims
+      and features to check reviews against.