Files

Andrew Yim 236be6c580 directory changes and restructuring

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-22 02:01:41 +09:00

11 KiB

Raw Blame History

Skills Refactoring Plan

Guiding Principles

One thing done well - Each skill focuses on a single, well-defined capability
Directives under 1,500 words - Concise, actionable (SKILL.md / CLAUDE.md)
Dual-platform support - Separate subdirectories for Claude Desktop and Claude Code
Self-contained - Each platform version is fully independent (no shared resources)
Code-first development - Build Claude Code version first, then refactor to Desktop
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

Build Claude Code version first - Full automation with scripts
Refactor to Desktop - Extract guidance, remove script dependencies
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:

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

11 KiB Raw Blame History