Skip to content
BSWEN
Blog

How to Build Reusable Claude Code Skills for Website Optimization

Cowrie
Cowrie
Dev @ Bswen

Workflow automation

Problem

Every time I need to run an SEO audit on a website, I repeat the same steps: analyze page structure, check meta tags, validate schema markup, review Core Web Vitals, generate a prioritized report. I keep explaining these workflows to Claude Code from scratch, and I keep rediscovering the same patterns.

I realized my skills were just fancy prompts - they lacked real context and reusable structure.

Then I found a Reddit discussion in r/claudeskills where someone shared an open-source SEO analysis skill called Toprank. A staff member commented: “I’ve found that’s kind of the magic with skills in general - when they stop being just a fancy prompt and start acting more like a reusable workflow with real context.”

That insight changed how I approach skill design.

Purpose

This post demonstrates how to build reusable Claude Code skills that combine procedural workflows with real context - codebase analysis, external data, and bundled resources.

What is a Skill?

A skill is a modular package with three components:

Skill directory structure
skill-name/
├── SKILL.md          # Required: YAML frontmatter + instructions
├── scripts/          # Optional: executable automation
├── references/       # Optional: loaded when needed
└── assets/           # Optional: output templates

The key insight: skills work best when they combine structured workflows with actual context, not just prompt text.

Step 1: Define Skill Metadata

The SKILL.md file starts with YAML frontmatter. This metadata stays in context at all times (~100 words).

SKILL.md frontmatter
---
name: seo-audit
description: This skill should be used when the user asks to "audit SEO", "analyze page performance", "check meta tags", "validate schema markup", "run SEO analysis", or mentions website optimization tasks including Google Search Console integration, Core Web Vitals, or on-page SEO checks.
version: 1.0.0
---

I learned these best practices for descriptions:

  • Use third-person format
  • Include exact phrases users would say
  • Be concrete, not vague like “SEO optimization”
  • List specific trigger scenarios

When I wrote vague descriptions like “optimizes websites”, the skill rarely triggered. When I used exact phrases like “audit SEO” and “check meta tags”, it worked reliably.

Step 2: Design the Workflow

After frontmatter, the SKILL.md body contains imperative instructions. These load when the skill triggers.

SKILL.md workflow section
# SEO Audit Skill


## Workflow


1. **Analyze the website structure** - Inspect HTML files, identify key pages
2. **Check on-page SEO** - Validate meta tags, headings, schema markup
3. **Performance audit** - Core Web Vitals, page load times, image optimization
4. **Content analysis** - Keyword usage, internal linking, duplicate content
5. **Generate report** - Create actionable recommendations with priority


For Google Search Console integration, see [GSC_GUIDE.md](references/GSC_GUIDE.md)

The workflow uses progressive disclosure:

  • Frontmatter: Always loaded (triggers)
  • SKILL.md body: Loaded when skill triggers
  • References: Loaded only when mentioned

This keeps context small while providing depth when needed.

Step 3: Add Bundled Resources

Scripts provide reliable automation. I put executable code in the scripts/ directory:

scripts directory
scripts/
├── fetch_gsc_data.py     # Google Search Console API
├── analyze_performance.js # Lighthouse automation
└── validate_schema.py     # Schema markup validation

References hold documentation that loads on demand:

references directory
references/
├── GSC_GUIDE.md       # Google Search Console integration
├── SCHEMA_PATTERNS.md # Common schema templates
└── SEO_CHECKLIST.md   # Complete audit checklist

Assets store output templates:

assets directory
assets/
├── seo_report_template.md  # Report format
└── priority_matrix.md      # Issue prioritization

Step 4: Integrate MCP Tools

Skills gain more power when they connect to MCP servers. For SEO work, I use:

  • Fetch MCP - Retrieve webpage content, extract meta tags
  • Context7 MCP - Get official SEO documentation
  • Search Console MCP - Fetch search analytics data

The skill instructions reference these tools directly:

MCP integration in workflow
## Workflow


1. Use `mcp__fetch__fetch_markdown` to retrieve page content
2. Use `mcp__context7__resolve-library-id` for SEO docs
3. Call Search Console MCP for analytics data

Step 5: Test and Iterate

I tested the skill on real optimization tasks:

  1. Ran it on three different websites
  2. Noticed it struggled with schema validation
  3. Added scripts/validate_schema.py
  4. Updated SKILL.md to reference the script
  5. Tested again - now it handles schemas reliably

Each iteration made the skill more practical.

Common Mistakes I Made

When I started building skills, I made several mistakes:

Vague descriptions:

Description comparison
# Wrong - too generic
description: This skill helps with SEO.


# Right - specific triggers
description: This skill should be used when the user asks to "audit SEO", "check meta tags", or "validate schema markup".

Bloated SKILL.md body: I put too much content in the body, which loaded every time the skill triggered. Now I use references for detailed guides.

Missing user phrases: I forgot to include exact phrases users say. Skills triggered unpredictably.

Too generic: I tried building “website helper” skills instead of focused “SEO audit” skills. Domain-specific skills work better.

Complete Example

Here’s a complete SKILL.md for a meta tag optimizer:

meta-tag-optimizer/SKILL.md
---
name: meta-tag-optimizer
description: This skill should be used when the user asks to "optimize meta tags", "update title and description", "fix SEO metadata", or mentions meta tag optimization including title tags, meta descriptions, open graph tags, or Twitter cards.
version: 1.0.0
---


# Meta Tag Optimizer


## Workflow


1. **Analyze current meta tags** - Inspect HTML files
2. **Identify issues** - Missing tags, duplicates, length issues
3. **Generate optimized tags** - Based on content and SEO best practices
4. **Update files** - Apply changes with proper format


See [META_GUIDE.md](references/META_GUIDE.md) for complete tag specifications.

The full directory structure:

Complete skill directory
seo-optimizer-skill/
├── SKILL.md
├── scripts/
│   ├── run_lighthouse.sh
│   ├── fetch_gsc_data.py
│   └── generate_report.py
├── references/
│   ├── META_GUIDE.md
│   ├── GSC_GUIDE.md
│   └── SEO_CHECKLIST.md
└── assets/
    └── seo_report_template.md

Why This Matters

Skills transform repetitive work into reusable workflows:

  • Efficiency: I run SEO audits without re-explaining the process
  • Consistency: Standardized approach across all audits
  • Context: Skills combine codebase analysis with external data sources
  • Community: Open-source skills like Toprank demonstrate proven patterns

The magic happens when skills stop being fancy prompts and start acting like workflows with real context.

Summary

In this post, I showed how to build reusable Claude Code skills using SKILL.md files with YAML frontmatter, structured workflows, and bundled resources. The key point is that skills become powerful when they combine procedural knowledge with real context - codebase analysis, external data, and scripts that run reliably.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: