ourdigital/our-claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f78d9474bbfcf4438f7f772e8c5a2d80cdc0a43b
our-claude-skills/custom-skills/REFACTORING_PLAN.md
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

387 lines
11 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink