A Claude Code skill that turns any SEO technical issue into a developer-ready user story — complete with context, fix instructions, a code example, and acceptance criteria. One line in. Full ticket out.
Install it once and it becomes a /seo-user-story slash command available in every project. Based on the methodology from Sara Taher's How to Communicate SEO Fixes to Developers.
Background
Devs don't dislike SEO requests — they dislike ambiguous, low-value, unexplained ones. The fix is a properly structured SEO user story: a doc that tells the dev what's broken, why it matters, exactly what to change, and how to verify the fix.
This skill automates the drafting. Give it any SEO issue — one sentence is enough — and it produces a complete 9-element user story following the format Sara Taher described in How to Communicate SEO Fixes to Developers.
Claude fills in all the SEO expertise sections — what, why, fix, code example, resources, acceptance criteria — and leaves placeholders only for the site-specific data you need to add yourself: your example URLs, screenshots, and spreadsheet links.
The methodology behind this skill is direct: SEO user stories should be delivered as a Word doc or markdown file, not a PowerPoint. Slides split one fix across multiple slides and are designed for marketing stakeholders — not dev teams. A single doc with all the information in one place is what gets things built.
If your dev team keeps asking clarifying questions or tickets get deprioritized, the user story wasn't precise enough. This skill outputs the first draft — you add your site-specific URLs, then it's ready to send.
What it generates
Every user story Claude produces contains these 9 elements. 7 are generated from your issue alone. 2 are placeholders you fill in with your site data.
A short, specific name for the issue — ready to use as a Jira, Linear, or Notion ticket title.
Claude generates this from your issue description alone. e.g. 'Missing Organization Schema on Homepage' or 'Duplicate Title Tags on Paginated Category Pages'.
A plain-language explanation of the problem, written for a developer who may not have an SEO background.
Avoids unexplained jargon, or defines it on first use. The goal is that a dev can read this and immediately understand what's broken — without needing an SEO to walk them through it.
The SEO and business impact if the issue is left unfixed — crawl budget, rankings, indexation, rich results eligibility, UX.
This is the section devs push back on most when it's missing. It answers 'why should I prioritize this?' so the SEO doesn't have to justify it in a follow-up meeting.
A specific, actionable fix instruction — not a vague goal.
'Add a self-referencing canonical tag to each paginated URL' not 'fix the pagination issue.' Claude writes this as an explicit instruction the dev can act on without interpretation.
A concrete example URL or screenshot showing the problem on your specific website.
Claude leaves a placeholder here — it doesn't know your site URLs. You fill in one or two representative examples before handing the ticket to your dev team.
A spreadsheet or list of all affected pages when the issue impacts more than a handful of URLs.
Placeholder only. Claude notes whether the issue typically affects one page or many, but the actual crawl data is yours to add.
A before/after code snippet or markup example showing exactly what the fix looks like in practice.
For schema issues: a JSON-LD block. For meta tags: the HTML. For hreflang: the full link tag set. Always concrete — a dev should be able to copy this directly.
Links to relevant official documentation — Google Search Central, schema.org, web.dev.
Only real, applicable links. Claude omits this field entirely rather than invent a URL that doesn't exist.
A specific, testable definition of 'correctly fixed' — with a verification tool or method where one exists.
e.g. 'Passes validation in Google's Rich Results Test with no errors' or 'Canonical tag present in page source and matches the page URL.' No subjective pass criteria.
Example
One line in. Here's the complete user story Claude generates.
Input
Output
What is the issue?
The homepage has no Organization structured data markup. Search engines can read the page content, but there is no machine-readable signal explicitly identifying the site's organization name, logo, URL, or social profiles.
Why is this a concern?
Structured data (schema.org markup) is how we communicate entity information directly to search engines in an unambiguous way. Without Organization schema on the homepage:
Organization.logo to display a brand logo in SERPs and the Knowledge Panel.What we want to do about it
Add an Organization schema markup block in JSON-LD format to the <head> of the homepage. At minimum, include:
@type: Organizationname: the site's official organization nameurl: the homepage URLlogo: URL of the organization's logo imagesameAs: array of official social profile URLs (LinkedIn, X/Twitter, Facebook, etc.)Example of the issue on the site
*(Add example URL — this only affects the homepage)*
*(Add screenshot of the page source or a structured data testing tool showing no Organization schema detected)*
Impacted URLs
This affects only the homepage. No spreadsheet needed — just one URL.
Example of how this should be solved
Before: No structured data present in <head>.
After: Add the following JSON-LD block inside <head> on the homepage:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Your Organization Name",
"url": "https://www.yoursite.com",
"logo": "https://www.yoursite.com/images/logo.png",
"sameAs": [
"https://www.linkedin.com/company/your-org",
"https://twitter.com/yourhandle",
"https://www.facebook.com/yourpage"
]
}
</script>Additional resources
Acceptance criteria
Setup
Tips
The skill handles the most common cases by default — but a few small adjustments unlock more.
Paste several issues in a single prompt — Claude produces one complete user story per issue, clearly separated, with a short index at the top.
Ask 'give me a doc I can send to my dev team' and Claude generates a .docx instead. Per the methodology, avoid defaulting to PowerPoint for developer-facing tickets — PowerPoints are for business stakeholders, not devs.
Include your CMS, framework, or URL pattern in the prompt. The more context Claude has about your site's setup, the more specific the 'what to do' and code example sections will be.
The .skill file is a ZIP archive. Extract it to get the SKILL.md inside, edit the output template or instructions, and re-zip. Claude follows whatever you write.
Free. One file. Drop it in your skills folder and it works immediately.