# 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

```bash
# 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`

```yaml
---
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`

```markdown
# 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