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 GitHubMCP 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-Agent1 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
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.
| Rule | Name | What It Does |
|---|---|---|
| 1 | 40-Word Featured Snippet | Limits answers to 40 words to trigger featured snippets |
| 2 | Answer Boolean Questions | Starts boolean answers with "Yes" or "No" before elaborating |
| 3 | Answer Type/Listing Questions | Structures listing responses with clear formatting |
| 4 | Author Rules | Avoids "if" at start, minimizes "also", statements before conditions |
| 5 | Avoid Analogies | Replaces all comparisons with direct, factual statements |
| 6 | Avoid Confusing Users & Bots | Restates info directly instead of "As stated before..." |
| 7 | Avoid Coreference Errors | Ensures every pronoun clearly references a specific entity |
| 8 | Avoid Everyday Language | Uses formal and professional diction only |
| 9 | Avoid Linking to Citations | Mentions sources in text without outbound links |
| 10 | No Product Promotion | Keeps informational content unbiased |
| 11 | Semantic Triples | Structures info as Subject + Special Fact + Main Information |
| 12 | Avoid Unnecessary Sentences | Combines related info to minimize token consumption |
| 13 | Be Certain | Uses definite, factual statements instead of possibility language |
| 14 | Be Specific | Uses exact counts and categories, not vague descriptors |
| 15 | Verb Context | Matches verbs to semantic signals (increase/improve/develop) |
| 16 | Cite Authoritative Sources | Cites sources before statements with "According to..." format |
| 17 | Consistent Declarations | Maintains consistent stance across all webpages |
| 18 | Consistent Style | Uses uniform tone across all documents and platforms |
| 19 | Consistent Part of Speech | Uses same word role at start of every list item |
| 20 | Content Length | As 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.
| Rule | Name | What It Does |
|---|---|---|
| 21 | Boolean Questions Format | Reinforces "Yes/No" + supporting evidence with sources |
| 22 | Context Vector | Creates logical flow from H1 to the last heading |
| 23 | Cut the Fluff | Deletes all contextless words and filler |
| 24 | Discourse Integration | Optimizes logical connections between sentences/sections |
| 25 | Perspective Richness | Adds diverse perspectives after factual answers |
| 26 | Entity Attributes | Includes relevant entities and attribute values for context |
| 27 | Entities Over Keywords | Focuses on entity association, not keyword insertion |
| 28 | Avoid Entity Stuffing | Prioritizes attributes by Prominence, Relatedness, Popularity |
| 29 | Evidence Variations | Incorporates statistical, anecdotal, scientific, and expert evidence |
| 30 | Factual Sentences | Uses objective, verifiable, clear, and direct statements |
| 31 | Content Originality | Requires genuine expert writing, not rephrasing |
| 32 | Semantic SEO Framework | Applies principles from 3,000+ Google patents research |
| 33 | Examples After Plurals | Follows every plural noun with specific examples |
| 34 | Subject-Predicate-Object | Structures sentences using semantic triples |
| 35 | Content Types | Maintains Main, Supplementary, and Ads content balance |
| 36 | Key Terms → Title & H1 | Connects key terms to title, H1, and topical map |
| 37 | Long-Form Answer Format | Uses definitions, entity signifiers, and qualifiers |
| 38 | No Context Breaking | Keeps related details within one paragraph |
| 39 | Logical Information Graph | Uses simple transitions, builds on previous points |
| 40 | Anchor Text Matching | Matches anchor text with target page's title |
| 41 | Tense & Modality Matching | Matches tenses and modal verbs between Q&A |
| 42 | Study Citations | Uses "A [Year] study at [Org] found that..." format |
| 43 | Information Density | Maximizes info per webpage, section, paragraph, sentence |
| 44 | Clarity & Precision | Uses Subject + Verb + Object/Modifier structures |
| 45 | Subordinate Text | Matches 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.
| Rule | Name | What It Does |
|---|---|---|
| 46 | Parts of Speech | Ensures correct grammatical role for each word |
| 47 | User Perspective Richness | Adds perspectives for different user types |
| 48 | "If" Statements Second | States action first, then condition |
| 49 | Prioritize Attributes | Matches answer attributes to interrogative signals |
| 50 | Safe Answers | Provides comprehensive answers with multiple evidence types |
| 51 | Remove Contextless Words | Eliminates filler like "basically", "essentially" |
| 52 | Relevance Configuration | Restructures entity descriptions per query context |
| 53 | N-Gram Consistency | Uses same key phrases at document start and end |
| 54 | Ontology & Taxonomy | Connects entities through shared attributes and hierarchy |
| 55 | Short-Form Questions | Prefers short questions; splits long into H2/H3 |
| 56 | Bold the Answer | Bolds the answer part, not the search term |
| 57 | Single Macro Context | Maintains one overarching theme per page |
| 58 | Complete Topic Coverage | Covers every detail, including gaps in competitor content |
| 59 | Table Context | Defines table contents and context before presenting data |
| 60 | Answer Immediately | Answers the question first, then elaborates |
| 61 | Question Headings | Converts headings to question format for retrieval |
| 62 | Truth Ranges | Provides min-to-max ranges when data varies across sources |
| 63 | Unique N-Grams | Uses unique phrase combinations instead of generic phrases |
| 64 | Abbreviations | Full term + abbreviation in parentheses on first mention |
| 65 | Diverse Units | Includes multiple measurement unit systems |
| 66 | Numeric Values | Uses specific numbers, not vague quantifiers |
| 67 | Ordered & Unordered Lists | Uses lists for structured, snippet-optimized content |
| 68 | Short Sentences | One piece of information per sentence |
| 69 | Dependency Trees | Keeps dependency trees short for clarity |
| 70 | Research Citations | Cites universities and studies with specifics |
| 71 | Vocabulary Richness | Uses 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