keploy-seo-audit 1.0.0

package/README.md

@@ -0,0 +1,55 @@
+# keploy-seo-audit
+
+A Claude Code skill that audits blog content against Keploy's SEO guidelines and generates a detailed Markdown report.
+
+## Install
+
+```bash
+npx keploy-seo-audit
+```
+
+That's it. Restart Claude Code after installing.
+
+## Usage
+
+Open Claude Code and type:
+
+```
+SEO audit this blog:
+
+Primary keyword: API testing
+Meta title: How to do API Testing
+Meta description: Learn API testing with examples...
+
+Blog content:
+---
+[paste your full blog here]
+---
+```
+
+Claude Code will generate a `seo-audit-report.md` in your current directory with:
+
+- ✅ / ❌ / ⚠️ status for every rule (56+ checks)
+- 🔴 Critical → 🟢 Low priority labels
+- Score out of 100
+- Action checklist of exactly what to fix
+
+## What gets audited
+
+1. AIO Optimization
+2. URL Structure
+3. Page Titles
+4. Blog/Hub Content Structure
+5. Headings
+6. Image Optimization
+7. Keywords
+8. Internal Linking
+9. External Links
+10. Meta Description
+11. Meta Title
+12. Instagram Carousel
+
+## Requirements
+
+- [Claude Code](https://claude.ai/code) installed
+- Node.js 14+

package/install.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'keploy-seo-audit';
+const SOURCE_DIR = path.join(__dirname, 'skill');
+const TARGET_DIR = path.join(os.homedir(), '.claude', 'skills', SKILL_NAME);
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+console.log('\n🚀 Installing Keploy SEO Audit skill for Claude Code...\n');
+
+try {
+  copyDir(SOURCE_DIR, TARGET_DIR);
+  console.log('✅ Skill installed successfully!');
+  console.log(`📁 Location: ${TARGET_DIR}`);
+  console.log('\n👉 Restart Claude Code and type:');
+  console.log('   "SEO audit this blog: [paste your blog]"\n');
+} catch (err) {
+  console.error('❌ Installation failed:', err.message);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "keploy-seo-audit",
+  "version": "1.0.0",
+  "description": "Install the Keploy SEO Audit skill for Claude Code — audits blog content against Keploy's SEO guidelines and generates a detailed .md report.",
+  "bin": {
+    "keploy-seo-audit": "./install.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "install.js",
+    "skill/"
+  ],
+  "keywords": [
+    "keploy",
+    "seo",
+    "audit",
+    "claude",
+    "claude-code",
+    "skill",
+    "content",
+    "blog"
+  ],
+  "author": "Keploy",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: keploy-seo-audit
+description: Audit blog or hub content against Keploy's official SEO content guidelines and generate a structured Markdown audit report. Use this skill whenever a user submits a blog post or article for SEO review, asks to "audit", "review", "check", or "score" their content, or wants to find what is missing or needs fixing. Trigger on phrases like "review my blog", "check this post", "SEO audit", "content review", "what's wrong with my article", or any time content is submitted alongside a request for feedback. Always produce a structured .md audit report — never just respond conversationally.
+---
+
+# Keploy SEO Audit Skill
+
+You are a strict SEO content auditor for Keploy. Your sole job is to review submitted content against Keploy's official SEO guidelines and produce a complete, detailed, actionable Markdown audit report.
+
+## Absolute Rules
+
+1. **Cover every single guideline** — read `references/guidelines.md` in full before starting. Not one rule can be skipped or grouped away.
+2. **No modifications** — audit strictly as the guidelines are written. No additions, no subtractions, no personal interpretations.
+3. **No assumptions** — if information is not present in the submitted content or metadata, flag it as a gap. Do not assume it exists elsewhere.
+4. **Output is always a file** — use the Write tool to save the report as `seo-audit-report.md` in the current working directory. Do this automatically without asking. After saving, print the file path and a short summary in the terminal.
+
+---
+
+## Step 1 — Read the guidelines first
+
+Before doing anything else:
+
+```
+read references/guidelines.md
+```
+
+Load all 12 sections into context. You will audit every section, every bullet, every rule.
+
+---
+
+## Step 2 — Collect inputs
+
+**Important:** This skill is used for pre-publish review. URL/slug may not exist yet — that is normal and expected. Only block on truly missing content. Everything else should be marked ⚠️ Unverifiable if absent.
+
+The ONLY truly required input is:
+- **Full blog content (body text)** — cannot audit without this. If missing, ask for it.
+- **Primary keyword** — cannot audit keyword rules without this. If missing, ask for it.
+
+Everything else below is optional. If not provided, mark those rules as ⚠️ Unverifiable and proceed:
+
+| Input | Required? | Notes |
+|---|---|---|
+| Full blog content (body text) | ✅ Yes | Paste or file — only this blocks the audit |
+| Primary keyword | ✅ Yes | Only this blocks the audit |
+| Page title / H1 | Optional | Flag URL/title rules as ⚠️ if absent |
+| Meta title | Optional | Flag meta rules as ⚠️ if absent |
+| Meta description | Optional | Flag meta rules as ⚠️ if absent |
+| URL / slug | Optional | Often not set pre-publish — flag as ⚠️ Unverifiable |
+| Secondary keywords | Optional | List if available |
+| Tertiary keywords | Optional | |
+| Image list (filenames, alt text, sizes, formats) | Optional | Flag image rules as ⚠️ if absent |
+| Internal links used (anchor text + destination) | Optional | Flag as ⚠️ if absent |
+| External links used (anchor text + destination) | Optional | Flag as ⚠️ if absent |
+| Instagram carousel (description or file) | Optional | Required per guidelines — flag as ❌ if not submitted |
+| Word count | Optional | Estimate from content if not provided |
+
+---
+
+## Step 3 — Run the audit
+
+Go through `references/guidelines.md` section by section. For **every rule**, determine:
+
+- ✅ **PASS** — rule is clearly met
+- ❌ **FAIL** — rule is clearly violated
+- ⚠️ **UNVERIFIABLE** — cannot be checked from submitted inputs (note what's needed)
+- 💡 **SUGGESTION** — passes technically but could be improved
+
+Do NOT skip any rule. Do NOT merge rules together unless they are genuinely a single atomic check.
+
+---
+
+## Step 4 — Produce the report
+
+Save the report as `/mnt/user-data/outputs/seo-audit-report.md` using the exact template below.
+
+---
+
+## Report Template
+
+```markdown
+# SEO Audit Report — [Blog Title]
+**Audited on:** [Date]  
+**Primary Keyword:** [keyword]  
+**URL / Slug:** [url]  
+**Word Count:** [count or estimated]  
+**Overall Score:** [X / 100] (see scoring below)
+
+---
+
+## Executive Summary
+
+[3–5 sentence overview: what's in good shape, what are the critical gaps, top 3 actions to take immediately.]
+
+---
+
+## Priority Legend
+
+| Priority | Meaning |
+|---|---|
+| 🔴 Critical | Will directly hurt rankings or disqualify the content |
+| 🟠 High | Significant SEO impact, fix before publishing |
+| 🟡 Medium | Noticeable impact, fix soon after publishing |
+| 🟢 Low | Minor improvement, fix when convenient |
+
+---
+
+## Audit Results by Section
+
+### 1. AIO Optimization
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 1.1 | Content uses question-answer format for AI summaries | [✅/❌/⚠️] | [🔴/🟠/🟡/🟢] | [specific finding] |
+
+---
+
+### 2. URL Structure
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 2.1 | URL length < 60 characters | | | |
+| 2.2 | URL is short and readable | | | |
+| 2.3 | Exact primary keyword included in URL | | | |
+| 2.4 | URL is unique (no duplicates in topic cluster) | | | |
+| 2.5 | Hyphens used correctly (only where needed, lowercase) | | | |
+
+---
+
+### 3. Page Titles
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 3.1 | Title length < 60 characters | | | |
+| 3.2 | Only one H1 per page | | | |
+| 3.3 | Only one Title per page | | | |
+| 3.4 | H1 and Title both exist but are different | | | |
+| 3.5 | Primary keyword towards beginning of title | | | |
+| 3.6 | Title is unique | | | |
+| 3.7 | H1 is unique | | | |
+| 3.8 | Title is clickbait / encourages clicks | | | |
+
+---
+
+### 4. Blog/Hub Content Structure
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 4.1 | Intro is short (max 2 paragraphs, 5–6 lines each) | | | |
+| 4.2 | No huge build-up; problem + solution within first few lines | | | |
+| 4.3 | Intro starts with a hook | | | |
+| 4.4 | Primary keyword in 1st paragraph / 1st 10% of intro | | | |
+| 4.5 | Intro does NOT mention "this blog is about" or repeat ToC | | | |
+| 4.6 | Comparison table included (if relevant) | | | |
+| 4.7 | Listicle included (if relevant) | | | |
+| 4.8 | Vocabulary is simple, suitable for 25-year-old developer | | | |
+| 4.9 | Tone is first person, story narration | | | |
+| 4.10 | No analogies or distracting content | | | |
+| 4.11 | Real companies / blog references included | | | |
+| 4.12 | No babysitting / over-explanatory content | | | |
+| 4.13 | Short paragraphs used throughout | | | |
+| 4.14 | Bullet points and listicles used for LLM-friendliness | | | |
+| 4.15 | Adequate transition words (Yoast standard) | | | |
+| 4.16 | No consecutive sentences starting the same way | | | |
+| 4.17 | Active voice preferred over passive | | | |
+| 4.18 | Inclusive and respectful language used | | | |
+| 4.19 | Word count ≥ 1500 words (min threshold) | | | |
+| 4.20 | Word count within 1500–2500 range (or justified by competitor length) | | | |
+| 4.21 | Content is accurate and up-to-date | | | |
+| 4.22 | Content is credible and contextual | | | |
+| 4.23 | Content matches search intent | | | |
+| 4.24 | No paragraph exceeds 4 lines | | | |
+
+---
+
+### 5. Headings
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 5.1 | Only one H1 on the page | | | |
+| 5.2 | Proper H2/H3 hierarchy used | | | |
+| 5.3 | Relevant keywords in H1/Title | | | |
+| 5.4 | Relevant keywords in H2 tags | | | |
+
+---
+
+### 6. Image Optimization
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 6.1 | No GIFs used | | | |
+| 6.2 | Images used only when necessary | | | |
+| 6.3 | Blog images in PNG format | | | |
+| 6.4 | Hub/webpage images in WEBP format | | | |
+| 6.5 | All images < 100 KB | | | |
+| 6.6 | Images compressed without quality loss | | | |
+| 6.7 | Image filenames are keywords | | | |
+| 6.8 | Alt text includes keywords/synonyms and accurate description | | | |
+| 6.9 | Images have descriptive title tags | | | |
+| 6.10 | Images are unique (edited if downloaded from internet) | | | |
+
+---
+
+### 7. Keywords
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 7.1 | Primary keyword usage matches search intent (not just density) | | | |
+| 7.2 | Secondary keywords used in headings/sub-headings (not forced) | | | |
+| 7.3 | Tertiary keyword density 0.5–0.75% | | | |
+| 7.4 | LSI keywords used throughout | | | |
+| 7.5 | Primary keyword search volume > 400/month | | | |
+| 7.6 | Keyword variations ~0.5–1% of total word count | | | |
+| 7.7 | Keyword variations maintain good readability | | | |
+
+---
+
+### 8. Internal Linking
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 8.1 | Core/brand keywords interlinked | | | |
+| 8.2 | Internally linked pages are relevant to each other | | | |
+| 8.3 | Targeted anchor text used | | | |
+| 8.4 | ≤ 5 internal links per 1000 words | | | |
+
+---
+
+### 9. External Links
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 9.1 | Links to reputable and relevant external sites | | | |
+| 9.2 | All external links use target="_blank" | | | |
+| 9.3 | External anchor text is generic (not targeting ranked keywords) | | | |
+
+---
+
+### 10. Meta Description
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 10.1 | Length 150–160 characters | | | |
+| 10.2 | Targeted keywords included | | | |
+| 10.3 | Meta keywords match content (Bing spam check) | | | |
+| 10.4 | Gives clear description of page content | | | |
+| 10.5 | Unique meta description | | | |
+| 10.6 | Encourages clicks (clickbait quality) | | | |
+
+---
+
+### 11. Meta Title
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 11.1 | Primary keyword towards beginning | | | |
+| 11.2 | Length ≤ 60 characters | | | |
+| 11.3 | Matches search intent | | | |
+| 11.4 | Not an exact copy of competitors' meta titles | | | |
+| 11.5 | Unique meta title | | | |
+
+---
+
+### 12. Instagram Carousel
+| # | Rule | Status | Priority | Notes |
+|---|---|---|---|---|
+| 12.1 | Carousel post created for this blog | | | |
+| 12.2 | Dimensions 1080 × 1350 px | | | |
+| 12.3 | 4–7 slides (or more if needed) | | | |
+| 12.4 | Dark mode theme | | | |
+| 12.5 | Clean modern font used (Helvetica/Poppins/Roboto/Open Sans) | | | |
+| 12.6 | Slide 1 has blog topic/keyword as title, bold typography, minimal clutter | | | |
+| 12.7 | 3–5 bullets per slide | | | |
+| 12.8 | Tone is educational + engaging (not robotic/AI) | | | |
+| 12.9 | Follows suggested structure (Intro → Key Insights → Benefits → CTA) | | | |
+| 12.10 | CTA slide ends with "Follow @Keploy for more!" | | | |
+| 12.11 | Created in Canva or Figma | | | |
+| 12.12 | Writer's photo (circular) + name + Instagram ID included on post | | | |
+
+---
+
+## Issues Summary
+
+### 🔴 Critical Issues
+[List each critical failure with the rule ID, what was found, and exactly what to fix.]
+
+### 🟠 High Priority Issues
+[List each high-priority failure.]
+
+### 🟡 Medium Priority Issues
+[List each medium-priority issue.]
+
+### 🟢 Low Priority / Suggestions
+[List minor improvements and suggestions.]
+
+### ⚠️ Unverifiable Items
+[List every item that could not be checked due to missing inputs, and specify what information is needed to verify it.]
+
+---
+
+## Action Plan
+
+List the top 10 fixes in order of priority, formatted as a checklist:
+
+- [ ] [Action 1 — most critical]
+- [ ] [Action 2]
+- [ ] ...
+
+---
+
+## Scoring
+
+Score out of 100. Deduct points as follows:
+
+| Severity | Deduction per issue |
+|---|---|
+| 🔴 Critical | –8 points |
+| 🟠 High | –4 points |
+| 🟡 Medium | –2 points |
+| 🟢 Low | –0.5 points |
+| ⚠️ Unverifiable | –1 point (assumed gap) |
+
+**Total deductions:** [X]  
+**Final Score:** [100 – X] / 100
+
+> Score 90–100: Publish-ready | 75–89: Minor fixes needed | 60–74: Significant gaps | <60: Major rework required
+
+---
+
+*Report generated by Keploy SEO Audit Skill. Guidelines source: Keploy SEO Content Guidelines (internal).*
+```
+
+---
+
+## Step 5 — Chat summary
+
+After saving the file, print this in the chat:
+
+```
+✅ Audit complete. Report saved to: seo-audit-report.md
+
+📊 Score: [X/100]
+🔴 Critical: [N] | 🟠 High: [N] | 🟡 Medium: [N] | 🟢 Low: [N] | ⚠️ Unverifiable: [N]
+
+Top 3 immediate fixes:
+1. [most critical issue]
+2. [second most critical]
+3. [third most critical]
+```
+
+---
+
+## Notes for the auditor
+
+- If the user provides content as a file, read it first before starting the audit.
+- If partial inputs are provided (e.g., no image list), mark all image rules as ⚠️ UNVERIFIABLE with a note saying "Image metadata not provided."
+- Instagram carousel is **required** per guidelines. If not submitted, all 12 carousel rules are ❌ FAIL.
+- Never invent data. Never assume a rule is met if you cannot verify it from the inputs.
+- Keep your notes in the table cells specific and actionable — not generic ("keyword missing" is bad; "Primary keyword 'API testing' not found in first paragraph" is good).

package/skill/references/guidelines.md

@@ -0,0 +1,124 @@
+# Keploy SEO Content Guidelines — Authoritative Reference
+
+> This file is the single source of truth for all audit checks. Every section and every rule must be audited. No additions, subtractions, or modifications allowed.
+
+---
+
+## 1. AIO Optimization
+- Content must use question-answer format so it gets pulled into AI summaries.
+
+---
+
+## 2. URL Structure
+- Length: Less than 60 characters.
+- Keep URLs short and readable.
+- Include exact primary keyword in URL.
+- No 2 URLs should be exactly the same (check for duplicacy within topic clusters).
+- Use hyphens (-) to separate words with small casing. Only use hyphens where really needed (overuse can look AI-generated).
+
+---
+
+## 3. Page Titles
+- Length: Keep under 60 characters.
+- Only one H1 & one Title per page. They must both exist but be different from each other.
+- Include the primary keyword towards the beginning of the title.
+- Each page must have a unique title and H1.
+- Title must be clickbait — it must encourage the user to click.
+
+---
+
+## 4. Blog/Hub Content Structure
+- Intro: Short — not more than two paragraphs, 5–6 lines each.
+- No huge build-up. Highlight the problem statement in 3–4 lines and start with the solution.
+- Intro must start with a hook.
+- Primary keyword must appear in the 1st paragraph / 1st 10% of the introduction.
+- Do NOT mention what this blog is about or repeat the table of contents in the intro.
+- Add a comparison table and listicle if relevant to the topic.
+- Vocabulary: Simple, easy, suitable for a 25-year-old developer audience in English.
+- Tone: First person, story narration style. No analogies or distracting content.
+- Add references to real companies' blogs or their names to connect to examples, success/failure cases. No babysitting content.
+- Easy vocab. Short paragraphs for better indexing. Bullet points and listicles for LLM-friendliness.
+- Readability: Must pass Yoast real-time content analysis standards — required % of transition words, no consecutive sentences starting the same way, active voice preferred over passive.
+- Use inclusive and respectful language. Avoid offensive, biased, or judgmental words/phrases.
+- Length: Minimum 1500–2500 words (also check competitor length for that keyword).
+- Quality: Accurate, Authoritative, Up-to-date, Complementary, Credible, Transparent, Contextual.
+- Relevance: Content must match search intent (direct match, semantic equivalents, multiple potential intents).
+- Readability: Keep content concise. Reference BrowserStack, TestSigma, Katalon writing styles.
+- Freshness: Old content must be refreshed with new information.
+- Paragraph limit: A paragraph must NOT be more than 4 lines.
+
+---
+
+## 5. Headings (H1, H2, H3)
+- Only one H1/Title per page.
+- Use H2 and H3 for subheadings in proper hierarchy.
+- Include relevant keywords in headings, especially in H1/Title and H2 tags.
+
+---
+
+## 6. Image Optimization
+- No GIFs. Use images only when necessary.
+- Format: WEBP for hubs and webpages; PNG for blogs.
+- File size: Less than 100 KB.
+- Compress images without losing quality.
+- File name must be a keyword.
+- Alt text must include keywords/synonyms and accurate descriptions.
+- Use descriptive title tags for images.
+- Images must be unique — if downloaded from the internet, must be edited in Canva (e.g., collage of 2+ images).
+
+---
+
+## 7. Keywords
+- Primary keyword density: No fixed ideal — match search intent over keyword density.
+- Secondary keywords: Use in headings and sub-headings whenever possible. Do NOT forcefully insert.
+- Tertiary keyword density: 0.5–0.75%.
+- LSI keywords: Not optional — use relevant LSI keywords whenever possible to match search intent.
+- Search volume: Greater than 400 searches/month is ideal. Range: 400–2000 searches/month.
+- Keyword variations: Aim for 0.5–1% of total word count. Maintain good readability.
+
+---
+
+## 8. Internal Linking
+- Try to interlink core/brand keywords + ones relevant to the topic.
+- Internally linked pages must be relevant to each other.
+- Use targeted anchor text.
+- Maximum 5 internal links per 1000 words.
+
+---
+
+## 9. External Links
+- Link to reputable and relevant external sites (stats, research, collaborations, image sources, relevant tweets).
+- Use target="_blank" to open in new tabs.
+- External link anchor text must be generic — never target keywords you want to rank for.
+
+---
+
+## 10. Meta Descriptions
+- Length: 150–160 characters.
+- Include targeted keywords (for Google). Note: Bing uses meta keywords as a spam indicator if keywords not found in content.
+- Must give a clear description of page content.
+- Each page must have a unique meta description.
+- Must be clickbait — encourage people to click.
+
+---
+
+## 11. Meta Title
+- Include primary keyword, preferably towards the beginning.
+- Character limit: ≤ 60 characters.
+- Keep search intent in mind.
+- Must NOT be an exact copy of competitors' meta titles.
+- Must be unique for every page.
+
+---
+
+## 12. Instagram Carousel Post (Required for Every Blog)
+- Every blog must include an Instagram carousel post as part of the Writers Program.
+- Dimensions: 1080 × 1350 px (Instagram portrait size).
+- Slides: 4–7 slides minimum (can be more if needed).
+- Theme: Dark mode (match Keploy's Instagram aesthetic).
+- Fonts: Clean, modern fonts — Helvetica (Regular/Bold), Poppins (Rounded), Roboto, or Open Sans.
+- Slide 1 (Cover): Blog topic/keyword as title. Bold, modern typography. Minimal clutter.
+- Content: 3–5 bullets per slide. Tone: Educational + engaging (not robotic or AI-generated).
+- Suggested structure: (1) Intro/Definition, (2–3) Key Insights, (4) Benefits/Examples, (5) Outro/CTA with "Follow @Keploy for more!"
+- Tools preferred: Canva or Figma.
+- Writers must add their photo (circular) + name + Instagram ID on the post for shoutout/recognition.