convez.ai
MCP ServerEscrita & ConteúdoIntermediário
hasnainkhan8532

Semantic SEO Writer - AI Agent Skill

hasnainkhan8532/Semantic-SEO-Writer-AI-Agent

71 regras de SEO semântico para agentes de IA gerarem conteúdo otimizado

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que integra 71 regras de SEO semântico baseadas em pesquisa para otimizar conteúdo web gerado por agentes de IA. Funciona com Claude, Copilot, Gemini e Cursor, incluindo integração nativa com Ubersuggest para dados de SEO em tempo real.

Instalação

$npx convez-ai hasnainkhan8532/Semantic-SEO-Writer-AI-Agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
7
Forks
0
Acompanhando
1
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Otimizar artigos de blog com regras de SEO semântico automaticamente
  • Gerar landing pages e páginas de projeto com estrutura semanticamente rica
  • Integrar análise de concorrência e volume de palavras-chave via Ubersuggest antes da redação
  • Padronizar qualidade de conteúdo em pipelines de múltiplos clientes

Veredito

Ferramenta sólida para quem cria conteúdo com IA e precisa garantir conformidade com boas práticas de SEO semântico. A integração com Ubersuggest agrega valor real ao trazer dados de mercado para o contexto de geração, embora dependa da qualidade das prompts companion para pleno potencial.

README

A tradução para o português deste README ainda está na fila.


What Is This?

This repository contains a portable AI agent skill that enforces 71 semantic SEO rules whenever an AI coding agent writes, edits, reviews, or optimizes web content. It also includes 3 companion prompts that structure the content generation workflow for blog posts, project pages, and data-driven SEO articles.

Most AI agents produce generic text that lacks the semantic depth and structural precision modern search engines require. This skill solves that problem by packaging research-backed writing rules, grounded in Google patents, Named Entity Recognition (NER), and proven case studies, into a format any compatible AI agent can load and execute on demand.

✨ Key Feature: Ubersuggest MCP Integration

This toolkit now includes native integration for Ubersuggest via MCP (Model Context Protocol). By using the dedicated ubersuggest-prompt-blog.md, your AI agent can pull live SEO data (keyword volume, domain authority, backlink benchmarks, and SERP competitor analysis) directly into its context before generating content, ensuring every article is grounded in real-time search metrics.

Who Is This For?

  • Content creators who use AI agents (Copilot, Claude, Cursor, Gemini) to write blog posts, articles, or landing pages
  • SEO specialists who want to enforce consistent semantic SEO rules across their content pipeline
  • Developers building AI-powered content workflows who need a structured set of optimization rules
  • Agencies managing content for multiple clients who need standardized quality controls

The 71 Rules - Three Categories

The rules are organized into 3 categories. Each category addresses a distinct layer of content quality that search engines evaluate during indexing and ranking.

Category 1: Content Optimization (Rules 1–20)

Enforces precision in sentence structure, citation format, featured snippet optimization, and content tone.

RuleNameWhat It Does
140-Word Featured SnippetLimits answers to 40 words to trigger featured snippets
2Answer Boolean QuestionsStarts boolean answers with "Yes" or "No" before elaborating
3Answer Type/Listing QuestionsStructures listing responses with clear formatting
4Author RulesAvoids "if" at start, minimizes "also", statements before conditions
5Avoid AnalogiesReplaces all comparisons with direct, factual statements
6Avoid Confusing Users & BotsRestates info directly instead of "As stated before..."
7Avoid Coreference ErrorsEnsures every pronoun clearly references a specific entity
8Avoid Everyday LanguageUses formal and professional diction only
9Avoid Linking to CitationsMentions sources in text without outbound links
10No Product PromotionKeeps informational content unbiased
11Semantic TriplesStructures info as Subject + Special Fact + Main Information
12Avoid Unnecessary SentencesCombines related info to minimize token consumption
13Be CertainUses definite, factual statements instead of possibility language
14Be SpecificUses exact counts and categories, not vague descriptors
15Verb ContextMatches verbs to semantic signals (increase/improve/develop)
16Cite Authoritative SourcesCites sources before statements with "According to..." format
17Consistent DeclarationsMaintains consistent stance across all webpages
18Consistent StyleUses uniform tone across all documents and platforms
19Consistent Part of SpeechUses same word role at start of every list item
20Content LengthAs short as possible, as long as necessary

Category 2: Semantic SEO & Structure (Rules 21–45)

Governs content architecture through context vectors, entity-attribute prioritization, discourse integration, and tense matching.

RuleNameWhat It Does
21Boolean Questions FormatReinforces "Yes/No" + supporting evidence with sources
22Context VectorCreates logical flow from H1 to the last heading
23Cut the FluffDeletes all contextless words and filler
24Discourse IntegrationOptimizes logical connections between sentences/sections
25Perspective RichnessAdds diverse perspectives after factual answers
26Entity AttributesIncludes relevant entities and attribute values for context
27Entities Over KeywordsFocuses on entity association, not keyword insertion
28Avoid Entity StuffingPrioritizes attributes by Prominence, Relatedness, Popularity
29Evidence VariationsIncorporates statistical, anecdotal, scientific, and expert evidence
30Factual SentencesUses objective, verifiable, clear, and direct statements
31Content OriginalityRequires genuine expert writing, not rephrasing
32Semantic SEO FrameworkApplies principles from 3,000+ Google patents research
33Examples After PluralsFollows every plural noun with specific examples
34Subject-Predicate-ObjectStructures sentences using semantic triples
35Content TypesMaintains Main, Supplementary, and Ads content balance
36Key Terms → Title & H1Connects key terms to title, H1, and topical map
37Long-Form Answer FormatUses definitions, entity signifiers, and qualifiers
38No Context BreakingKeeps related details within one paragraph
39Logical Information GraphUses simple transitions, builds on previous points
40Anchor Text MatchingMatches anchor text with target page's title
41Tense & Modality MatchingMatches tenses and modal verbs between Q&A
42Study CitationsUses "A [Year] study at [Org] found that..." format
43Information DensityMaximizes info per webpage, section, paragraph, sentence
44Clarity & PrecisionUses Subject + Verb + Object/Modifier structures
45Subordinate TextMatches first sentence under heading to heading format

Category 3: Advanced Techniques (Rules 46–71)

Distinguishes expert-level content through truth ranges, unique n-grams, vocabulary richness, and perspective balance.

RuleNameWhat It Does
46Parts of SpeechEnsures correct grammatical role for each word
47User Perspective RichnessAdds perspectives for different user types
48"If" Statements SecondStates action first, then condition
49Prioritize AttributesMatches answer attributes to interrogative signals
50Safe AnswersProvides comprehensive answers with multiple evidence types
51Remove Contextless WordsEliminates filler like "basically", "essentially"
52Relevance ConfigurationRestructures entity descriptions per query context
53N-Gram ConsistencyUses same key phrases at document start and end
54Ontology & TaxonomyConnects entities through shared attributes and hierarchy
55Short-Form QuestionsPrefers short questions; splits long into H2/H3
56Bold the AnswerBolds the answer part, not the search term
57Single Macro ContextMaintains one overarching theme per page
58Complete Topic CoverageCovers every detail, including gaps in competitor content
59Table ContextDefines table contents and context before presenting data
60Answer ImmediatelyAnswers the question first, then elaborates
61Question HeadingsConverts headings to question format for retrieval
62Truth RangesProvides min-to-max ranges when data varies across sources
63Unique N-GramsUses unique phrase combinations instead of generic phrases
64AbbreviationsFull term + abbreviation in parentheses on first mention
65Diverse UnitsIncludes multiple measurement unit systems
66Numeric ValuesUses specific numbers, not vague quantifiers
67Ordered & Unordered ListsUses lists for structured, snippet-optimized content
68Short SentencesOne piece of information per sentence
69Dependency TreesKeeps dependency trees short for clarity
70Research CitationsCites universities and studies with specifics
71Vocabulary RichnessUses domain-specific terms and headword clusters

📖 Full details and examples for each rule are in the reference files inside semantic-seo-writer/references/.


Repository Structure

semantic-seo-writer-skill/
│
├── README.md                                    # ← You are here
├── LICENSE                                      # Proprietary license
├── .gitignore                                   # macOS / editor ignores
│
├── prompt-blog.md                               # SEO Blog Post Writing Prompt
├── prompt-project.md                            # SEO Project/Portfolio Page Prompt
├── ubersuggest-prompt-blog.md                   # SEO Blog Prompt + Ubersuggest MCP
│
├── semantic-seo-writer/                         # The AI Agent Skill
│   ├── SKILL.md                                 # Core skill definition (271 lines)
│   ├── references/
│   │   ├── content-optimization.md              # Rules 1-20, full details (342 lines)
│   │   ├── semantic-seo.md                      # Rules 21-45, full details (456 lines)
│   │   └── advanced-techniques.md               # Rules 46-71, full details (464 lines)
│   └── assets/
│       └── checklist.md                         # Quick-reference 71-rule checklist (86 lines)

Installation

Quick Start

Clone the repository and copy the skill + prompts into your AI agent's skills directory.

git clone https://github.com/hasnainkhan8532/Semantic-SEO-Writer-AI-Agent.git

VS Code - GitHub Copilot

# From your project root
mkdir -p .agents/skills/
cp -r semantic-seo-writer-skill/semantic-seo-writer .agents/skills/

Claude Code

# From your project root
mkdir -p .claude/skills/
cp -r semantic-seo-writer-skill/semantic-seo-writer .claude/skills/

Google Gemini (Antigravity / Gemini CLI)

# Global installation
mkdir -p ~/.gemini/config/skills/
cp -r semantic-seo-writer-skill/semantic-seo-writer ~/.gemini/config/skills/

# Or per-project
mkdir -p .gemini/skills/
cp -r semantic-seo-writer-skill/semantic-seo-writer .gemini/skills/

Cursor

# From your project root (or global config directory)
cp -r semantic-seo-writer-skill/semantic-seo-writer /path/to/cursor/skills/

Note: After installation, the AI agent will automatically discover and activate the skill when a content writing task matches the skill description. No manual activation is needed.


