our-claude-skills/custom-skills/99_archive/doc/REFACTORING_PLAN.md

Skills Refactoring Plan

Guiding Principles

1. One thing done well - Each skill focuses on a single, well-defined capability
2. Directives under 1,500 words - Concise, actionable (SKILL.md / CLAUDE.md)
3. Dual-platform support - Separate subdirectories for Claude Desktop and Claude Code
4. Self-contained - Each platform version is fully independent (no shared resources)
5. Code-first development - Build Claude Code version first, then refactor to Desktop
6. Progressive numbering - Logical grouping by domain

---

Dual-Platform Skill Structure

Each skill has two independent versions:

XX-skill-name/
│
├── code/                           # Claude Code version
│   ├── CLAUDE.md                   # Main directive
│   ├── scripts/                    # Executable Python/Bash
│   │   ├── main_script.py
│   │   └── requirements.txt
│   ├── references/                 # Documentation
│   └── templates/                  # Output templates
│
├── desktop/                        # Claude Desktop version
│   ├── SKILL.md                    # Main directive (YAML frontmatter)
│   ├── references/                 # Guidance docs (no scripts)
│   ├── templates/                  # Output templates
│   └── examples/                   # Usage examples
│
└── README.md                       # Overview (optional)

Platform Differences

Aspect	Claude Code (code/)	Claude Desktop (desktop/)
Directive	CLAUDE.md	SKILL.md (YAML frontmatter)
Execution	Direct Bash/Python	MCP tools only
Scripts	Full automation	Reference/guidance only
Install	Clone + pip install	Add to Project context
Focus	Action-oriented	Conversational guidance

Development Workflow

1. Build Claude Code version first - Full automation with scripts
2. Refactor to Desktop - Extract guidance, remove script dependencies
3. Desktop focuses on MCP - Use Firecrawl, Perplexity, Notion MCP tools

---

Directory Structure Overview

Range	Domain	Purpose
01-09	General Automation	Notion, data pipelines, reporting
10-19	SEO Tools	Decomposed from seo-audit-agent
20-29	GTM/GA Tools	Tag management, analytics
30-39	OurDigital Channel	Branding, content, design
40-49	Jamie Clinic	Brand-specific tools

---

Phase 1: Self-Contained Skills (No Shared Directory)

Design Decision: Duplicate Utilities Per Skill

Each skill includes its own copy of required utilities:

• base_client.py - Copied to each skill needing API rate limiting
• notion_client.py - Copied to skills that export to Notion

Trade-offs:

• (+) Each skill is fully independent and portable
• (+) No import path complexity
• (+) Skills can diverge if needed
• (-) Code duplication across skills
• (-) Updates need to be applied to multiple copies

Pattern: Keep utility files minimal (~100-200 LOC) to reduce duplication cost.

---

Phase 2: SEO Tools Decomposition (10-19)

Source: seo-audit-agent/scripts/ (6,049 LOC → ~600 LOC per skill)

10-seo-technical-audit

Focus: Crawlability and indexing fundamentals

• robots_checker.py - Robots.txt parsing and validation
• sitemap_validator.py - XML sitemap structure validation
• sitemap_crawler.py - Async URL accessibility checking

Triggers: "check crawlability", "robots.txt", "sitemap validation"

11-seo-on-page-audit

Focus: Single-page optimization analysis

• page_analyzer.py - Meta tags, headings, links, OG tags

Triggers: "on-page SEO", "meta tags", "heading structure"

12-seo-local-audit

Focus: Local business SEO assessment (standalone, NOT merged with schema)

• NAP (Name, Address, Phone) consistency analysis
• Google Business Profile optimization checklist
• Local citations audit
• LocalBusiness schema integration (imports from 13-seo-schema-validator)
• Review management guidelines

Triggers: "local SEO", "Google Business Profile", "NAP", "citations", "local rankings"

13-seo-schema-validator

Focus: Structured data extraction and validation

• schema_validator.py - JSON-LD, Microdata, RDFa parsing
• Rich Results compatibility checking

Triggers: "validate schema", "structured data check"

14-seo-schema-generator

Focus: Schema markup creation

• schema_generator.py - Template-based generation
• Types: Organization, Article, FAQ, Product, LocalBusiness, Breadcrumb, WebSite

Triggers: "generate schema", "create JSON-LD", "add structured data"

15-seo-core-web-vitals (rename from schema-optimizer)

Focus: Performance metrics only

• pagespeed_client.py - LCP, FID, CLS, INP, TTFB, FCP

Triggers: "Core Web Vitals", "page speed", "LCP/CLS/FID"

16-seo-search-console (rename from search-intent)

Focus: GSC data retrieval and analysis

• gsc_client.py - Rankings, CTR, impressions, sitemap status

Triggers: "Search Console", "GSC data", "search performance"

17-seo-gateway-architect (keep as-is)

Focus: Gateway page strategy planning

18-seo-gateway-builder (keep as-is)

Focus: Gateway page content generation

19-seo-audit-orchestrator (optional)

Focus: Coordinate multiple SEO tools for full audit

• Lightweight orchestrator that calls other skills
• Report aggregation and Notion export

Decision: May not be needed if Claude can chain skills naturally

---

Phase 3: Fix Misplaced Directories

Current Issues

