feat: Add installation tool, Claude.ai export, and skill standardization (#1)

## Summary - Add portable installation tool (`install.sh`) for cross-machine setup - Add Claude.ai export files with proper YAML frontmatter - Add multi-agent-guide v2.0 with consolidated framework template - Rename `00-claude-code-setting` → `00-our-settings-audit` (avoid reserved word) - Add YAML frontmatter to 25+ SKILL.md files for Claude Desktop compatibility ## Commits Included - `93f604a` feat: Add portable installation tool for cross-machine setup - `9b84104` feat: Add Claude.ai export for portable skill installation - `f7ab973` fix: Add YAML frontmatter to Claude.ai export files - `3fed49a` feat(multi-agent-guide): Add v2.0 with consolidated framework - `3be26ef` refactor: Rename settings-audit skill and add YAML frontmatter Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 16:48:06 +07:00
parent 0bc24d00b9
commit b6a478e1df
72 changed files with 4770 additions and 803 deletions
--- a/custom-skills/99_archive/doc/REFACTORING_PLAN.md
+++ b/custom-skills/99_archive/doc/REFACTORING_PLAN.md
@@ -0,0 +1,386 @@
+# 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