Companion Prompts

This repository includes 3 companion prompts designed to work alongside the skill. Each prompt embeds explicit rule references (e.g., "Rule 27", "Rule 41") and includes an inline quality checklist.

prompt-blog.md - SEO Blog Post Writing Prompt

Use this prompt to generate complete SEO-optimized blog posts. The prompt enforces:

  • Keyword strategy: 1 primary keyword + 3–9 secondary keywords
  • URL slug: max 4 words, no stop words, includes primary keyword
  • Blog metadata: title (50–60 chars), excerpt (300 chars), meta description (150–155 chars), tags, read time
  • Content structure: Introduction → Definition section → Main body → Code snippets (if applicable) → Conclusion
  • Heading hierarchy: strict H2–H6 with declarative headings (no questions)
  • Internal links: placeholder format [Internal Link: anchor text -> hasnainayaz.com/page]
  • Quality checklist: 22 verification items checked before output

How to use:

Paste the contents of prompt-blog.md into your AI agent, replacing [Insert your topic] with your blog topic.

prompt-project.md - SEO Project/Portfolio Page Prompt

Use this prompt to generate SEO-optimized portfolio or project case study pages. The prompt enforces:

  • Categories: select from E-Commerce, UI/UX Design, Business Website, Elementor, AI/ML, Agentic AI
  • Entity mapping: 5–10 entities with 2–3 attributes each, prioritized by Prominence, Relatedness, Popularity
  • Content sections: SEO Title → Meta Description → Overview (300–400 words) → Challenge & Solution (~400 words) → Conclusion (~300 words)
  • Quality checklist: 20 verification items

How to use:

Paste the contents of prompt-project.md into your AI agent, replacing [Insert your URL or Project Description] with your project details.

ubersuggest-prompt-blog.md - SEO Blog Prompt with Ubersuggest MCP

An enhanced version of the blog prompt that integrates Ubersuggest MCP tools for real-time SEO data research before content generation. This prompt executes:

  • Domain analysis: traffic overview, top pages, competitor identification
  • Keyword research: keyword overview, suggestions, SERP analysis, trend data
  • Content ideation: high-performing content angles and social sharing data
  • Backlink research: competitor backlink profiles and referring domains
  • Site audit: on-page SEO issue identification

The prompt generates a structured Research Summary before writing, including:

  • Primary keyword with search volume and SEO difficulty
  • Top 3 SERP competitors with domain authority
  • Content gaps not covered by competitors
  • Trending direction (rising, stable, declining)
  • Backlink benchmarks

Requirements: Ubersuggest MCP server must be configured in your AI agent's MCP settings.

How to use:

Paste the contents of ubersuggest-prompt-blog.md into your AI agent with Ubersuggest MCP enabled.
Replace [Insert your topic] and [Insert your domain] with your details.

How the Skill Works - Progressive Disclosure

The skill uses a 3-stage progressive disclosure architecture to keep the AI agent's context window efficient:

Stage 1 - Metadata (~100 tokens)
├── name: semantic-seo-writer
└── description: "Comprehensive SEO content writing..."
    ↓ Agent activates skill when task matches description

Stage 2 - Instructions (<5,000 tokens)
└── SKILL.md body loads, condensed summaries of all 71 rules
    ↓ Agent applies rules during content generation

Stage 3 - Resources (on demand)
├── references/content-optimization.md    → loaded when Rules 1–20 need detail
├── references/semantic-seo.md           → loaded when Rules 21–45 need detail
├── references/advanced-techniques.md    → loaded when Rules 46–71 need detail
└── assets/checklist.md                  → loaded during content review

Why this matters: The main SKILL.md stays under 300 lines. Detailed reference material (1,300+ lines) loads only when needed. This prevents context window overflow while keeping the full depth of 71 rules accessible.


Framework Foundation

The 71 rules are grounded in the Semantic SEO Framework, which is based on:

  • Extensive research across 3,000+ Google patents
  • Applied to 120+ websites with documented case studies

The framework emphasizes entity-based content optimization, context vectors, dependency tree management, and vocabulary richness, moving beyond traditional keyword-focused SEO toward semantic understanding.

📖 Learn more about the Semantic SEO framework and how these rules apply in practice: Semantic SEO Content Writing


Quick-Reference Checklist

A condensed checklist of all 71 rules is available at semantic-seo-writer/assets/checklist.md. Use it for quick content reviews:

# View the checklist
cat semantic-seo-writer/assets/checklist.md

The checklist is organized by category with checkboxes for each rule, ideal for pre-publish content audits.


Author

Hasnain Ayaz

  • 🌐 Website: hasnainayaz.com
  • 💼 SEO Specialist, Semantic Content Strategist, Web Developer

License

This project is licensed under a Proprietary License. See the LICENSE file for details.

You are free to:

  • View and read the repository contents for learning
  • Use the skill files in your own AI agent workflows (with attribution)
  • Fork the repository for personal, non-commercial use

You may not:

  • Redistribute, sell, or commercially distribute the work
  • Claim authorship or remove attribution notices
  • Create competing commercial products without permission

Ver o original no GitHub

Bom para

Relacionados