diff --git a/README.md b/README.md index 0290e0f..f271555 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,10 @@ can reference individual files. Skills should be small, self-contained, and safe to share between tools. Avoid tool-specific assumptions where a generic approach will do. +For a broad topic, prefer one skill whose `SKILL.md` acts as a router. The router +maps the request to a playbook under `files/`, and the agent loads only that part. +`seo` and `marketing` follow this shape. + ## Attributions Most skills are adapted from open-source collections. Where a skill was renamed, @@ -76,3 +80,5 @@ Each skill's text is upstream apart from local adaptation: renamed frontmatter, reference docs moved under `files/`, path fixes, and dropped tool-specific metadata (`agents/openai.yaml`, authoring-only `evals/`). Skills not listed here were added before this section existed. + +The `seo` and `marketing` skills are written for this repo, not imported. diff --git a/skills/marketing/SKILL.md b/skills/marketing/SKILL.md new file mode 100644 index 0000000..d400a4c --- /dev/null +++ b/skills/marketing/SKILL.md @@ -0,0 +1,54 @@ +--- +name: marketing +description: Research markets, plan marketing content, and write the pieces. Use for audience and competitor research, positioning, content strategy, editorial calendars, campaign and launch plans, landing pages, emails, ads, social posts, case studies, and any marketing copy that has to ship. Router that sends each job to a focused playbook in this folder. +--- + +# Marketing + +Router. Pick the playbook, then work through it. Paths below are relative to this skill folder. Research feeds the plan, the plan feeds the brief, the brief feeds the draft. Do not skip straight to writing when the inputs are missing. + +## Route + +| The user wants | Read | +| --- | --- | +| Market, audience, competitor, or positioning research | `files/research.md` | +| A content plan, calendar, funnel map, campaign, or launch plan | `files/plan.md` | +| The actual piece: page, email, ad, post, case study, one-pager | `files/write.md` | +| A review of a draft before it goes out | `files/review.md` | +| Search-led content | Read the `seo` skill first, then its `files/reference/content.md` and `files/reference/on-page.md` | + +Typical flow: `files/research.md` -> `files/plan.md` -> `files/write.md` -> `files/review.md`. Small requests start at the file that answers them. + +## Rules + +- One audience, one problem, one promise per piece. If a draft has two, split it. +- Evidence over adjectives. A claim needs a source, a customer quote, a measurement, or a real example. +- If proof is missing, write without it. Never invent customers, numbers, logos, or reviews. +- Use the reader's words. Pull them from support tickets, reviews, calls, and forums, not from a brainstorming session. +- Specific beats clever. A clear sentence that names the thing wins. +- Every piece ends with one next action. +- No em dashes and no semicolons in shipped copy. Plain ASCII quotes. +- Before delivery, apply the `unslop` skill. For interface or landing page copy, also apply `antislop-copywriting`. +- Ask for missing inputs in one short batch. Do not run an interview across ten messages. + +## Inputs to collect + +Ask only for what the work needs, and only what you cannot find in the repo, the site, or the user's own material. + +1. Audience and what they are trying to do. +2. Offer, price, and how it is bought. +3. Goal and the metric that shows success. +4. Channel and format. +5. Proof assets: customers, data, demos, screenshots, testimonials. +6. Deadline, owner, and approval path. + +## Deliverables + +Save where the repo keeps marketing work. With no convention, use `marketing/` and say where the files went. + +- `marketing/research--.md` +- `marketing/plan--.md` +- `marketing/brief-.md` +- `marketing/content/.md` + +Each deliverable opens with the inputs it was built from, so the next person can check the reasoning. diff --git a/skills/marketing/files/plan.md b/skills/marketing/files/plan.md new file mode 100644 index 0000000..229cf76 --- /dev/null +++ b/skills/marketing/files/plan.md @@ -0,0 +1,149 @@ +# Content planning + +**Use when:** the user wants a content strategy, editorial calendar, campaign plan, launch plan, funnel map, or a decision about what to publish next. +**Produces:** a plan with one goal, a fixed set of formats, owners, dates, and a measurement method. +**Loads:** `files/research.md` output when it exists. For search-led programs, also read the `seo` skill, `files/reference/content.md`. + +## Inputs + +- Goal and metric, from the business side, not "more traffic". +- Audience and segment, from research or the user. +- Offer, price, and sales motion. +- Channels with real access and capacity. +- Proof assets that exist today. +- Team and budget. A plan that needs people who are not there is fiction. +- Time horizon: launch, quarter, or year. + +## Step 1: one goal + +Write it as a metric and a date: "40 qualified demo requests from organic and email by March 31". + +Then name the constraint: the thing most likely to stop it. Budget, proof, traffic, sales follow-up. The plan should attack the constraint, not the easy work. + +## Step 2: map the funnel + +| Stage | The audience is | Content that helps | Metric | +| --- | --- | --- | --- | +| Problem aware | Feeling the pain, no solution named | Explainers, teardown posts, comparison framing | Reach, engaged sessions | +| Solution aware | Comparing approaches | Guides, templates, webinars, calculators | Email signups, return visits | +| Vendor aware | Comparing products | Case studies, demos, pricing explainers, migrations | Demo requests, trials | +| Ready | Choosing now | Onboarding content, security docs, proof, offers | Conversion rate | +| Customer | Using it | Adoption guides, release notes, community | Retention, expansion | + +A plan that only produces top-of-funnel posts will show traffic and no pipeline. Say so when that is what is being asked for. + +## Step 3: choose the pillars + +Three to five pillars, each tied to a buyer question. Not to internal teams. + +For each pillar: + +- The question it answers. +- The buyer stage. +- The proof we have. +- The search demand, if search matters. +- The owner. +- The format that fits. + +Kill pillars with no proof and no access to the audience. They become filler. + +## Step 4: pick formats by job + +| Format | Good for | Cost | Lifespan | +| --- | --- | --- | --- | +| Long guide | Search demand, deep problem | High | Long, refresh yearly | +| Teardown or comparison | Solution and vendor stage | Medium | Medium | +| Case study | Proof, sales enablement | Medium, needs a customer | Long | +| Demo video or recording | Product clarity | Medium | Medium | +| Newsletter | Relationship, repeat reach | Low per issue, high ongoing | Short per issue | +| Landing page | One offer, one audience | Medium | Long, needs testing | +| Paid ad | Demand capture, message test | Low to produce, costly to run | Short | +| Social post | Distribution, point of view | Low | Hours | +| Webinar or live session | Trust, complex products | High | Medium | +| Docs and templates | Utility, links, search | Medium | Long | + +One strong asset beats five thin ones. Repurpose deliberately: a guide becomes a newsletter issue, a set of posts, and a sales one-pager. + +## Step 5: calendar + +- Work backward from the launch or campaign date. +- One primary asset per week at most for a small team. Two per month is a real cadence. +- Leave 20 percent of slots open for reactive work. +- Group by pillar, not by channel, so a single idea ships across formats. +- Mark dependencies: design, review, customer approval, legal. +- Mark owners by name or role. + +```markdown +| Date | Pillar | Working title | Format | Funnel stage | Owner | Proof needed | Status | +| --- | --- | --- | --- | --- | --- | --- | --- | +``` + +## Step 6: briefs + +Every planned asset gets a brief before writing. Use the brief template in the `seo` skill, `files/reference/content.md`, or this short version: + +```markdown +# Brief: + +- Audience and stage: +- One promise: +- Proof available: +- What the reader does next: +- Format, length, channel: +- Angle only we can take: +- Sources to cite: +- Owner and due date: +``` + +## Step 7: distribution + +Publishing is not distribution. For each asset, name: + +- Owned: email list, site, docs, in-product. +- Earned: communities, partners, newsletters, press. +- Paid: only after the message works organically. +- Sales: which assets go to which stage of the deal. + +If an asset has no distribution path, cut it from the plan. + +## Step 8: measurement + +- One primary metric for the program. +- One metric per stage, so a break is visible. +- A review date, not an ongoing dashboard. +- A decision rule: continue, change, or stop. Write it before the results arrive. + +Example: "If the guide does not produce 15 email signups per month after two months, we revise the offer or replace the topic." + +## Plan format + +Write `marketing/plan--.md`: + +1. Goal, metric, date, constraint. +2. Audience and stage focus. +3. Pillars with the buyer question each answers. +4. Format mix and why. +5. Calendar table. +6. Briefs, or the rule for writing them. +7. Distribution per asset. +8. Measurement and decision rule. +9. Risks: proof gaps, capacity, approvals, seasonality. + +## Launch plans + +For a launch, add: + +- The one-sentence announcement. +- Who needs to know, in what order: team, customers, partners, press, public. +- Assets by day: page, email, post, demo, docs. +- The ask for each audience. +- A rollback or hold point if the first day goes wrong. + +## Checks before delivery + +- The plan has one goal and one metric. +- Every item has an owner, a date, and a proof source. +- Formats match the audience and stage. +- Distribution is named for each asset. +- The decision rule is written. +- Nothing in the plan depends on people or proof that do not exist. diff --git a/skills/marketing/files/research.md b/skills/marketing/files/research.md new file mode 100644 index 0000000..5f6d4f2 --- /dev/null +++ b/skills/marketing/files/research.md @@ -0,0 +1,114 @@ +# Market research + +**Use when:** the user needs to understand a market, audience, competitor set, or positioning before planning or writing. +**Produces:** a research document that ends in decisions, not a data dump. +**Feeds:** `files/plan.md` and `files/write.md`. Search demand work also loads the `seo` skill. + +## Start with the decision + +Write one sentence first: what decision will this research change? + +Examples: + +- Which segment do we target first? +- Which message leads the homepage? +- Which two competitors define the category, and where are they weak? +- Is this market already crowded around one promise? + +Research with no decision attached turns into a link list. If the user cannot name the decision, propose one and confirm it. + +## Sources, in order of trust + +1. **Own data:** sales calls, support tickets, churn reasons, onboarding drop-off, search queries, email replies. +2. **Primary conversations:** five to ten interviews with real buyers beat any report. Ask what they did, not what they would do. +3. **Reviews:** G2, Capterra, Trustpilot, app stores, Reddit threads. Read the one-star and three-star reviews for real objections. +4. **Competitor material:** pricing pages, docs, changelogs, homepages, ads, job posts, conference talks. +5. **Public data:** search demand, industry reports, government statistics, funding announcements. +6. **Analyst and media coverage:** use for context, not for facts about your product. + +Record the source and date for every external claim. Label estimates as estimates. + +## Audience model + +Build one profile per segment, not one per persona name. + +- **Job:** what they are trying to get done, in their words. +- **Trigger:** the event that starts the search. +- **Current workaround:** the spreadsheet, the intern, the old tool. +- **Pains:** what breaks, what costs time, what gets them in trouble. +- **Objections:** price, trust, migration, security, internal approval. +- **Decision process:** who signs, who blocks, how long it takes. +- **Language:** the phrases they repeat. Copy these verbatim into a quote bank. +- **Where they look:** communities, publications, search queries, peers. + +Mark each item with its evidence: interview, review, ticket, or assumption. Never mix them. + +## Competitor set + +Pick competitors by the buyer's actual shortlist, not by who the company likes to compare against. + +| Competitor | Who they win | Promise | Price model | Strengths | Weaknesses | Evidence | +| --- | --- | --- | --- | --- | --- | --- | + +Rules: + +- Read their pricing page and docs, not only their homepage. +- Note what they deliberately do not show: no pricing, no docs, no case studies. +- Look at their reviews for the gap between promise and delivery. +- Track their positioning over time if archived pages exist. + +## Positioning + +Positioning is a choice about where to compete. + +```markdown +For who , is the that . +Unlike , it . +``` + +Then test it: + +- Does it name a real segment, or everyone? +- Is the promise something the buyer already wants, or something the company wishes they wanted? +- Is the difference provable today? +- Would a competitor's customer switch because of it? + +If the answer is no, the positioning is decoration. + +## Message tests + +Cheap ways to check a message before a big campaign: + +- Run it past five people in the segment. Ask what they think it means, not whether they like it. +- Compare two headlines in an ad or a small email test. Measure clicks and replies, not opinions. +- Check the search demand for the words. If buyers do not use the phrase, the message is internal language. +- Read the message back with the brand removed. If any competitor could say it, it is not differentiating. + +## Output + +Write `marketing/research--.md`: + +1. Decision this research serves. +2. Method and sources, with dates. +3. Audience model, with evidence markers. +4. Quote bank: verbatim phrases from real people. +5. Competitor table and the gap we can own. +6. Positioning statement and the evidence behind it. +7. Open questions and what would answer them. +8. Recommended next step: the plan, a test, or more interviews. + +## Pitfalls + +- Survey questions that ask about future behavior instead of past behavior. +- Personas built from demographics with no buying evidence. +- Competitor analysis from homepages only. +- A positioning statement nobody outside the company understands. +- Treating one loud customer as the market. +- Presenting estimates as measured data. + +## Check before delivery + +- Every external claim has a source and a date. +- Assumptions are labeled as assumptions. +- Quotes are real and attributed as allowed. +- The document ends with a decision or a next step. diff --git a/skills/marketing/files/review.md b/skills/marketing/files/review.md new file mode 100644 index 0000000..ceebaf3 --- /dev/null +++ b/skills/marketing/files/review.md @@ -0,0 +1,105 @@ +# Marketing review + +**Use when:** a draft exists and needs a pass before publishing. +**Produces:** a numbered findings list, ordered by severity, then a fixed draft on approval. +**Loads:** `files/write.md` for the format rules, and the `unslop` skill for the language pass. + +## How to review + +1. Read once as the target reader. Do not edit yet. Note where you stop, where you doubt, where you get bored. +2. Read again as the person who has to approve it. Note claims without proof, promises the product cannot keep, and legal exposure. +3. Check the mechanics: format, links, metadata, channel limits. +4. List findings by number with severity. Fix only what the user approves, unless asked to fix everything. + +## Severity + +| Level | Meaning | Examples | +| --- | --- | --- | +| Blocking | Cannot ship | Fabricated claim, wrong price, broken link, missing legal text | +| High | Damages trust or conversion | Promise the proof does not support, unclear offer, wrong audience | +| Medium | Weakens the piece | Buried point, vague CTA, weak opening | +| Low | Polish | Repetition, awkward rhythm, formatting | + +## Checklist + +### Promise and evidence + +- [ ] One audience, one problem, one promise. +- [ ] The headline promise is delivered by the body. +- [ ] Every number has a source and a date. +- [ ] Every quote is real, attributed, and used with permission. +- [ ] No customer names, logos, or results without approval. +- [ ] No guarantees that the product cannot keep. + +### Audience fit + +- [ ] Uses the reader's language, not internal jargon. +- [ ] The opening situation is recognizable to the reader. +- [ ] Objections are handled rather than ignored. +- [ ] The next step fits where the reader is in the decision. + +### Structure + +- [ ] The point appears in the first screen. +- [ ] Sections follow the reader's questions. +- [ ] No section exists only to fill a template. +- [ ] Length matches the question being answered. +- [ ] The ending states the action, not a summary. + +### Language + +- [ ] No em dashes, no semicolons, plain ASCII quotes. +- [ ] No hype words: seamless, revolutionary, leverage, empower, robust, cutting edge. +- [ ] No "in today's world", "it is worth noting", "let us dive in". +- [ ] Sentences are short enough to read once. +- [ ] Active voice, concrete nouns, checkable adjectives. +- [ ] Nothing that would survive a competitor's name swap. + +### CTA and mechanics + +- [ ] One primary action. +- [ ] The action names what happens next. +- [ ] Links resolve to the right page and are tracked. +- [ ] Channel limits respected: subject length, ad character limits, meta description length. +- [ ] Images have alt text and real files. +- [ ] Form fields ask only for what the offer needs. + +### Search, when the piece must rank + +- [ ] Intent matches the query. +- [ ] Title and description unique and accurate. +- [ ] One H1, ordered headings. +- [ ] Internal links added. +- [ ] Structured data valid if used. + +### Legal and accessibility + +- [ ] Claims about security or compliance are accurate. +- [ ] Unsubscribe, privacy, and terms links present where required. +- [ ] Contrast and text size work in the real template. +- [ ] Video and audio have captions or transcripts when published. + +## Findings format + +```markdown +1. [Blocking] Claim "saves 40 percent" has no source. Cite the test or remove. +2. [High] The page targets two audiences. Split or pick the primary one. +3. [Medium] The CTA says "learn more" but the action is a trial signup. +``` + +Keep one line per finding. Add the suggested fix after the finding, not a rewrite. + +## After approval + +- Fix in the source of truth, not in a pasted copy. +- Re-read the changed sections in context. +- Re-check links and numbers after edits. +- Run the `unslop` pass on the final text. +- Report what changed and what you could not verify. + +## Never + +- Rewrite the whole piece when asked for a review. +- Approve a claim because the user is confident. Ask for the source. +- Remove a finding because it is inconvenient. +- Change the voice without saying so. diff --git a/skills/marketing/files/write.md b/skills/marketing/files/write.md new file mode 100644 index 0000000..0994f14 --- /dev/null +++ b/skills/marketing/files/write.md @@ -0,0 +1,178 @@ +# Marketing writing + +**Use when:** the user wants a piece written: landing page, email, ad, social post, case study, article, one-pager, announcement, newsletter. +**Produces:** a draft that is ready for `files/review.md`. +**Loads:** `files/plan.md` brief when it exists. For search-led pieces, also read the `seo` skill, `files/reference/on-page.md` and `files/reference/content.md`. + +## Before the first sentence + +Answer these, from the brief or by asking once: + +1. Who reads this, and what are they doing right now? +2. What is the one promise? +3. What proof exists? +4. What is the next action? +5. Where will it be read: inbox, search result, feed, sales call, product page? + +If the promise or the proof is missing, write the piece without the missing claim. Do not fill the gap with invented numbers or customers. + +## Universal rules + +- One idea per piece. If the draft argues two things, split it. +- Lead with the reader's situation, not the company's history. +- Use the words buyers use. Keep a quote bank from research and pull from it. +- Concrete nouns and verbs. Cut adjectives that cannot be checked. +- Short sentences. Vary length on purpose. +- Active voice by default. +- Second person for the reader. First person plural for the company. +- No em dashes, no semicolons, plain ASCII quotes. +- No hype words: seamless, revolutionary, cutting edge, leverage, empower, unlock, robust, game changing. +- No sentence that would survive a competitor's name in place of ours. That sentence is filler. + +## Structure that works anywhere + +1. **Hook:** the situation or the problem, in one or two lines. +2. **Promise:** what the reader gets, specifically. +3. **Proof:** evidence, example, demo, number, quote. +4. **Detail:** how it works, in the order a reader would ask. +5. **Objection handling:** price, risk, migration, trust. +6. **Action:** one next step, stated plainly. + +Not every format needs all six. Every format needs the hook, the promise, and the action. + +## Headlines + +Write ten, keep two. + +- Name the outcome, not the feature. +- Include the audience when it is narrow. +- Use a number or a detail when it is real. +- Avoid questions the reader can answer "no". +- Avoid puns that hide the meaning. +- Test: does a reader know what they get from the headline alone? + +## Openings + +- Start in the middle of the problem. +- No "In today's fast paced world". +- No "We are excited to announce". Announce it. +- No dictionary definitions. +- One sentence of context is allowed after the hook, not before it. + +## Proof + +Priority order: + +1. Measured result with a method and a date. +2. Customer quote with a name and a role, used with permission. +3. Screenshot, demo, or recording. +4. Named example from a real deployment. +5. Public data with a source. + +If none of these exist, write the piece without proof and say what proof would make it stronger. Do not stage a testimonial. + +## CTA + +- One primary action per piece. Secondary links are fine, competing buttons are not. +- Name the action and what happens next: "Start a free trial, no card needed". +- Avoid "learn more" unless the reader already knows what they will learn. +- Repeat the CTA at the end. Do not repeat it five times. + +## Formats + +### Landing page + +Sections, in order, cut whatever does not earn its place: + +1. Hero: headline, one-line promise, primary CTA, real product visual. +2. Proof strip: real logos or a real quote, only if permission exists. +3. Problem: the reader's current situation. +4. How it works: three or fewer steps, concrete. +5. Outcome: what changes, with evidence. +6. Objections: pricing, security, migration, support. +7. Secondary proof: case study link, docs, demo. +8. Final CTA. + +Length: as short as the offer allows. Complex purchases need more objection handling, not more adjectives. + +### Email + +- Subject: under about 50 characters, specific, no clickbait. Preview text continues the subject, it does not repeat it. +- First line: why this email, why now. +- Body: one idea, short paragraphs, one link repeated at most twice. +- Footer: who you are, how to stop receiving. +- Test: would a person send this to one colleague? + +### Ad + +- Hook in the first three words. +- One promise, one proof, one action. +- Match the landing page message exactly. A mismatch wastes the click. +- State the offer plainly. Vague ads buy expensive curiosity. + +### Social post + +- First line earns the expand. +- One point, one example, no thread when a paragraph works. +- Links in a reply or at the end, per platform convention. +- No engagement bait. + +### Case study + +1. Who the customer is, in one line. +2. The situation before, in their words. +3. What they tried that did not work. +4. What changed, with the implementation detail that makes it credible. +5. The result, with numbers and the measurement window. +6. Quote that says something the page does not already say. +7. What a similar reader should do next. + +Get written permission for names, quotes, and numbers before publishing. + +### Article or blog + +- Answer the title's promise in the first screen. +- Sections that follow the reader's questions. +- Original evidence: test, data, screenshots, experience. +- Subheads that read as a summary on their own. +- No warm-up intro, no summary that repeats the article. + +### One-pager + +- The problem, the offer, the proof, the price or next step. +- Designed for a forwarded email and a printed handout. +- Every claim sourced, because it will be read without the seller present. + +## Search-led writing + +When the piece must rank: + +- Write for the query intent first, then tune the tags. +- Follow the `seo` skill's `files/reference/on-page.md` for title, description, headings, links, images. +- Add the internal links from the brief. +- Do not pad to a word count. Length follows the question. +- Do not add an FAQ unless real questions exist. + +## Voice + +- Match the voice in existing published work before inventing one. +- If none exists, choose three adjectives with the user, then apply them consistently. +- Cut one adjective from every sentence that has three. +- Read the draft aloud. Anything you would not say to a colleague gets rewritten. + +## Delivery + +- Run the `unslop` pass, then `files/review.md`. +- For interface copy, also apply `antislop-copywriting`. +- Report what proof is missing and what the draft assumes. +- When the format is HTML or MDX, check that headings, links, and alt text survived the build. + +## Common failures + +- Two audiences in one piece. +- A promise the proof does not support. +- Feature lists with no outcome. +- Generic CTAs on a specific offer. +- Testimonials with no name or permission. +- Copy written to impress the team, not to help the reader. +- Em dashes and semicolons left in shipped copy. diff --git a/skills/seo/SKILL.md b/skills/seo/SKILL.md new file mode 100644 index 0000000..5c877a3 --- /dev/null +++ b/skills/seo/SKILL.md @@ -0,0 +1,56 @@ +--- +name: seo +description: Audit and improve search performance for an existing website. Use when the user asks for an SEO audit, a traffic or ranking diagnosis, technical SEO fixes, on-page and template optimization, keyword and content gaps, structured data, Core Web Vitals work, or an SEO roadmap. Router that sends each job to a focused playbook in this folder. +--- + +# SEO + +Router. Pick the playbook for the job, then work through it in order. Paths below are relative to this skill folder. Do not read the whole folder for one question. + +## Route + +| The user wants | Read | +| --- | --- | +| Why the site is not ranking, where traffic is lost, what is broken | `files/analyze.md` | +| Fixes, a ranked backlog, template and content changes, a rollout plan | `files/improve.md` | +| Crawl, indexing, rendering, redirects, sitemaps, structured data facts | `files/reference/technical.md` | +| Titles, meta, headings, internal links, images, page copy | `files/reference/on-page.md` | +| Keyword research, search intent, content gaps, briefs | `files/reference/content.md` | +| Search Console, analytics, rank tracking, before and after proof | `files/reference/measurement.md` | + +Usual order: `files/analyze.md` first, then `files/improve.md`. The reference files are loaded on demand by those playbooks, or directly when the user asks about one specific area. + +If the request covers two or more areas, or asks for changes at scale across a template, start at `files/improve.md` and load the reference files it names. Do not run separate playbooks in parallel for one job. + +## Rules + +- Evidence first. Every finding cites a URL, a query, a crawl result, a response header, or a metric. "Best practice" is not a finding. +- One page is not the site. Check every template and a sample of pages per type before generalizing. +- Diagnose before prescribing. A fix without a cause is a guess. +- Rank fixes by impact times confidence divided by effort, and state all three. +- Search engines see what the crawler sees. Verify the rendered result, not the browser tab. +- Never promise rankings or traffic. Name the mechanism you expect and the metric that will show it. +- Never invent metrics, keyword volumes, or competitor traffic. If the tool or export is missing, record it as a limit. +- Check current official guidance (Google Search Central, Bing Webmaster Guidelines) when a recommendation depends on policy, not memory. +- Copywriting in this skill follows the `unslop` rules, and `antislop-copywriting` when the copy is user facing. + +## Deliverables + +Save work where the repo keeps marketing documents. With no convention, use `marketing/seo/` and state the path. + +- `marketing/seo/audit--.md` +- `marketing/seo/plan--.md` + +Both open with the data the work was based on, so the next run can diff against it. + +## Intake gate + +Before analysis, record these facts. Ask only for what you cannot find. + +1. Domain and main templates (home, category, product, article, landing). +2. Target countries and languages. +3. Main organic competitors, named by the user or found by search. +4. Access to Search Console, analytics, or a crawl tool. +5. The business goal behind the work: signups, sales, calls, ad revenue. + +A missing tool is a documented limit. Work with what exists and say what could not be measured. diff --git a/skills/seo/files/analyze.md b/skills/seo/files/analyze.md new file mode 100644 index 0000000..f801f26 --- /dev/null +++ b/skills/seo/files/analyze.md @@ -0,0 +1,101 @@ +# SEO audit + +**Use when:** the user asks why the site is not ranking, what is broken, where organic traffic is lost, or wants an SEO audit. +**Produces:** a dated audit document with sourced findings, severity, and a short list of the causes that matter most. +**Load with:** `files/reference/technical.md`, `files/reference/on-page.md`, `files/reference/content.md`, `files/reference/measurement.md` as each step needs them. + +## Inputs + +Collect before judging: + +- Domain, target countries, target languages. +- Templates and a sample URL for each. +- Search Console access or an export. If absent, say the query-level diagnosis is limited. +- Analytics access or an export for organic sessions and conversions. +- Known competitors, or the top three domains ranking for the main money terms. +- Recent site changes: redesign, migration, new CMS, URL changes, lost backlinks. + +## Steps + +### 1. Baseline snapshot + +Record the numbers the audit will be judged against. + +- Organic sessions and conversions, last 3 months, segmented by template, country, device. +- Indexed page count from Search Console, and the count from a `site:` query. +- Top 20 landing pages by organic traffic, and top 20 queries by impressions. +- Core Web Vitals field data for mobile and desktop. +- Date of the snapshot. Findings age, and a silent decay is itself a finding. + +### 2. Index and crawl health + +Work through `files/reference/technical.md`. The questions that matter: + +- Can every important page be crawled and indexed? Check robots.txt, meta robots, X-Robots-Tag, canonicals, sitemaps. +- Are important pages reachable by links, or only by the sitemap? +- Is the rendered HTML the same as what the crawler gets? Check one JS-heavy template with rendering disabled, or with the URL Inspection live test. +- Do redirects form chains or loops? Do old URLs still return 200 duplicates? +- Are faceted, parameter, or search pages creating index bloat? +- Is there a canonical conflict between `www` and non-`www`, `http` and `https`, or trailing slash variants? + +### 3. Template and on-page review + +Sample at least three URLs per template. For each template, audit one page against `files/reference/on-page.md` and note the pattern, not the individual page. + +- Title, meta description, H1, heading order. +- Search intent match: does the page answer the query it targets? +- Thin or duplicated template output (empty category pages, near-identical product copy). +- Internal links into the template, and out of it. +- Images, alt text, file weight. +- Structured data presence and validity. + +### 4. Content and query coverage + +- Map the top queries to landing pages. Queries with no matching page are gaps. +- Queries where two or more pages compete are cannibalization candidates. Confirm with the query and URL report. +- Compare the site's topic coverage against the top two competitors. Use their sitemaps and search results, not guesses. +- Classify missing coverage by intent: informational, commercial, transactional, navigational. + +### 5. Structure and authority + +- Click depth from the home page. Pages more than three clicks deep get less equity and less crawling. +- Anchor text distribution. Generic "click here" links to money pages are a finding. +- Breadcrumbs and category architecture. +- Backlink profile if data exists: referring domains, anchor mix, lost links around the traffic change date. +- Trust signals for the topic: author pages, about page, contact details, citations, reviews. + +### 6. Change history + +Correlate the traffic change with releases. Check deploy dates, redirect maps, and Search Console coverage spikes. A drop with a same-week release is usually a technical regression, not an algorithm update. + +### 7. Prioritize + +Produce one table. No long prose list. + +| Finding | Evidence | Pages or templates | Cause | Impact | Confidence | Effort | +| --- | --- | --- | --- | --- | --- | --- | + +Impact: high, medium, low, measured against the business goal from intake. +Confidence: high when the mechanism is known and the evidence is direct. +Effort: hours or days of one engineer or writer. + +Sort by impact times confidence divided by effort. + +## Output + +Write `marketing/seo/audit--.md`: + +1. Scope and data used, with dates and tool names. +2. Limits: what could not be measured, and why. +3. Health summary: index, crawl, performance, content, authority, in five short lines. +4. Findings table, sorted. +5. Top three causes, with the evidence chain for each. +6. Recommended next step: the `files/improve.md` plan, or a measurement setup first. +7. Appendix: URLs sampled, exports used, queries checked. + +## Checks before delivery + +- Every finding has a URL or export behind it. +- Findings are grouped by cause, not listed page by page. +- The audit names limits instead of filling gaps with assumptions. +- The audit does not recommend a fix whose cause is unconfirmed. diff --git a/skills/seo/files/improve.md b/skills/seo/files/improve.md new file mode 100644 index 0000000..8b3e839 --- /dev/null +++ b/skills/seo/files/improve.md @@ -0,0 +1,107 @@ +# SEO improvements + +**Use when:** the audit is done, or the user wants a fix list, an implementation plan, or a rollout order. Also use for "just fix the titles" style requests. +**Produces:** a ranked plan, the changes themselves, and a measurement record. +**Load with:** `files/reference/technical.md`, `files/reference/on-page.md`, `files/reference/content.md`, `files/reference/measurement.md` for the fix pattern in play. + +## Start from evidence + +Do not plan fixes without an audit or a specific user report. Read `files/analyze.md` output, or run the smallest audit that identifies the cause. Each plan item carries: + +- The finding and its evidence. +- The cause. +- The change, at template level when the issue repeats. +- Expected effect and the metric that will show it. +- Effort, owner, and dependencies. + +## Order of work + +1. **Blockers.** Anything that stops crawling, indexing, or rendering. Robots rules, accidental noindex, broken canonicals, 5xx, blocked assets, broken JS bundles. These come first even when the fix is small. +2. **Regressions.** Redirect chains, missing redirects after a migration, duplicate host or protocol variants, lost internal links. Restore what worked before adding anything new. +3. **Template fixes.** Title, description, H1, canonical, internal links, schema, image handling. One template change reaches many pages, so it beats page-by-page edits. +4. **Content work.** Refresh decaying pages, merge cannibalized pages, fill intent gaps, prune thin pages. This is the slowest and usually the largest win. +5. **Authority and off-page.** Only after the site can be crawled, rendered, and trusted. Links to a broken page waste the link. +6. **Performance.** Core Web Vitals when field data shows a real problem, not because a lab score looks low. + +## Fix patterns + +### Titles and descriptions + +- One intent per page. The title names the thing and the differentiator, not the brand alone. +- Keep titles short enough to render in results on mobile. Roughly 50 to 60 characters is a safe target, not a rule. +- Descriptions earn the click, they do not rank. Write them per template with real specifics, and do not mass-generate near-identical text. +- Fix at the template or CMS field level. Do not hand-edit 400 pages when one template rule fixes them. + +### Canonicals and duplicates + +- One canonical URL per piece of content: scheme, host, path, trailing slash, case. +- Self-referencing canonicals on indexable pages. +- Point variants at the primary. Never point a page at a different topic. +- Verify with the rendered HTML, not the source template alone. + +### Redirects + +- One hop. No chains. No redirect to a 404. +- Keep a redirect map in the repo when a migration causes it. It is the only durable record. +- Return 410 for content that should disappear and has no replacement. +- Watch for redirects that drop query parameters needed by tracking or filters. + +### Internal links + +- Link from pages with traffic and authority to pages that need it. +- Use descriptive anchors, varied naturally, not the same phrase on every link. +- Reduce click depth for money and pillar pages. +- Remove links to pruned or redirected pages, or update them to the new target. + +### Content refresh + +Refresh before creating when a page already targets the query. Steps: compare the page against the current top results, add what is missing, update facts and dates, fix intent mismatch, strengthen the internal links, then request indexing. Keep the URL. + +### Pruning + +Merge or remove pages that have no traffic, no links, and no unique intent. Redirect to the closest relevant page, or return 410. Never mass-delete without checking backlinks first. + +### Structured data + +Add only the types the page actually is. Validate with the Rich Results Test and the schema validator. Invalid markup is worse than none. Do not mark up content that is not visible on the page. + +### Performance + +Fix the metric that field data flags, in this order: LCP resource and priority, render-blocking work, image dimensions and formats, third-party scripts, layout shifts, main thread work. Measure with field data after the change, not a single lab run. + +## Plan format + +Write `marketing/seo/plan--.md`: + +1. Goal and metric. +2. Constraints: team, release process, freeze windows. +3. Phases in the order above, each with a checklist. +4. Per item: finding, change, owner, effort, expected metric movement. +5. Verification steps per item. +6. Measurement window and the review date. +7. Risks and rollback. + +## Verification + +- Crawl the changed templates after deploy. Confirm status codes, canonicals, titles, and robots directives. +- Spot-check three live pages per changed template with rendering on. +- Confirm redirects resolve in one hop to a 200. +- Validate any new structured data. +- Check Search Console coverage for new errors within a few days. +- Record the deploy date in the plan. It anchors the before and after comparison. + +## Risks to name + +- Redirect changes can drop rankings for weeks. Stage them and keep the map. +- Canonical changes can remove pages from the index by accident. +- Bulk content edits can look like a rewrite to search engines and to readers. +- Title rewrites can lower click-through even when ranking holds. Measure both. +- Removing pages can lose links and conversions. Check both before deleting. + +## Never + +- Cloaking, doorway pages, hidden text, keyword stuffing. +- Buying links or link exchanges presented as partnerships. +- Mass-generated pages with no unique value. +- Editing robots.txt to "fix" indexing before confirming the real cause. +- Claiming a fix worked without a measurement window. diff --git a/skills/seo/files/reference/content.md b/skills/seo/files/reference/content.md new file mode 100644 index 0000000..6d5289b --- /dev/null +++ b/skills/seo/files/reference/content.md @@ -0,0 +1,135 @@ +# Content and keyword reference + +**Use when:** building keyword lists, mapping queries to pages, finding content gaps, deciding create versus refresh, or writing a content brief for search. +**Loaded by:** `files/analyze.md` step 4, `files/improve.md` content work, and the `marketing` skill when planning search-led content. + +## Where keyword data comes from + +Start with queries the site already earns, then expand. + +| Source | Gives you | +| --- | --- | +| Search Console queries and pages | Real impressions, clicks, position, and the queries a page almost ranks for | +| Search autocomplete and related searches | Demand language and long-tail variants | +| People Also Ask and result features | Question intent and the format expected | +| Competitor sitemaps and rankings | Topics they own, page types, and gaps | +| Reviews, forums, support tickets, sales calls | The words buyers actually use | +| Paid search exports, when available | Converting queries and negative terms | + +Paid tools disagree on volume. Treat volume as a relative signal, not a fact, and never present it as exact. State the source and the date. + +## Intent classification + +Classify every cluster before mapping it. + +- **Informational:** how, what, why, guide, examples, best, vs. +- **Commercial:** best, top, review, alternatives, pricing, comparison. +- **Transactional:** buy, price, demo, trial, download, book. +- **Navigational:** brand names, product names, login. + +One cluster, one intent, one page. If a cluster mixes intents, split it. + +## Clustering + +Group queries that the same page can satisfy. + +1. Start from a seed topic, not a single keyword. +2. Pull variants from Search Console, autocomplete, and question sources. +3. Group by meaning, not by string match. "pricing", "cost", and "how much" often share a page. +4. Name each cluster with the primary query a human would type. +5. Check the current results for the cluster. If the top results are all a different page type, the intent is different from what the words suggest. + +## Mapping + +Build one table: + +| Cluster | Intent | Primary query | Page | Action | +| --- | --- | --- | --- | --- | +| ... | ... | ... | existing URL or new slug | refresh, create, merge, prune | + +Rules: + +- No page owns two unrelated clusters. +- No cluster has two pages. That is cannibalization. +- New pages need internal links from pages that already have authority. +- A new page is justified by a new intent, not by a new keyword. + +## Create, refresh, merge, or prune + +- **Refresh:** the page matches the intent and has some impressions, but is thin, stale, or off-format. Keep the URL. +- **Create:** no page matches the intent, and the cluster has real demand and a path to rank. +- **Merge:** two or more pages split the same intent. Combine into the strongest URL and redirect the rest one hop. +- **Prune:** no demand, no links, no conversions, no unique intent. Redirect or return 410. + +Default to refresh. New pages cost links, time, and maintenance. + +## Gap analysis against competitors + +1. Take the top two or three competitors for the money terms. +2. Pull their sitemaps and their ranking pages for the topic. +3. Group their coverage by cluster. +4. Mark clusters you cover, cover weakly, or miss. +5. Rank gaps by business value, not by competitor count. +6. For each gap, decide whether the site can win: does it have proof, data, or experience the competitor does not? + +Copying a competitor's outline produces a worse version of their page. Find the angle the site can own. + +## Content brief + +Write the brief before the draft. One page, no filler. + +```markdown +# Brief: + +- Cluster and primary query: +- Intent: +- Target reader: +- Angle only we can take: +- Search result format to match: +- Sections, in order, with the question each answers: +- Proof to include: data, screenshots, quotes, tests +- Internal links in: +- Internal links out: +- Title tag and meta description: +- Structured data: +- Success metric and review date: +``` + +The writer may change the outline. The angle and the proof list stay. + +## Experience and trust + +Search rewards content that shows first-hand work. Before writing, answer: + +- Did we use the product, run the test, or handle the case ourselves? +- Is there original data, a screenshot, a recording, or a measurement? +- Is the author a real person with a relevant background? +- Are facts dated and sourced? +- Does the page show who is behind the site? + +If the answer is no to all of these, the page is a rewrite of existing results. Either add first-hand evidence or do not publish. + +## Internal links for new content + +- Link from at least three existing pages with traffic or authority. +- Use the anchor a reader would click, not the exact keyword every time. +- Link out from the new page to its parent topic and to related pages. +- Add the page to the sitemap and to the relevant hub or category. + +## Quality gate + +- [ ] One intent, one page. +- [ ] Original evidence or a clear reason the page is the best answer. +- [ ] Format matches what results favor. +- [ ] Answer appears in the first screen. +- [ ] Facts sourced and dated. +- [ ] Internal links in and out. +- [ ] Title, description, headings checked against `files/reference/on-page.md`. +- [ ] No fabricated data, quotes, or reviews. + +## Never + +- Publish near-duplicate pages for keyword variants. +- Generate pages at scale with no unique value. +- Present tool estimates as measured traffic or revenue. +- Add FAQs, stats, or testimonials that were not verified. diff --git a/skills/seo/files/reference/measurement.md b/skills/seo/files/reference/measurement.md new file mode 100644 index 0000000..2ec8049 --- /dev/null +++ b/skills/seo/files/reference/measurement.md @@ -0,0 +1,108 @@ +# Measurement reference + +**Use when:** setting up tracking, proving a fix worked, building an SEO report, or explaining why a metric moved. +**Loaded by:** `files/analyze.md` step 1 and 7, `files/improve.md` verification, and any reporting request. + +## Pick the metric before the work + +The metric comes from the business goal recorded at intake. + +| Goal | Primary metric | Supporting | +| --- | --- | --- | +| Signups | Organic signups | Sessions by template, conversion rate | +| Sales | Organic revenue | Product page sessions, add to cart, checkout completion | +| Leads | Organic form submissions and calls | Landing page sessions, form start rate | +| Ad revenue | Organic pageviews and RPM | Session duration, pages per session | +| Brand demand | Branded search volume and impressions | Direct traffic, branded clicks | + +Traffic alone is not a goal. A page can gain sessions and lose signups. + +## Search Console + +Use these reports, with a fixed date range and a fixed set of pages: + +- **Queries:** impressions, clicks, CTR, average position. Filter to non-branded to see real acquisition. +- **Pages:** which URLs earn the traffic. Group by template with a URL pattern filter. +- **Performance over time:** compare two equal periods, same days of week. +- **Coverage or Pages report:** indexed, excluded, and the reason for each exclusion. +- **Core Web Vitals:** field data by device. +- **URL Inspection:** rendered HTML, canonical, crawl status for one URL. + +Caveats: + +- Position is an average across queries and locations. It is not a rank. +- CTR depends on the result layout. A featured snippet can raise or lower it. +- Data is sampled and anonymized in places. Small segments are noisy. +- Use 28-day or 3-month windows. Weekly fluctuations are noise. + +## Analytics + +- Segment organic search, then by landing page, country, device. +- Track the conversion events that map to the goal, not just pageviews. +- Check that conversions are not double-counted across events. +- Compare organic against other channels for the same period. Seasonality moves everything. + +## Rank tracking + +- Use it for a fixed list of target queries, not for a general score. +- Pin location, device, and language. Rankings differ by all three. +- A single rank tool is a sample. Two tools disagree often. +- Never report a rank change as the business result. Report clicks and conversions. + +## Proving a fix + +Use the strongest evidence available, in this order: + +1. **Holdout:** split comparable templates or page groups, change one, leave the other. Compare after the same window. +2. **Before and after:** same pages, equal windows, one change, no other releases in the window. +3. **Correlation with a change log:** weakest. Useful when nothing else exists, and must be labeled as correlation. + +Record the change log: + +| Date | Change | Pages or templates | Owner | Expected effect | +| --- | --- | --- | --- | --- | + +Measurement windows: + +- Indexing and title changes: 2 to 4 weeks. +- Content refresh: 4 to 8 weeks. +- Structural and internal link work: 4 to 12 weeks. +- Migration recovery: up to several months. + +Do not declare success inside the window. State the window and the review date. + +## Report format + +Keep it to one page unless asked for more. + +```markdown +# SEO report: , + +- Goal and primary metric: +- Period compared with: +- What changed: +- Result: metric, delta, and whether it is inside noise +- Driver: which pages, queries, or templates moved +- Next: the three highest-impact actions +- Limit: what the data cannot show +``` + +Rules: + +- Show absolute numbers next to percentages. A 200% rise from 3 to 9 is not a win. +- Name the comparison period. +- Separate branded from non-branded. +- Flag seasonality, releases, and tracking changes that could explain the move. +- If the cause is unclear, say so. Do not attach a convenient story. + +## Track the baseline once + +Save the baseline snapshot from `files/analyze.md` with the audit. Every later comparison points at it. Without a baseline, "improvement" is an opinion. + +## Never + +- Report impressions as traffic. +- Compare unequal periods, or periods with a tracking change. +- Present a rank tool score as revenue impact. +- Claim a fix worked when the window has not passed. +- Hide a decline by changing the metric. diff --git a/skills/seo/files/reference/on-page.md b/skills/seo/files/reference/on-page.md new file mode 100644 index 0000000..ca93a74 --- /dev/null +++ b/skills/seo/files/reference/on-page.md @@ -0,0 +1,116 @@ +# On-page reference + +**Use when:** writing or reviewing titles, meta descriptions, headings, body copy, internal links, images, URLs, or page intent for search. +**Loaded by:** `files/analyze.md` step 3, `files/improve.md` template fixes, and the `marketing` skill when content is search-driven. + +## One intent per page + +Before touching the tags, answer: which query is this page for, and what does the searcher want? + +| Intent | The searcher wants | The page must | +| --- | --- | --- | +| Informational | An answer, a method, a comparison | Answer early, then show depth | +| Commercial | To compare options before buying | Compare, price, alternatives, proof | +| Transactional | To act now | Offer, price, availability, one clear action | +| Navigational | A specific brand or page | Get them there fast | + +A page that answers a different intent than the query will not rank, no matter how good the tags are. Fix intent before optimization. + +## Title + +- Names the page's subject and the reason to pick it. +- Front-load the distinguishing words. Brand goes last unless the brand is the query. +- Roughly 50 to 60 characters is a safe rendering target. Longer titles get truncated, not penalized. +- Unique per page. Duplicate titles across a template mean the template is wrong. +- No keyword repetition, no clickbait the page cannot deliver. +- Avoid "Home" and "Untitled" on money pages. + +## Meta description + +- Not a ranking factor. It is ad copy for the result. +- Say what the page delivers and to whom, in one or two sentences. +- Roughly 140 to 160 characters. Mobile truncates sooner. +- Unique per template or page type. Do not machine-generate near-duplicates. +- No "click here to learn more". No promises the page does not keep. + +## Headings + +- One H1 that matches the page subject. It can differ from the title tag. +- H2s for the main sections, H3s under them. Do not skip levels for styling. +- Headings read as a table of contents. A reader scanning only headings should get the argument. +- Keyword variants belong in a heading only when they help the reader. + +## Body + +- Answer the query in the first screen. Background comes after. +- Concrete detail beats word count. A short page that answers wins over a padded one. +- Evidence for claims: numbers with a source, tests with a method, quotes with a name. +- Original observation or data earns trust that rewritten competitor text cannot. +- Update facts, dates, and screenshots. Stale content is a slow ranking leak. +- Match the format the results favor: table, steps, comparison, definition, tool. + +## Internal links + +- Link to related pages where a reader would naturally want them. +- Descriptive anchors. "Pricing for teams" beats "click here". +- 3 to 8 contextual links is usually enough for an article. More is fine when each is useful. +- Link from strong pages to weak ones, not only the reverse. +- Check the target is a 200 with a single canonical. + +## Images and media + +- Real screenshots or photos over stock and generated art. +- Descriptive file names and alt text. Alt describes the image for a person who cannot see it. +- Explicit width and height to prevent layout shift. +- Compress, use modern formats, lazy-load below the fold, never lazy-load the LCP image. +- Captions earn attention. Use them when the image needs explanation. + +## URLs + +- Short, readable, lowercase, hyphenated. +- Stable. Changing a URL costs more than it ever gains. +- No dates in evergreen URLs. No IDs when a slug is possible. +- Path should reflect the section: `/blog/`, `/guides/`, `/products/`. + +## Structured data + +- Add the type the page is: Article, Product, FAQPage only with real FAQs, BreadcrumbList, Organization, LocalBusiness. +- Match visible content exactly. +- Validate after changes. Broken markup is a defect. + +## Search snippet work + +- Write the title and description as a pair. The user sees both. +- Lead with the differentiator when competition is high. +- Keep the first 120 characters self-contained. That is what mobile shows. + +## Local pages + +- Name, address, phone in visible text, matching the business listing. +- Embedded map, opening hours, service area. +- One page per real location. Do not generate city pages with swapped names and no local content. + +## Page-type checklist + +Use as a final pass, not as a template to fill. + +- [ ] Intent matches the query. +- [ ] Unique title and description. +- [ ] One H1, ordered headings. +- [ ] Answer in the first screen. +- [ ] Claims have sources. +- [ ] Internal links to related pages. +- [ ] Images sized, compressed, alt text. +- [ ] Canonical is correct. +- [ ] Structured data valid and visible. +- [ ] Next action is obvious. + +## Common failures + +- Keyword stuffing in titles and first paragraphs. +- Same meta description on 200 pages. +- H1 used for the logo, then reused on every page. +- FAQ blocks generated from keyword lists. +- Article text that restates the top results with no added evidence. +- Links to redirected or pruned pages. +- City landing pages with only the city name changed. diff --git a/skills/seo/files/reference/technical.md b/skills/seo/files/reference/technical.md new file mode 100644 index 0000000..72d2f1a --- /dev/null +++ b/skills/seo/files/reference/technical.md @@ -0,0 +1,130 @@ +# Technical SEO reference + +**Use when:** checking crawl, index, render, redirect, sitemap, canonical, or structured data behavior. +**Loaded by:** `files/analyze.md` step 2 and `files/improve.md` fix patterns. + +## Crawl and index checklist + +| Check | How to see it | Failure looks like | +| --- | --- | --- | +| robots.txt allows the page and its assets | Fetch `/robots.txt`, test the URL against it | CSS, JS, or image folders blocked | +| No accidental noindex | Rendered HTML head, `X-Robots-Tag` header | Staging `noindex` shipped to production | +| Canonical points to the right URL | Rendered HTML, not the template source | Canonical to the home page on every article | +| Status codes are honest | Crawl export | Soft 404s, 200 pages that say "not found" | +| Redirects are one hop | `curl -I` chain | Chains, loops, redirect to 404 | +| Sitemap lists indexable URLs only | Fetch the sitemap | 404s, redirected URLs, noindex URLs listed | +| Important pages are linked | Crawl depth report | Orphan pages found only in the sitemap | +| Pagination is crawlable | Crawl | `rel=next` removed and links hidden behind JS | +| Facets and parameters are controlled | Crawl, canonical rules | Thousands of near-duplicate URLs indexed | +| Host and protocol are single | `curl -I` on each variant | `http`, `https`, `www`, and non-`www` all return 200 | + +## Rendering + +Search engines render JavaScript, but not always the same way or as fast. Verify with the URL Inspection live test, or a renderer that disables JS. + +- Content that exists only after a click is usually not indexed. +- Lazy-loaded images need a real `src` or a crawler-visible `srcset`. +- Client-side routing must serve real URLs, not `#/path` fragments. +- Infinite scroll needs paginated URLs behind it. +- Compare the rendered DOM against `view-source` when a template looks suspicious. + +## Canonical patterns + +```html + +``` + +Rules: + +- Absolute URL, correct scheme and host. +- Self-reference on the page itself. +- One canonical per page. Multiple canonical tags are ignored or misread. +- Do not canonicalize across topics to "consolidate". Consolidate only duplicates. +- Paginated pages should self-canonicalize, not point to page one. + +## robots.txt + +```txt +User-agent: * +Disallow: /checkout +Disallow: /*?sort= +Allow: / + +Sitemap: https://example.com/sitemap.xml +``` + +Notes: + +- `Disallow` blocks crawling, not indexing. Use `noindex` to remove a page from the index. +- Never block CSS, JS, or image paths that the page needs to render. +- Test rules against real URLs before deploying. A single wildcard can block a whole template. +- Keep the file small. Rules are not a security control. + +## Sitemaps + +- Split by type: pages, articles, images, video. +- List only 200 status, indexable, canonical URLs. +- Include `lastmod` only when it reflects real content change. +- Reference the sitemap in robots.txt. +- Check size limits: 50,000 URLs or 50 MB uncompressed per file. + +## Structured data + +Use JSON-LD in the page head. Mark up only what the page shows. + +```html + +``` + +Check: + +- Required fields per type, per the current schema documentation. +- Values match the visible page. +- No `FAQPage` markup on pages without real questions, no `Review` markup without real reviews. +- One primary entity per page. Nest related entities instead of stacking unrelated types. + +## Status codes + +| Code | Use | +| --- | --- | +| 200 | Real content | +| 301 | Permanent move, same topic | +| 302 | Temporary move, keep the URL in mind | +| 404 | Missing, no replacement | +| 410 | Removed on purpose | +| 5xx | Server failure, never a redirect target | + +## Core Web Vitals + +Field data is the source of truth. Lab tools only explain a field problem. + +- **LCP**: find the element, then check server response, resource priority, image size and format, render-blocking CSS. +- **INP**: find the long tasks on interaction, split heavy work, defer third-party scripts. +- **CLS**: set explicit dimensions on media and embeds, reserve space for injected banners. + +Check mobile field data separately. Most sites fail there first. + +## Log files + +When available, server logs show what crawlers actually requested. Useful for: + +- Pages crawled but never indexed. +- Crawl budget wasted on parameters. +- Assets blocked by robots.txt. +- Sudden crawl drops after a deploy. + +Keep the analysis to a sample window. Logs are evidence, not a daily report.