examples.md
# Reference intros
Use these as tone and structure references, not copy-paste templates. Patterns and rules: [SKILL.md](SKILL.md#intro-patterns).
## Contents
- [Listicle — search engines](#listicle-search-engines)
- [How-to — reverse image search](#how-to-reverse-image-search)
- [Definition — what is SEO](#definition-what-is-seo)
- [Full output — definition guide (AI SEO style)](#full-output-definition-guide-ai-seo-style)
- [Debate intro — frame a fight](#debate-intro-frame-a-fight)
## Listicle — search engines
**Title:** 21 Best Search Engines in the World
**Slug:** `search-engine-list`
Search engines are online tools that allow users to search for content on the internet.
Google is the most popular. But many other search sites and apps get millions of visits each month.
Explore our list of the best search engines in the world (grouped by type, in no particular order). Or jump straight to our search engine FAQs.
---
## How-to — reverse image search
**Title:** How to Do a Reverse Image Search (Desktop and Mobile)
**Slug:** `reverse-image-search`
A reverse image search is the act of searching the internet with an image rather than keywords.
It helps you uncover more details about the image itself and its subject matter.
Such as:
- The original size of the image
- Alternative sizes
- Other appearances on the internet
- Visually similar images
In this article, we'll cover how to do a reverse image search on desktop and mobile.
And how you can get attribution for any of your uncredited images.
---
## Definition — what is SEO
**Title:** What Is SEO? Meaning, Examples & How to Optimize Your Site
**Slug:** `what-is-seo`
SEO (search engine optimization) is a set of processes aimed at improving a website's visibility in search engines, like Google, with the goal of getting more organic traffic.
SEO activities can take place both on-site and off-site. That's why you may often see SEO divided into "on-page" and "off-page" categories.
In practice, SEO typically involves:
- Keyword research
- Content creation and optimization
- Technical optimization
- Link building
---
## Full output — definition guide (AI SEO style)
Modeled on [Semrush's AI SEO intro](https://www.semrush.com/blog/ai-seo/).
**Slug:** `ai-seo`
**Title:** AI SEO: How to Get Cited by ChatGPT, Google AI Overviews & Perplexity
**Image alt:** Diagram showing AI search engines pulling citations from a web page into a chat answer.
**Intro:**
**AI SEO** is the practice of optimizing your content so AI engines (ChatGPT, Perplexity, Google's AI Overviews) can find it, extract it, and cite it as a source.
That means two new jobs for SEO:
- Getting your pages picked as the **source** behind AI-generated answers
- Making sure the **brand** those answers describe is the one you want users to see
And it matters more than ever. Pew Research found that users who see an AI summary click a traditional link only **8%** of the time, compared to **15%** without one. In other words: _ranking #1 no longer guarantees the click._
**In this guide, you'll learn:**
- [The platforms AI SEO applies to](#platforms)
- [The retrieval factors that drive citations](#retrieval-factors)
- [A step-by-step process to get your content cited](#process)
- [The metrics that replace rank tracking](#metrics)
Here's what to know before you optimize for citations.
---
## Debate intro — frame a fight
From [Max Marchione's BPC-157 article](https://x.com/maxmarchione/article/2061492144636920206). The opening:
> BPC-157 is one of the peptides that's talked and asked about the most.
>
> The debate sits between two extremes.
>
> On one side, people say it's the holy grail of healing. On the other, people say it will give you cancer. The answer lies somewhere in the middle.
Then a question list that doubles as the table of contents. Why it works:
- **It frames a fight, not a topic.** Two extremes, and the article as the level-headed referee. That tension is the reason to keep reading.
- **It names the enemy and the method.** "Everyone on Twitter is shooting from the hip. This piece does the opposite." Then it sells a payoff: you'll understand the topic better than almost anyone arguing about it online.
- **Question-list roadmap.** The questions mirror what a curious reader already wonders, and the H2s answer them in order.
- **One-line paragraphs control pace.** "This is where things get murky." Standalone lines give the eye a rest and add weight.
- **Connecting phrases carry the reader.** "Which leaves an open question," "On top of this," "More precisely." Each section hands off to the next.
- **Honest hedging builds credibility.** "Treat the loud voices on both sides with skepticism, including this one."
- **No em dashes.** Ideas are split into separate sentences instead.
- **Concrete over vague.** "16 patients," "87.5%," named people. Specific numbers make claims feel checked.
SKILL.md
---
name: intro
description: Write short, Semrush-style blog post intros with journey teasers, practical relevance, and reader intent matching. Use when the user asks for /intro, a blog intro, opening paragraph, article lead, listicle intro, or hook copy for a post.
metadata:
version: 1.0.0
author: illyism
source: https://il.ly/skills/intro
---
# Blog Intro Writer
Write engaging blog intros in the style of high-performing SEO listicles and guides ([examples.md](examples.md#contents)).
## Contents
- [When this applies](#when-this-applies)
- [First step](#first-step)
- [Commitments](#commitments)
- [Intro patterns](#intro-patterns)
- [Writing rules](#writing-rules)
- [Slug, title, and image alt](#slug-title-and-image-alt)
- [Default output](#default-output)
- [Full output format](#full-output-format)
- [Quality check](#quality-check)
## When this applies
The user invoked **`/intro`**, or asked for a blog intro, opening paragraph, or lead copy for a post.
Works on its own or after title work (see the `seo-title-optimization` skill). If the slug or title is missing, ask briefly or propose one.
## First step
Say: "Tell me a bit about your content and I'll write an intro for it."
Gather enough to match intent:
- Topic, primary keyword, and search intent (informational, listicle, how-to, comparison)
- Target reader and their goal
- Article shape: listicle count, H2/H3 outline, or key sections
- Product angle, if the post promotes one
- Optional: chosen title, slug, featured image subject
If the user already pasted an outline or draft, use it. Do not invent stats, market share, or legal claims unless they provided them.
## Commitments
I will:
- Use simple, concise English
- Return an image alt text
- Give a slug and a title
- Use lists where they help scanning
- Match the reader's intent to the content
- Introduce the topic and why it matters
- Tell readers what they will learn
- **Journey teaser:** a roadmap of the key steps or sections ahead
- **Explain why:** the practical importance of the topic
- **Relevance:** how the topic relates to the reader's goal
- Use short sentences and keep it short
## Intro patterns
Pick the pattern that fits the article type.
### Listicle (e.g. "21 Best Search Engines")
Reference: [listicle example](examples.md#listicle-search-engines)
1. One sentence: what the thing is.
2. One sentence: why the default option is not enough, or why the list matters.
3. Journey teaser: what the list covers and how it is organized (`grouped by type`, `in no particular order`).
4. Optional jump line: `Or jump straight to our [FAQs](#anchor).`
### How-to / guide (e.g. reverse image search)
Reference: [how-to example](examples.md#how-to-reverse-image-search)
1. Lead with the task or problem in plain language.
2. **Explain why** in one or two short sentences.
3. Optional bullet list of outcomes (3–5 items) when it clarifies value.
4. Journey teaser: what platforms or steps the article covers.
5. Close with what they will learn by the end (one short sentence).
### Definition-first (e.g. "What Is SEO?")
Reference: [definition example](examples.md#definition-what-is-seo)
1. Open with the term and a tight definition (expand acronyms on first use).
2. One sentence on the user need and outcome (visibility, traffic, accuracy).
3. Optional short bullet list of what the practice involves.
4. Journey teaser: the main sections ahead.
### Debate / evidence piece
Reference: [debate example](examples.md#debate-intro-frame-a-fight)
1. Frame two extremes the reader has heard.
2. Position the article as the level-headed referee and name the method.
3. Promise a concrete payoff.
4. List the questions the article answers, in the order the H2s answer them.
## Writing rules
- **Short sentences.** Prefer 8–15 words. Break long lines into two sentences.
- **Keep it short.** 2–4 short paragraphs or 80–120 words unless the user asks for more.
- **Listicles:** mirror the count in the title (`three proven ways`, `five common mistakes`).
- **Voice:** direct, practical, confident. No hype words.
- **Emphasis (sparingly):** **bold** 2–4 hook words per intro (primary keyword, pain point, or outcome). Use _italic_ for one short aside or contrast. Never both on the same phrase.
- **No H2 in the intro** unless the outline starts with a definition block (`What Is X?`) right after the intro.
- The intro is the first prose block after frontmatter, not the meta description or excerpt.
## Slug, title, and image alt
- **Slug and title:** use the ones the user has. If not, propose one slug and one title that fit the intro.
- **Image alt:** describe the featured image for accessibility: subject plus context (mock UI, diagram, before/after). One sentence, under 125 characters when possible.
## Default output
Unless the user asks for `full`, `slug`, `title`, or `alt`, return only the intro: the markdown body paragraphs, ready to paste under frontmatter.
## Full output format
Use when the user asks for **`full`** or everything in one pass. Reference: [full output example](examples.md#full-output-definition-guide-ai-seo-style).
```markdown
**Slug:** `[slug]`
**Title:** [title]
**Image alt:** [one sentence, under 125 characters when possible]
**Intro:**
[1–2 sentences: definition or what the thing is]
[Optional: "That means…" + 2–4 short bullets: outcomes or jobs to be done]
[1–2 sentences: **explain why**, the practical stakes; use stats only if the user provided them]
**In this guide, you'll learn:**
- [Section or outcome 1](#heading-anchor)
- [Section or outcome 2](#another-anchor)
- [Section or outcome 3](#another-anchor)
- [Section or outcome 4](#another-anchor)
[One short closing line. Vary it; do not default to "Let's dive in."]
```
**Closing lines (pick one that fits; avoid repeating across a batch):**
- Here's how it works.
- Below is the full walkthrough.
- We'll break down each approach below.
- Here's what to know before you build.
- Use the sections below as your playbook.
- Read on for the step-by-step workflow.
- Here's how each platform compares.
- The rest of this guide covers it in order.
Rules for full output:
- Label fields with **Slug**, **Title**, **Image alt**, **Intro** so they are easy to copy.
- Use the heading **`In this guide, you'll learn:`** (or a close variant the user prefers).
- **Link each journey bullet** to the matching H2 anchor on the same post when the heading slugs are known. Anchors must match the live post.
## Quality check
Before returning, confirm:
- [ ] Reader intent matches the listicle, how-to, definition, or debate pattern
- [ ] Why the topic matters (practical, not abstract)
- [ ] Relevance to the reader's goal is clear
- [ ] Journey teaser names sections or outcomes
- [ ] Journey bullets link to real anchors in full output for existing posts
- [ ] 2–4 **bold** hooks and at most one _italic_ aside
- [ ] Sentences are short; total length is tight
- [ ] No fabricated data or competitor claims