SEO for Developers Skill

SEO for Developers

Practical SEO techniques for technical blog posts without compromising content quality.

Overview

This skill provides actionable SEO guidance specifically for technical content. It focuses on techniques that improve discoverability while maintaining the depth and accuracy that technical readers expect.

This skill covers:

Meta tag optimization (title, description)
Heading structure for SEO
Keyword placement strategies
Structured data for technical content
Internal linking best practices

This skill does NOT cover:

General marketing SEO tactics
Link building strategies
Social media optimization
Paid promotion

Quick Reference

Meta Tag Targets

| Element | Target | Notes | |---------|--------|-------| | Title tag | 50-60 chars | Include primary keyword | | Meta description | 150-160 chars | Call to action or value prop | | URL slug | 3-5 words | Hyphenated, no stop words | | H1 | 1 per page | Match or vary title slightly |

Content Checklist

| Check | Target | |-------|--------| | Primary keyword in title | Yes | | Primary keyword in first 100 words | Yes | | Keyword in at least one H2 | Yes | | Internal links | 2-5 per post | | External links | 1-3 authoritative sources | | Image alt text | All images |

Title Tag Optimization

Structure

[Primary Keyword]: [Benefit/Hook] | [Site Name]

Examples:

"Event Sourcing in Python: A Practical Guide | DevBlog"
"How to Set Up GitHub Actions: CI/CD in 10 Minutes | DevBlog"
"Understanding WebAssembly: From Browser to Server | DevBlog"

Guidelines

Front-load keywords — Put the most important words first
Include benefit — Why should someone click?
Stay under 60 chars — Longer titles get truncated
Match search intent — Use "how to", "guide", or "tutorial" for instructional content

Meta Description

Structure

[What the post covers]. [Key benefit or outcome]. [Call to action].

Examples:

"Learn how to implement event sourcing in Python with practical code examples. Build an audit log that never loses data. Start building today."
"Step-by-step guide to GitHub Actions CI/CD. Deploy your code automatically in under 10 minutes. No DevOps experience required."

Guidelines

150-160 characters — Longer descriptions get truncated
Include primary keyword — Helps with relevance
Add a CTA — "Learn how", "Get started", "See examples"
Unique per page — Never duplicate descriptions

Heading Structure

SEO-Optimized Structure

# Primary Keyword: Descriptive Title (H1)

## Introduction keyword phrase (H2)

### Supporting topic (H3)

## Second main keyword variation (H2)

### Supporting topic (H3)

## Conclusion with keyword (H2)

Guidelines

One H1 per page — Usually the post title
Keywords in H2s — Natural variations of primary keyword
Logical hierarchy — H2 > H3 > H4, no skipping levels
Descriptive headings — Tell readers what's in each section

Keyword Placement

Natural Placement Points

| Location | Priority | Notes | |----------|----------|-------| | Title (H1) | High | Primary keyword | | First paragraph | High | Within first 100 words | | At least one H2 | High | Natural variation | | URL slug | Medium | Exact or close match | | Image alt text | Medium | When relevant | | Throughout body | Low | Natural usage only |

Keyword Research for Technical Content

Focus on:

Problem-based queries — "how to debug memory leaks"
Comparison queries — "postgres vs mysql for..."
Tutorial queries — "python websocket tutorial"
Version-specific — "react 18 server components guide"

Avoid

Keyword stuffing (unnatural repetition)
Exact match in every heading
Forced keyword placement that hurts readability

Structured Data

Article Schema

Add to post frontmatter or page template:

{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Post Title",
  "description": "Meta description",
  "author": {
    "@type": "Person",
    "name": "Author Name"
  },
  "datePublished": "2025-02-19",
  "dateModified": "2025-02-19",
  "publisher": {
    "@type": "Organization",
    "name": "Site Name"
  }
}

HowTo Schema (for tutorials)

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to [Do Something]",
  "step": [
    {
      "@type": "HowToStep",
      "name": "Step 1 title",
      "text": "Step 1 description"
    }
  ]
}

Internal Linking

Best Practices

Link to related posts — 2-5 internal links per post
Use descriptive anchor text — "learn about event sourcing" not "click here"
Link early — Important links in first half of post
Create content clusters — Group related posts with cross-links

Link Placement

For more on this topic, see our [guide to event sourcing](/posts/event-sourcing-guide).

As we covered in the [previous tutorial](/posts/python-basics), ...

Related: [Understanding CQRS](/posts/cqrs-explained)

Image Optimization

Alt Text Guidelines

Describe the image — What does it show?
Include context — How does it relate to the content?
Keep it concise — Under 125 characters
Include keywords — When natural and relevant

Examples:

"Diagram showing event sourcing data flow from command to event store"
"Terminal output of successful pytest run with 15 passing tests"
"Architecture diagram comparing monolith vs microservices"

File Naming

event-sourcing-architecture-diagram.png
github-actions-workflow-screenshot.png
performance-comparison-chart.png

URL Structure

Guidelines

/blog/event-sourcing-python/
/tutorials/github-actions-setup/
/deep-dives/webassembly-explained/

Short and descriptive — 3-5 words
Use hyphens — Not underscores
Include keyword — Primary keyword in URL
No dates — Unless content is time-sensitive
Lowercase — Consistent casing

Common Mistakes

Over-Optimization

Keyword density targets (outdated)
Exact match keywords everywhere
Sacrificing readability for SEO

Under-Optimization

Missing meta descriptions
Generic titles ("Post 1")
No internal links
Missing alt text on images

Technical Issues

Duplicate content across URLs
Missing canonical tags
Slow page load (affects rankings)
Non-mobile-friendly layout

Agent Skills: SEO for Developers

Install this agent skill to your local

Skill Files