Directory	Issue	Action
01-notion-organizer/02-notion-organizer/	Nested structure	Flatten
04-research-to-presentation	Wrong range	Move to 32
21-gmt-manager	Typo (gmt→gtm)	Rename

Corrections

# Fix nested structure
mv 01-notion-organizer/02-notion-organizer/* 01-notion-organizer/
rmdir 01-notion-organizer/02-notion-organizer

# Move to correct range
mv 04-research-to-presentation 32-ourdigital-presentation

# Fix typo
mv 21-gmt-manager 21-gtm-manager

---

Phase 4: Final Directory Structure

ourdigital-custom-skills/
│
├── 01-notion-organizer/
│   ├── code/                       # Claude Code version
│   └── desktop/                    # Claude Desktop version
│
├── 02-notion-data-migration/
│   ├── code/
│   └── desktop/
│
├── 10-seo-technical-audit/
│   ├── code/
│   └── desktop/
│
├── 11-seo-on-page-audit/
│   ├── code/
│   └── desktop/
│
├── 12-seo-local-audit/
│   ├── code/
│   └── desktop/
│
├── 13-seo-schema-validator/
│   ├── code/
│   └── desktop/
│
├── 14-seo-schema-generator/
│   ├── code/
│   └── desktop/
│
├── 15-seo-core-web-vitals/
│   ├── code/
│   └── desktop/
│
├── 16-seo-search-console/
│   ├── code/
│   └── desktop/
│
├── 17-seo-gateway-architect/
│   ├── code/
│   └── desktop/
│
├── 18-seo-gateway-builder/
│   ├── code/
│   └── desktop/
│
├── 20-gtm-audit/
│   ├── code/
│   └── desktop/
│
├── 21-gtm-manager/
│   ├── code/
│   └── desktop/
│
├── 30-ourdigital-designer/
│   ├── code/
│   └── desktop/
│
├── 31-ourdigital-research/
│   ├── code/
│   └── desktop/
│
├── 32-ourdigital-presentation/
│   ├── code/
│   └── desktop/
│
├── 40-jamie-brand-editor/
│   ├── code/
│   └── desktop/
│
├── 41-jamie-brand-audit/
│   ├── code/
│   └── desktop/
│
└── _archive/                       # Archived after decomposition
    └── seo-audit-agent/

Key Points:

• Each skill has code/ and desktop/ subdirectories
• No sharing between platforms - fully independent
• Build code/ first, then refactor to desktop/

---

Phase 5: Directive Templates (Under 1,500 Words Each)

Claude Desktop: desktop/SKILL.md

---
name: skill-name
version: 1.0.0
description: One-sentence description. Triggers: keyword1, keyword2.
allowed-tools: mcp__firecrawl__*, mcp__perplexity__*, mcp__notion__*
---

# Skill Name

## Purpose
[2-3 sentences max]

## Core Capability
[Single focused capability - what this skill does]

## MCP Tool Usage
[Which MCP tools to use and how]

## Workflow
[Step-by-step guidance for the task]

## Output Format
[Expected deliverable format]

## Limitations
[1-3 bullet points]

Claude Code: code/CLAUDE.md

# CLAUDE.md

## Overview
[1-2 sentences - what this skill does]

## Quick Start
\`\`\`bash
python scripts/main.py --url https://example.com
\`\`\`

## Scripts
| Script | Purpose | Usage |
|--------|---------|-------|
| main.py | Primary function | `python scripts/main.py [args]` |

## Configuration
[Environment variables, credentials, API keys]

## Output
[What the script produces]

---

Implementation Order

Batch 1: Directory Cleanup

• Fix nested 01-notion-organizer structure
• Rename 21-gmt-manager → 21-gtm-manager
• Move 04-research-to-presentation → 32-ourdigital-presentation

Batch 2: SEO Decomposition

• 10-seo-technical-audit (robots + sitemap)
• 11-seo-on-page-audit (page analyzer)
• 13-seo-schema-validator
• 14-seo-schema-generator
• 15-seo-core-web-vitals (pagespeed)
• 16-seo-search-console (gsc)

Batch 3: Finalization

• Archive seo-audit-agent → _archive/
• Update root CLAUDE.md with new structure
• Verify each skill works independently

---

Script Distribution Matrix

Script	Target Skill	LOC
base_client.py	00-shared	400
robots_checker.py	10-seo-technical-audit	350
sitemap_validator.py	10-seo-technical-audit	450
sitemap_crawler.py	10-seo-technical-audit	400
page_analyzer.py	11-seo-on-page-audit	650
schema_validator.py	13-seo-schema-validator	600
schema_generator.py	14-seo-schema-generator	600
pagespeed_client.py	15-seo-core-web-vitals	500
gsc_client.py	16-seo-search-console	400
notion_reporter.py	00-shared (base)	900
full_audit.py	ARCHIVE (orchestrator)	800

---

Decisions Made

Question	Decision
Shared 00-shared/ directory?	No - Each skill self-contained with copied utilities
12-seo-local-audit scope?	Keep separate - Focus on NAP/GBP/citations (broader than just schema)
03-notion-reporter?	Not needed - Notion export is per-skill
19-seo-audit-orchestrator?	Skip - Let Claude chain skills naturally

---

Next Steps

Ready to proceed? I recommend:

1. Start with Batch 1 (infrastructure + fixes)
2. Then Batch 2 (SEO decomposition - largest effort)
3. Validate each skill works independently before archiving seo-audit-agent