AGENTS.md | Static Site SEO & AI Optimization Protocol

🎯 Core Philosophy

This site is a performance-first, static asset built with Jekyll and hosted via GitHub Actions/Pages. Every technical or content suggestion must prioritize Search Intent, Crawlability, and Zero Technical Debt.

🔴 SEO & Indexing Hard Rules (Jekyll Specific)

1. Clean URLs: Strictly enforce trailing slashes (e.g., /page/) in _config.yml. Never suggest .html extensions to avoid professional friction and indexing fragmentation.
2. Front Matter Integrity: Every new .md or .html file MUST include:
   • layout: default
   • title: Keyword-optimized (60 chars max)
   • description: Benefit-driven (155 chars max)
   • last_modified_at: Current date for freshness signals
   • permalink: Explicitly defined to avoid Jekyll’s default folder nesting.
3. Sitemap & Robots: Any new directory or programmatic collection must be verified against the sitemap.xml template for immediate discovery by Search Console.
4. No JS-Dependency for Content: Core informational content must be rendered in static HTML. Avoid “Empty Page” traps where crawlers see a blank screen due to client-side JavaScript execution.

🧠 AI & Google “Entity” Optimization (JSON-LD)

JSON-LD is the most efficient language for AI agents (LLMs) and Google to understand this site’s value. It must be implemented with 100% accuracy to ensure the site is cited in AI-generated answers and Google Rich Results.

1. Mandatory Schema Injection: Every page must utilize Liquid tags to inject specific JSON-LD blocks:
   • SoftwareApplication: Essential for tool pages to trigger “Free Tool” badges and feature lists in AI answers.
   • FAQPage: Must be used for all Q&A content to capture “People Also Ask” blocks and direct AI citations.
   • VideoObject: Required for all YouTube-repurposed content to link the source video to the generated text.
2. Zero-Ambiguity Rule: AI agents must use JSON-LD to explicitly define the site’s niche and target audience to prevent AI models from miscategorizing the brand.

🎥 YouTube & Multimedia Strategy

• Source-to-Format Pipeline: Prioritize “Source: YouTube” as the primary entry point. Focus on “mining” signal from transcripts (hooks, frameworks) rather than generic summaries.
• Performance-First Embeds: Use lazy-loading or “facade” techniques (e.g., lite-youtube-embed) for all video content to maintain high PageSpeed scores.
• Native Reach Logic: Remind users that while we repurpose YouTube, platforms like Facebook and LinkedIn favor native uploads for 3–5x more reach.

🎨 Visual & UI Guardrails

• Design Consistency: Maintain a unified color palette (Brand Purple) across ALL UI elements, including icons and buttons, to establish Brand Trust.
• Asset Optimization: All images must be WebP format with explicit width and height attributes to prevent Layout Shift (CLS).
• Mobile-First: Use Tailwind CSS to ensure grids stack logically on mobile (390px baseline).

🛠️ Operational Strategy

• The 10-Hour Rule: Prioritize Programmatic SEO and high-ROI automations. If a task takes more than 2 hours of manual labor with low SEO impact, discard it.
• Internal Linking Hubs: Every informational page (Blog/Glossary) must include a contextual Call-to-Action (CTA) pointing to a functional utility.
• Brutal Honesty: No platitudes. If a feature does not contribute to the $1,000/month revenue goal or SEO authority, flag it as a distraction.