---
name: ai-seo-discovery
description: >-
  Find the exact words your audience already searches for and match each post to one searchable phrase plus its intent, with platform-native titles, captions, hashtags, and alt text — without invented keyword volumes or guaranteed-ranking claims. Use before drafting any post, when choosing a tutorial angle or Top 5 topic, and when reviewing a post after it publishes.
license: MIT
metadata:
  version: 1.0.0
  date: 2026-11-16
  author: Muhammad Saad Ranjha / NeedCraft
title: ai-seo-discovery
canonical_url: https://skilld.dev/gh/jokerhtml/needcraft-skills/ai-seo-discovery
last_updated: 2026-11-17T10:30:38.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [examples/per-post-seo-output.md](https://skilld.dev/api/skills-raw/jokerhtml/needcraft-skills/ai-seo-discovery/examples/per-post-seo-output.md), [LICENSE](https://skilld.dev/api/skills-raw/jokerhtml/needcraft-skills/ai-seo-discovery/LICENSE), [README.md](https://skilld.dev/api/skills-raw/jokerhtml/needcraft-skills/ai-seo-discovery/README.md).
>
> If the user asked to install this Skill, run `npx skilld install jokerhtml/needcraft-skills/ai-seo-discovery`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/ai-seo-discovery`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jokerhtml/needcraft-skills/ai-seo-discovery) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/ai-seo-discovery`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/ai-seo-discovery --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/ai-seo-discovery --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# SEO & Search Discovery

## What this skill is

A method for matching each post to the words the audience already searches for — one searchable phrase plus its intent per post — and producing the per-post SEO output that makes the post findable, without fake ranking hacks, invented keyword volumes, or guaranteed-ranking claims.

Who it is for: creators and small teams publishing tutorials, comparisons, and how-to content who want their posts found by search, not just by the feed.

## How to use this skill

1. Start from the audience problem, not a keyword tool (see Process).
2. Generate variants, check the phrase natively on the platforms where the post will live, and pick one primary phrase.
3. Write the per-post SEO output block and paste it into the plan before drafting.
4. After publishing, run the post-publication review at 24h / 72h / 7d and record what actually happened.

## Rules (hard)

- **Never invent keyword volume, difficulty, or ranking data.** If no tool measured it, say "unmeasured — chosen from audience wording" and do not quote a number.
- **Never sell a ranking hack, secret ranking factor, or guaranteed inclusion in AI answers.** Foundational SEO still matters; there is no shortcut past it.
- **One primary phrase per post.** Secondary phrases only if genuinely relevant (3–8 max).
- **Hashtags 1–3 where they genuinely help, never stuffed.** LinkedIn 0–1. Instagram up to 5.
- **Every claim about a platform's search behaviour must trace to an official source** (listed under Official references) **or be labelled as your own observation.**
- **No guaranteed outcomes.** Never promise a ranking, a view count, or an AI-answer inclusion.

## Learning modules

1. **Keyword + search intent:** audience wording, query variations, questions, comparisons ("best X for Y"), long-tail queries, content gaps. Intent types: learn / compare / do / buy / troubleshoot.
2. **Platform-native search:** Instagram search, YouTube Search and Studio, Pinterest trends and search, Threads/X topical language. If a platform's search tool is unavailable to you (no account, paywalled, or blocked), record "unavailable" — never claim a check you did not do.
3. **YouTube SEO:** topic intent, title clarity, thumbnail promise, description, chapters, spoken keywords, captions; tags only where genuinely useful.
4. **Instagram/Facebook:** discoverable phrasing, accurate captions, topic consistency, original media, alt text, compliant hashtags.
5. **Pinterest SEO:** keyword-led pin title (keyword in the first 40 of 100 characters — only about the first 40 show in the feed), natural description up to 800 characters, vertical 1000×1500 asset, destination relevance, board context.
6. **X/Threads:** clear topical language, strong first line, concise context, useful source links, conversation relevance.
7. **Web/Google SEO:** people-first content, helpful structure, original analysis, descriptive titles, technical accessibility, Search Console measurement (free service — set it up on your own site).
8. **AI-search literacy:** foundational SEO still matters; no fake "GEO/AEO" hacks.
9. **Optimisation after publish:** Search Console plus platform analytics — queries, pages/posts, CTR, retention, saves, shares, clicks, conversions.

## Process

1. **Start from the audience problem**, not a keyword tool. Write the question a beginner would type, in their own words.
2. **Generate variants:** question form, comparison form ("X vs Y"), "best X for Y", "how to X with Y", task + tool form.
3. **Check the phrase natively:** YouTube Search autocomplete, Pinterest search suggestions, Instagram search, and Google Search Console queries for your own site (only for a site you own). Record what you actually saw and the date.
4. **Pick one primary phrase** — the variant with the clearest intent match plus the most native evidence — and 3–8 secondaries.
5. **Place it:** in the first line of the caption/post, in the on-screen headline, and in the opening spoken phrase for video. Placement rules that are verified vs house practice:
   - **Pinterest pin title, first 40 characters** — verified: only about the first 40 characters of a 100-character title show in the feed (Pinterest Help, pin specs). Put the keyword there.
   - **Instagram, first ~125 characters** — house practice, not an official figure: Instagram publishes no fold point, but roughly the first two lines show before "more" on most phones. Put the point in the first line.
   - **Everywhere else:** no published fold point exists. The house rule is the same — the primary phrase goes in the first line, because the first line is what every feed shows.
6. **Write alt text** for every meaningful image; accurate captions/subtitles for video.
7. **Verify every link destination** before delivery; record the check date.

## Tie-break rule (when variants conflict)

When two or more phrase variants look equally good, decide in this order — no step is skipped, and the first step that separates them wins:

1. **Intent match.** The variant whose intent (learn / compare / do / buy / troubleshoot) matches the post's actual content wins. A "how to" post never takes a "best X" phrase.
2. **Native evidence.** The variant you actually saw suggested or returned in the platform's own search wins over one you only imagined.
3. **Specificity.** The more specific variant wins when intent and evidence tie ("grow tomatoes on a balcony" beats "gardening tips").
4. **Shorter wins.** If still tied, take the shorter phrase — it fits more placements.
5. **Record the loser.** Write the rejected variant and the reason in the SEO output block. If the winner underperforms at the 7-day review, the loser is the first thing you test.

## Per-post SEO output (required — paste into every plan)

- Primary search phrase + reader intent (learn / compare / do / buy / troubleshoot).
- 3–8 secondary phrases or natural variants.
- Platform-native title/headline + caption/description.
- On-screen headline + opening spoken phrase (video days).
- 1–3 hashtags where they genuinely help.
- Alt text (images) / captions (video).
- Verified link destination + source references.
- Post-publication review note (what to check at 24h / 72h / 7d).
- Tie-break note: which variant lost and why (when applicable).

## Worked example (labelled example)

The block below is a complete SEO output for an invented example post. The post was not published; the phrases were chosen from audience wording, not measured with a keyword tool, and no volumes are claimed. Use it as a format reference, not as data.

**Example post:** a carousel teaching beginners to grow tomatoes on a balcony.

- **Primary search phrase:** "grow tomatoes on a balcony" — intent: **do** (the reader wants to grow them).
- **Secondary phrases (5):** "balcony tomato growing", "growing tomatoes in pots", "tomato plants for small spaces", "when to plant tomatoes", "balcony vegetable garden".
- **Platform-native title/headline:** "Grow Tomatoes on a Balcony (Even With No Garden)".
- **Caption/description (Instagram):** "No garden? You can still grow tomatoes on a balcony — this carousel shows the pot, the soil, and the watering routine, step by step. No experience needed."
- **On-screen headline:** "Tomatoes, on a balcony."
- **Opening spoken phrase (video version):** "Here's how to grow tomatoes on a balcony — even with no garden."
- **Hashtags (2):** #BalconyGarden #GrowYourOwn
- **Alt text:** "Carousel slide showing a tomato plant in a pot on a balcony railing, with a watering can beside it."
- **Verified link destination:** the growing guide the post is based on — check it on the day you publish and record the date here. No link is claimed until you have opened it.
- **Tie-break note:** "growing tomatoes in pots" lost on specificity to the primary phrase; it becomes a secondary phrase and the subject of a later post.
- **Post-publication review note:** at 24h check saves and profile visits; at 72h check Search Console queries for the primary phrase (own site only); at 7d compare against the previous tutorial post and record whether the primary phrase drove any search traffic. No ranking is promised.

A standalone copy of this worked example is in `examples/per-post-seo-output.md`.

## Official references (re-check before applying any time-sensitive rule)

- Google Search Central — helpful content: https://developers.google.com/search/docs/fundamentals/creating-helpful-content
- Google Search Central — AI-optimization guide: https://developers.google.com/search/docs/fundamentals/ai-optimization-guide
- Google Search Central — gen-AI content guidance: https://developers.google.com/search/docs/fundamentals/using-gen-ai-content
- YouTube Help — Shorts search/discovery: https://support.google.com/youtube/answer/11914225
- YouTube Help — content performance for recommendations: https://support.google.com/youtube/answer/16559650
- Instagram Creators best-practices hub (Meta): https://about.fb.com/news/2024/10/best-practices-education-hub-creators-instagram/
- Google Search Console (free service): https://support.google.com/webmasters/answer/9128668
- Pinterest Help — pin specs (title 100 characters, description 800): https://help.pinterest.com

## Character limits that matter for SEO placement (last checked 16 November 2026)

| Platform | Field | Limit |
|---|---|---|
| Pinterest | Pin title | 100 characters; only about the first 40 show in the feed |
| Pinterest | Pin description | 800 characters |
| Instagram | Caption | 2,200 characters |
| X | Post (standard account) | 280 characters, weighted |
| Threads | Post | 500 characters |
| LinkedIn | Post | 3,000 characters |

Verify in the platform's own composer or docs before publishing.

## Post-publication review

- **24h:** saves, shares, comments, profile visits — did the hook and the first line work?
- **72h:** Search Console queries for your own site (if the post links there); platform search impressions where readable.
- **7d:** compare against the previous post on the same topic. Record: primary phrase, what ranked or surfaced (if anything), what did not, and the next test (usually the tie-break loser).
- If a platform's analytics are unavailable to you (paywalled, blocked, or no account), record "unavailable" rather than inventing data.

## Re-check cadence

- **On publishing day:** re-open every official reference and link cited in the SEO output block; correct the copy if anything changed.
- **Monthly:** re-check the character limits table and the official references; update the "last checked" date.
- **When a placement rule stops working:** re-check the platform's own docs first — a silent feed or search change is the most common cause. Record the change and the date; do not keep quoting the old rule.

## Known limits

- This skill finds audience wording and places it well. It does not measure keyword volume, difficulty, or ranking — and it never claims to. Any volume figure needs a real keyword tool and a named source.
- The Instagram "~125 characters" fold point is house practice, not an official figure: Instagram publishes no fold point. The Pinterest "first 40" figure is documented in Pinterest's own specs.
- Search behaviour differs by account, device, and region. A phrase that surfaces for one reader may not surface for another; the 7-day review is how you learn what actually worked.
- No paid SEO tool is required for this method. The honest $0 stack is Search Console (measurement, your own site only) plus native search checks — never present AI-generated keyword volumes as measured data.
