seo-apply

name	seo-apply
description	Apply targeted SEO improvements to a finished article or tutorial without changing its tone or voice. Reads this week's keyword clusters from the Notion SEO drops database (generated by the weekly SEO agent), matches relevant clusters to the piece, then makes surgical changes only — frontmatter, one bridge paragraph, one internal link, and an optional FAQ for tutorials. Does not rewrite sections or stuff keywords throughout the body.
compatibility	Designed for Claude Code. Requires Notion token in ~/claude-workspace-automation/.env as NOTION_TOKEN. SEO keyword data must already exist in the Notion SEO drops DB (run the weekly SEO agent first if it hasn't run this week).

Overview

The weekly SEO agent (~/Lablab-AI/ai-seo-agent-tutorials-articles/agent/weekly_seo_agent.py) runs every Monday and posts keyword clusters to Notion. Each cluster names the exact Google queries to target and which pages they apply to.

This skill reads those clusters, identifies what's relevant to the piece being edited, and applies the minimum changes needed. The article's voice, structure, and tone are preserved — only the SEO surface layer is touched.

Notion SEO drops DB: 3425a26f-4693-81d7-8fc6-ee99cfffc9f4 Notion token: ~/claude-workspace-automation/.env → NOTION_TOKEN

---

Steps

1. Identify the piece

Confirm with the user (if not already clear):

• File path of the article or tutorial
• Content type: article (blog post) or tutorial

Read the full file.

2. Fetch this week's SEO clusters from Notion

Load the Notion token:

grep NOTION_TOKEN ~/claude-workspace-automation/.env

Query the SEO drops DB for the most recent weekly drop (the page titled "SEO Weekly Drop — [most recent Monday]"):

• DB ID: 3425a26f-4693-81d7-8fc6-ee99cfffc9f4
• API: GET https://api.notion.com/v1/databases/3425a26f-4693-81d7-8fc6-ee99cfffc9f4/query
• Sort by Week descending, take the first result
• Read the page blocks to extract all clusters (cluster name, keywords, suggested title, action, reasoning, article_urls)

If the DB returns no results or today is not Monday, note this to the user and proceed using the keywords from SEO_GUIDELINES.md Tier 1–2 as fallback.

3. Match clusters to this piece

Compare the article content and topic against the fetched clusters:

Match criteria (any one is sufficient):

• The article URL (if published) appears in a cluster's article_urls
• The article topic overlaps with a cluster's keywords or cluster_name
• The cluster's suggested_title aligns with this article's subject

Select up to 2 matching clusters. If no clusters match, use Tier 1 keywords from SEO_GUIDELINES.md as the target keywords.

Note the matched keywords — these are what you'll work with in the next steps.

4. Plan the changes

Before editing, list exactly what you will change and get implicit approval by showing the plan:

Proposed SEO changes for [filename]:
1. Frontmatter title: [current] → [new]
2. Frontmatter description: [current] → [new]
3. Bridge paragraph: insert after paragraph 1 of the intro (3 sentences)
4. Internal link: add to [specific sentence] in [section name]
5. FAQ section: [3 questions] before the footer  ← tutorials only

Do not proceed to edits until the plan is clear. If any change looks wrong (e.g. the title rewrite feels forced or off-brand), flag it and ask.

5. Apply the changes

Make each change surgically. Rules for each type:

Frontmatter title

• Include the primary keyword naturally — do not bolt it on awkwardly
• Keep the article's original angle; don't pivot the title to be about hackathons if the piece isn't about hackathons
• Max 65 characters
• If the current title already contains the primary keyword, leave it unchanged

Frontmatter description

• Include "AI hackathon" or the primary keyword in the first 50 characters
• Target 150–160 characters
• Preserve the description's existing value proposition — only add the keyword, don't rewrite the whole thing
• If adding the keyword makes it forced or unnatural, put it later in the sentence

AI Hackathon Bridge paragraph (articles and tutorials)

• Insert after the first paragraph of the introduction — not before it, not at the top
• 2–3 sentences only
• Explain why this topic is useful in AI hackathon contexts — must be genuinely true for this subject
• Include one internal link: [upcoming AI hackathons](https://lablab.ai/event) or [global AI hackathons](https://lablab.ai/ai-hackathons)
• Do not add this paragraph if the article is a news recap, announcement, or opinion piece — it only fits technical tutorials and how-to articles

Internal link (body)

• Add one additional internal link to /ai-hackathons or /event somewhere in the body, using natural anchor text
• Only if the article body has a sentence where this fits without forcing it
• Skip if the bridge paragraph already contains the only sensible placement

FAQ section (tutorials only)

• Add before the footer or final "Next Steps" section
• 3–5 questions
• At least 2 must be tutorial-specific (not generic hackathon questions)
• At least 1 must target a long-tail keyword from the matched cluster
• Format:

  ## Frequently Asked Questions
  
  **Q: [question]**
  [1–3 sentence answer]
  

6. What NOT to change

• Do not rewrite existing body paragraphs to inject keywords
• Do not add "AI hackathon" mentions throughout the text
• Do not change section headings unless the current heading is actively bad for SEO and the change is natural
• Do not alter code blocks, technical instructions, or numbered steps
• Do not change the article's voice, tone, or confidence level
• Do not add a FAQ to news recaps or opinion pieces

7. Report changes

After editing, show a summary:

SEO changes applied to [filename]:

Title: [before] → [after]   (or "unchanged")
Description: [before] → [after]   (or "unchanged")
Bridge paragraph: added after intro paragraph 1   (or "skipped — news recap")
Internal link: added in [section]   (or "skipped — no natural placement")
FAQ: [N questions added]   (or "skipped — article, not tutorial")

Target keywords: [list]
Matched cluster: [cluster name] (or "fallback: SEO_GUIDELINES.md Tier 1")

Do not commit. Leave that for the user or the publish-check flow.