Index of every page on this site: llms.txt
All skills
Run it yourself

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.

  • 4 files
  • 18 KB
  • Updated 5 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/jokerhtml/needcraft-skills/ai-seo-discovery

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈97 tokens for metadata: the name and description. ≈2.9k when used: this file. ≈1.3k more on demand in 2 files.

Description uses 4.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈386 characters, or 4.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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)

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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 90f40b1. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 5 days ago
Other metadata
metadata
{
  "version": "1.0.0",
  "date": "2026-11-16",
  "author": "Muhammad Saad Ranjha / NeedCraft"
}

README badge

README badge for jokerhtml/needcraft-skills/ai-seo-discovery