Add rewrite-pdp-copy skill

skills/rewrite-pdp-copy/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: rewrite-pdp-copy
+description: >-
+  Rewrites product detail page copy into a brand's existing PDP template.
+  Accepts the page structure via screenshot or pasted content, then produces
+  section-by-section copy that follows the brand voice and positioning.
+license: Apache-2.0
+---
+
+# Rewrite PDP Copy
+
+This skill takes a brand's existing PDP template and product information and produces rewritten copy that fits exactly into the brand's prescribed sections. It does not invent a new page structure or suggest new sections. It works within what the brand already has.
+
+The skill produces one product at a time. The output is a single document with one section per template slot, ready to paste into a CMS.
+
+For reference on the expected output, see
+[references/example-output.md](references/example-output.md). For the
+principles that guide the rewriting, see
+[references/copy-principles.md](references/copy-principles.md).
+
+## Voice and Approach
+
+You are a copywriter helping an ecommerce team produce better PDP copy. Be direct and practical. The user knows their brand and products better than you do -- your job is to write copy that fits their template, sounds like their brand, and says specific things about the product. Do not narrate your process, explain copywriting theory, or over-qualify your output. When transitioning between steps, keep it brief and natural. Match the user's level of formality.
+
+---
+
+## Conversation Flow
+
+### Turn 1: Collect the PDP Template and Supporting Materials
+
+Ask the user for their PDP template. Explain that a screenshot of an existing PDP or copy-pasted content both work. The skill extracts the section structure from whatever they share.
+
+Also ask whether they have any of these supporting materials, with a brief note on what each one adds:
+
+- Brand voice profile (keeps copy on-brand)
+- Positioning brief (grounds copy in the brand's actual differentiators)
+- Review insights (provides real customer language to draw from)
+- PDP audit (if they want the rewrite to address specific recommendations)
+
+These are recommended, not required. The skill works without them. If the user doesn't have these files but wants to create them, point them to https://skillshelf.ai/skills/ where they can find skills that produce each one.
+
+Accept whatever the user provides. If they share a screenshot, extract the section structure from it. If they paste content, parse the sections from the text. If they describe the sections (without being prompted to), accept that too.
+
+### Turn 2: Confirm the Template Structure
+
+Read back the extracted section structure as a numbered list. For each section, include:
+
+1. The section name (using whatever the brand calls it)
+2. What the section contains (bullets, paragraph, stats, quotes, etc.)
+3. Any visible constraints (approximate character limits, number of bullets, formatting patterns)
+
+If anything is ambiguous (accordion content not visible in a screenshot, unclear hierarchy, sections that could be read multiple ways), surface it here rather than guessing. Ask the user to confirm, rename, add, or remove sections before proceeding.
+
+**Wait for confirmation before proceeding.**
+
+### Turn 3: Collect Product Information
+
+Ask for the product information. The user might provide existing PDP copy (even the copy being rewritten), a spec sheet or brief, a product feed entry, raw notes, or a combination. Let them know that the more specific the input (ingredient details, clinical data, sourcing info, technical specs), the more specific the output.
+
+If the user already provided product information in Turn 1 (e.g., the screenshot or pasted content included both the template and the product details), acknowledge what you have and ask if there's anything else to add. Do not re-ask for what they already shared.
+
+### Turn 4: Produce the Rewritten Copy
+
+Rewrite the PDP copy following the process described in the Analysis and Rewriting Process section. Produce the full document as a downloadable Markdown file using the output structure below.
+
+Invite the user to review section by section and flag anything that needs a different angle, more detail, or a tone adjustment.
+
+### Turn 5+: Revise
+
+Edit individual sections in place when the user requests changes. Do not regenerate the entire document for a single correction.
+
+## Analysis and Rewriting Process
+
+Before writing, read [references/copy-principles.md](references/copy-principles.md).
+
+### Step 1: Classify each section
+
+For each section in the confirmed template, classify it:
+
+- **Rewrite sections** -- Sections where the skill writes new copy (descriptions, benefits, feature explanations, usage instructions, FAQs). These get the full rewriting treatment.
+- **Carry-through sections** -- Sections with regulated data, clinical results, certifications, ingredient claims, efficacy stats, or sourced quotes. Carry the data through unchanged. Improve surrounding copy (framing, transitions, formatting) but never alter the claims, percentages, stat language, or attributed quotes themselves.
+- **Placeholder sections** -- Sections where the product information provided is insufficient to write anything credible. Mark these with what's needed and move on.
+
+### Step 2: Apply the brand voice
+
+If a brand voice profile is provided, read it before writing and follow it throughout. Pay particular attention to:
+
+- The "What [Brand] Avoids" section -- these are hard constraints
+- The "Style Decisions" table -- specific binary rules that override general guidance
+- The voice summary and persuasion arc -- for overall character and structure
+
+If no brand voice profile is provided, examine the existing PDP copy (from the template screenshot or pasted content) and match its voice as closely as possible. Note in the output that a brand voice profile would improve consistency across PDPs.
+
+### Step 3: Apply the positioning
+
+If a positioning brief is provided, use it to anchor the copy in the brand's actual differentiators. When describing what a product does or why it matters, frame it through the lens of the brand's positioning rather than generic category language.
+
+If no positioning brief is provided, work from whatever brand context is visible in the template and product data. Do not invent positioning.
+
+### Step 4: Rewrite each section
+
+For each rewrite section, follow the principles in [references/copy-principles.md](references/copy-principles.md). Beyond the table stakes, two things separate good PDP copy from adequate PDP copy:
+
+1. **Specificity.** Look for places where the copy says something generic that could apply to any product in the category, and replace it with something specific to this product -- an ingredient, a mechanism, an outcome, a use case. Not every sentence needs to be unique, but the copy overall should make clear why this product is this product and not a competitor.
+
+2. **Decision-driving details are easy to find.** The information that helps someone decide whether this product is right for them should be near the top of each section, not buried under preamble. This doesn't mean every section leads with specs. A benefits section might lead with an outcome. A usage section might lead with the scenario. The principle is: don't make the shopper dig for the thing that matters most.
+
+When review insights are available, use customer language to inform copy -- particularly for benefits sections, FAQ answers, and usage descriptions. Customers often describe products in more concrete terms than marketing teams do. Do not fabricate customer quotes or attribute language to customers that didn't come from the review data.
+
+### Step 5: Self-check
+
+Before producing the final document, check every section against the table stakes:
+
+1. Does it follow the brand voice? Read it next to the voice profile (or existing copy). If it sounds like a different brand, rewrite.
+2. Is it aware of the brand positioning? Does it frame the product through the brand's lens, not generic category language?
+3. Does it follow the template structure exactly? Same sections, same format, same constraints.
+4. Does it make anything up? Every claim must trace to the product data, existing PDP copy, or review insights. If you can't source it, cut it.
+
+## Output Structure
+
+The output document follows this format:
+
+```
+# PDP Copy: [Product Name]
+
+**Template source:** [What the user provided -- screenshot, pasted content, etc.]
+**Product source:** [What product data was provided]
+**Supporting inputs:** [List any upstream skill outputs used, or "None"]
+
+---
+
+## [Section Name 1]
+
+[Rewritten copy, matching the format and constraints of the template section]
+
+## [Section Name 2]
+
+[Rewritten copy]
+
+...
+
+## Carry-Through Sections
+
+### [Section Name]
+
+[Original data preserved. Any copy improvements to framing or transitions are marked with inline comments.]
+
+---
+
+## Notes
+
+### Confidence Notes
+[Sections where the input was thin. What additional information would strengthen the copy.]
+
+### Placeholder Sections
+[Sections that could not be written due to missing information. What's needed.]
+
+### Recommendations
+[Optional. If the rewrite surfaced obvious template-level issues -- a section that doesn't serve the customer, a missing section that would help -- note them briefly. This is not an audit; keep it to observations that came up naturally during the rewrite.]
+```
+
+Section names in the output must match exactly what the brand calls them, not generic names.
+
+## Edge Cases
+
+### No brand voice profile provided
+
+Examine the existing PDP copy from the template and match its tone. Note at the top of the output that no voice profile was provided and that creating one would improve consistency across products. Point the user to https://skillshelf.ai/skills/ if they're interested.
+
+### No positioning brief provided
+
+Work from whatever brand context is available in the template, product data, and any other materials shared. Do not fabricate positioning. If the copy would benefit from clearer positioning, note it in the Recommendations section.
+
+### Sections with regulated or sourced data
+
+Clinical results, certifications, ingredient claims, efficacy percentages, attributed quotes. Carry the data through unchanged. Improve framing and surrounding copy, but never alter the claims themselves. If the user didn't provide the original data for these sections, leave them as placeholders and flag what's needed.
+
+### Template sections that don't apply to the product
+
+If a template section doesn't apply (e.g., "Scent profile" for an unscented product, "Clinical results" for a product without trials), flag it in the confirmation step (Turn 2). Suggest what could go there instead, or recommend leaving it empty. Do not fill it with invented content.
+
+### Thin product data
+
+Write what you can. Flag sections where you're working from limited information in the Confidence Notes. Be specific about what's missing: "The benefits section would be stronger with ingredient concentrations or mechanism-of-action details" is useful. "More product information would help" is not.
+
+### Conflicting information between sources
+
+If the product data says one thing and the existing PDP copy says another (e.g., different ingredient lists, conflicting claims), flag the conflict in the output. Do not silently pick one version. Let the user resolve it.
+
+### Template with many sections
+
+Some PDPs have 10+ content sections. Produce all of them. Do not summarize or skip sections to save space. The user needs copy for every slot in their CMS.
+
+## Closing
+
+Once the user approves the copy, let them know they can paste it directly into their CMS section by section. If they plan to rewrite more PDPs, suggest starting a new conversation with the same template, brand voice profile, and positioning brief -- they only need to provide new product data each time.

skills/rewrite-pdp-copy/references/copy-principles.md

@@ -0,0 +1,116 @@
+# PDP Copy Principles
+
+This reference file defines what "better" means when rewriting PDP copy. It is organized into two tiers: table stakes (the copy must clear these or it has failed) and what makes it good (these separate strong copy from adequate copy).
+
+Read this file before rewriting. Use it as a self-check after drafting.
+
+---
+
+## Table Stakes
+
+These are pass/fail. If the rewritten copy fails on any of these, the quality of everything else is irrelevant.
+
+### 1. Follows the brand voice
+
+The copy should sound like it was written by the brand's team, not by an AI or a generic copywriter. This means matching the brand's tone, sentence structure, vocabulary, and personality.
+
+When a brand voice profile is available, follow it -- especially the avoidance rules and style decisions, which are the most concrete constraints. When no voice profile is available, study the existing PDP copy and match its patterns.
+
+Common failures:
+- Introducing superlatives or hype the brand doesn't use ("revolutionary," "game-changing," "ultimate")
+- Shifting register (the brand writes casually but the rewrite sounds formal, or vice versa)
+- Using filler phrases that sound like AI output ("whether you're a... or a...," "designed to help you," "take your X to the next level")
+- Smoothing out personality or quirks that make the brand's voice distinctive
+
+### 2. Aware of the brand positioning
+
+The copy should frame the product through the lens of what the brand stands for, not through generic category language. Two skincare brands might sell similar serums, but one positions around clinical efficacy and the other around clean ingredients and ritual. The copy should reflect that difference.
+
+When a positioning brief is available, use it to guide how you describe what the product does and why it matters. When no brief is available, infer positioning from whatever brand context is visible (the template itself often reveals a lot about how the brand thinks about its products).
+
+Common failures:
+- Writing category-generic copy that could appear on any brand's site
+- Emphasizing attributes the brand doesn't lead with (e.g., writing performance-first copy for a brand that leads with sustainability)
+- Contradicting the brand's positioning by introducing framing the brand wouldn't use
+
+### 3. Follows the structure of the page
+
+The rewritten copy must fit exactly into the brand's prescribed template sections. Same section names, same format (bullets vs. paragraphs vs. stat blocks), same approximate length, same constraints.
+
+This is not about being rigid for rigidity's sake. PDP templates exist because the ecomm team needs to paste copy into a CMS with defined content slots. If the rewrite doesn't fit the slots, it doesn't ship.
+
+Common failures:
+- Writing a paragraph where the template expects bullets
+- Ignoring visible character or word count constraints
+- Merging or splitting sections the template keeps separate
+- Renaming sections to generic labels ("Key Benefits" when the brand calls it "Why you'll love it")
+
+### 4. Doesn't make things up
+
+Every claim in the copy must trace back to the product data, existing PDP copy, or review insights the user provided. If you can't source a claim, don't include it.
+
+This is especially important for:
+- Ingredient claims and mechanisms of action
+- Efficacy stats and clinical results (carry through unchanged)
+- Sourcing, certifications, and regulatory statements
+- Customer quotes or attributed language
+- Specific outcomes ("reduces fine lines in 4 weeks") -- only include if the data supports it
+
+When the product data is thin, write what you can support and flag the gaps. Confident-sounding copy built on guesses is worse than shorter copy built on facts.
+
+Common failures:
+- Inventing ingredient benefits or mechanisms not in the product data
+- Upgrading vague claims to specific ones without evidence ("helps with hydration" becoming "boosts hydration by 40%")
+- Adding customer-language phrasing that didn't come from actual reviews
+- Filling thin sections with plausible-sounding but unsourced claims
+
+---
+
+## What Makes It Good
+
+These are the difference between copy that clears the bar and copy that's worth using. They won't save bad copy, but they're what make good copy noticeably better.
+
+### 5. Specific to this product
+
+Strong PDP copy says things that are true of this product and not easily interchangeable with a competitor in the same category. This comes from working the product data hard -- pulling out specific ingredients, mechanisms, use cases, materials, sourcing details, or customer outcomes rather than defaulting to category-level language.
+
+Not every sentence needs to be unique to the product. Some things are category-standard and fine to state plainly ("apply to clean skin"). But the copy overall should leave no doubt about what makes this product this product.
+
+Where to push for specificity:
+- Hero descriptions: What does this product actually do, specifically? Not "nourishes your skin" but the specific mechanism or ingredient story.
+- Benefits sections: What outcomes can the customer expect, and why? Tie benefits to specific product attributes when possible.
+- Ingredient callouts: What does this ingredient do in this formulation, not just in general?
+- Usage instructions: What's the specific context, routine, or scenario where this product fits?
+
+Where specificity matters less:
+- Regulatory boilerplate
+- Standard usage instructions that are genuinely universal ("shake well before use")
+- Section headers and navigation labels
+
+When review insights are available, they're one of the best sources of specificity. Customers describe products in concrete terms that marketing copy often abstracts away. Use their language to inform (not replace) the copy.
+
+### 6. Decision-driving details are easy to find
+
+The job of PDP copy is to help the shopper decide whether this product is right for them. The information that drives that decision should be easy to find, not buried.
+
+What "drives the decision" depends on the product and the section. For a $60 serum, it might be what skin concern it addresses and how it works. For a hiking boot, it might be waterproof rating and intended terrain. For a coffee subscription, it might be roast profile and origin. The skill should identify the decision-driving details for this specific product and make sure they're prominent.
+
+This doesn't mean every section leads with specs. Different sections have different jobs:
+- A hero description might lead with the core benefit or use case
+- A benefits section might lead with outcomes
+- A usage section might lead with the scenario or routine it fits into
+- An FAQ might lead with the most common concern
+
+The principle is consistent across sections: put the most useful information where the shopper encounters it first within each section. Don't make them read through preamble to find what they need.
+
+Research supports this. Baymard Institute found that structuring descriptions with a scannable highlights layer before deeper detail increases engagement, because shoppers can quickly validate decision-critical attributes. (Baymard Institute, "Structuring Product Page Descriptions by 'Highlights' Increases User Engagement (Yet 78% of Sites Don't)," 2018). Nielsen Norman Group found that descriptions should answer real customer questions rather than lead with marketing fluff, since users skim and concentrate on the first lines. (Nielsen Norman Group, "UX Guidelines for Ecommerce Product Pages," 2019).
+
+---
+
+## Using These Principles
+
+These six principles are ordered by priority. When they conflict, higher-numbered principles yield to lower-numbered ones.
+
+For example: if making the copy more specific (principle 5) would require inventing a claim not in the product data, principle 4 (don't make things up) wins. If restructuring a section to surface decision-driving details (principle 6) would break the template format, principle 3 (follow the structure) wins.
+
+The table stakes (1-4) are non-negotiable. Principles 5 and 6 are where the skill adds the most value, but only within the constraints the table stakes set.