Purpose
Take an existing help or documentation article and make it discoverable in search — mapping the right keywords to real support queries, restructuring headings around how users actually search, and rewriting metadata so the article earns clicks. Solves the problem of high-quality support content that solves the user's problem but never surfaces when they search for it.
When to Use
Invoke this skill when the user asks to:
- Optimize a help center or knowledge base article for search
- Improve search rankings for support or documentation content
- Rewrite meta descriptions and title tags for help articles
- Fix heading structure or keyword targeting in existing docs
- Prepare a help article to capture organic "how to" and troubleshooting queries
- Audit a knowledge base page for on-page SEO gaps
Inputs Required
Before starting, collect:
- Article content: The full existing help article text (or URL/paste of the body)
- Product/feature: The SaaS product and specific feature the article covers
- Primary keyword or query: The main search phrase the article should rank for (if unknown, note it — the skill will propose one)
- Audience: Who reads this — end users, admins, developers, or a mix
- Existing metadata: Current title tag and meta description, if any
- Related articles: Titles/URLs of other help content available for internal linking
- Search Console data: Any current impressions, clicks, or queries the article already receives (optional)
If the primary keyword is missing, the skill will infer one from the article and product, flag it explicitly, and proceed.
Instructions
Step 1: Search Intent & Query Mapping
Classify the article's job and the searches it should intercept.
- Determine the dominant intent: informational ("how does X work"), troubleshooting ("X not working / error Y"), task/how-to ("how to do X"), or reference ("X settings / X requirements").
- Propose a primary keyword (the single phrase to optimize for) and confirm or replace the one provided.
- Build a secondary keyword set of 4–8 phrases: question variants, error-message strings, synonyms, and long-tail modifiers real users type. For support content, prioritize verbatim error text and "why won't/can't" phrasings.
- Note the searcher's likely state: are they mid-task, blocked by an error, or evaluating before buying? This shapes tone and heading order.
Step 2: Title Tag Optimization
Rewrite the browser/SERP title (target 50–60 characters).
- Lead with the primary keyword, front-loaded.
- Match the intent: how-to titles start with "How to…"; troubleshooting titles include the error or problem; reference titles name the setting.
- Include the product name only if it adds click value or if brand-qualified searches are common; otherwise keep it lean for keyword room.
- Provide 2 title options with a one-line rationale for the recommended pick.
Step 3: Meta Description Rewrite
Write a meta description (target 140–155 characters).
- Include the primary keyword naturally within the first 120 characters.
- State the specific outcome the reader gets ("Learn how to reset your API key in three steps") — not a vague summary.
- Add a subtle click driver: the step count, the resolution promise, or "no support ticket needed."
- Provide 2 options and mark the recommended one.
Step 4: Heading Structure Restructure
Rebuild the H1–H3 hierarchy around search intent.
- One H1 containing the primary keyword, phrased as the user would search or ask.
- H2s as questions or task phrases that map to secondary keywords — favor "How do I…", "Why is…", "What to do if…" phrasing for support content, since these match voice and featured-snippet queries.
- Ensure logical nesting (no H3 without a parent H2, no skipped levels).
- Recommend a short TL;DR or direct-answer block immediately under the H1 (40–55 words) engineered for featured snippets and instant resolution.
- Deliver the restructure as a before → after heading outline.
Step 5: On-Page Keyword & Body Optimization
Weave keywords in without degrading readability.
- Confirm the primary keyword appears in: H1, first 100 words, at least one H2, and naturally 2–4 more times in body (flag any keyword stuffing risk).
- Recommend adding an error-message or exact-phrase callout for troubleshooting articles so the page matches copied-and-pasted searches.
- Suggest formatting for snippet capture: numbered steps for how-to, a definition sentence for informational, a bulleted checklist for reference.
- Flag any passages to rewrite for clarity, and note where secondary keywords can be placed contextually.
Step 6: Internal Linking & Schema
Improve crawlability and rich-result eligibility.
- Recommend 3–6 internal links from the provided related articles, with descriptive anchor text using target phrases (not "click here").
- Recommend links into this article from higher-authority pages if applicable.
- Recommend applicable structured data: FAQPage schema for Q&A-format sections, HowTo schema for step-based tasks, or BreadcrumbList for knowledge base hierarchy — and note which applies here.
Step 7: Before/After Change Log
Summarize every change in a table: element (title tag, meta, H1, H2s, body keywords, internal links, schema), before state, after state, and the SEO rationale.
Output Format
- Structure: Sequential sections following the 7 steps, ending with the change-log table
- Length: 800–1,100 words
- Format: Structured document — prose for analysis, tables for title/meta options and the change log, an indented outline for the heading restructure
- Sections: Search Intent & Keyword Map → Title Tag (2 options) → Meta Description (2 options) → Heading Restructure (before/after outline) → Body Keyword Recommendations → Internal Linking & Schema → Before/After Change Log
- Tone: SEO specialist — precise, standards-driven, no fluff; every recommendation tied to a searcher behavior or ranking factor
Quality Checklist
Before delivering output, verify:
- [ ] Title tag options are within 50–60 characters and lead with the primary keyword (count them)
- [ ] Meta description options are within 140–155 characters with the keyword in the first 120 (count them)
- [ ] The heading outline has exactly one H1 and no skipped heading levels
- [ ] The secondary keyword set contains 4–8 phrases, including at least one question variant
- [ ] A specific schema type is recommended with a reason it applies to this article
- [ ] The change log lists a before and after state for every element modified
Notes
- Support content wins featured snippets more easily than blog content because searchers want a single direct answer — the TL;DR block is often the highest-ROI change.
- For troubleshooting articles, exact error-message text is the highest-intent keyword you can target; users paste errors verbatim into search.
- Never sacrifice resolution clarity for keyword density — a help article that ranks but doesn't solve the problem generates support tickets anyway.
- If the article covers multiple distinct tasks, recommend splitting it: one intent per URL almost always outranks a combined page.
How to use this skill
This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.
Installing in Claude Code:
~/.claude/skills/<folder-name>/SKILL.md— auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)<your-project>/.claude/skills/<folder-name>/SKILL.md— auto-loads only when working in that project (recommended for project-specific skills)
Restart Claude Code or open a new session to register.
Using in Claude.ai, ChatGPT, Gemini, or other AI tools:
- Drag this file into a new chat, or copy and paste its contents
- Send your task or request as your next message — the AI will apply the skill where it fits
For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills