refactor: Reorganize skill numbering and update documentation
Skill Numbering Changes: - 01-03: OurDigital core (was 30-32) - 31-32: Notion tools (was 01-02) - 99_archive: Renamed from _archive for sorting New Files: - AGENTS.md: Claude Code agent routing guide - requirements.txt for 00-claude-code-setting, 32-notion-writer, 43-jamie-youtube-manager Documentation Updates: - CLAUDE.md: Updated skill inventory (23 skills) - AUDIT_REPORT.md: Current completion status (91%) - Archived REFACTORING_PLAN.md (most tasks complete) Removed: - ga-agent-skills/ (moved to separate repo ~/Project/dintel-ga4-agent) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
186
AGENTS.md
Normal file
186
AGENTS.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# AGENTS.md
|
||||
|
||||
This file documents how to effectively use Claude Code's specialized agents (via the Task tool) when working with this skills repository.
|
||||
|
||||
## Agent Types for Skills Development
|
||||
|
||||
### Explore Agent
|
||||
|
||||
**Best for:** Understanding skill structure, finding patterns, researching existing implementations
|
||||
|
||||
```
|
||||
Use Task tool with subagent_type=Explore for:
|
||||
- "How is the SEO technical audit skill structured?"
|
||||
- "Find all skills that use Python scripts"
|
||||
- "What MCP tools are commonly used in desktop skills?"
|
||||
- "Compare the structure of GTM audit vs GTM manager"
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Codebase exploration before creating new skills
|
||||
- Finding patterns across multiple skills
|
||||
- Understanding how existing features are implemented
|
||||
|
||||
### Plan Agent
|
||||
|
||||
**Best for:** Designing new skills, planning refactors, architectural decisions
|
||||
|
||||
```
|
||||
Use Task tool with subagent_type=Plan for:
|
||||
- "Plan a new skill for Google Analytics 4 audit"
|
||||
- "Design the structure for a multi-step SEO workflow"
|
||||
- "Plan the refactoring of notion-organizer to support batch operations"
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Before creating a new skill (design first)
|
||||
- When refactoring affects multiple files
|
||||
- For complex feature implementations
|
||||
|
||||
### General-Purpose Agent
|
||||
|
||||
**Best for:** Multi-step tasks that combine research and action
|
||||
|
||||
```
|
||||
Use Task tool with subagent_type=general-purpose for:
|
||||
- "Create a new skill for PDF generation following the existing patterns"
|
||||
- "Audit all Jamie skills for consistent branding guidelines"
|
||||
- "Update all SEO skills to use a shared utility module"
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Complex tasks requiring both exploration and implementation
|
||||
- Tasks spanning multiple skills or directories
|
||||
|
||||
### Bash Agent
|
||||
|
||||
**Best for:** Git operations, running scripts, file system tasks
|
||||
|
||||
```
|
||||
Use Task tool with subagent_type=Bash for:
|
||||
- "Run the skill validation script on all custom skills"
|
||||
- "Create git commits for each modified skill separately"
|
||||
- "Execute the token analyzer on all SKILL.md files"
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Running Python scripts in the skills
|
||||
- Git operations (commits, branches, diffs)
|
||||
- Batch file operations
|
||||
|
||||
## Skill-Specific Agent Recommendations
|
||||
|
||||
### Creating New Skills
|
||||
|
||||
| Task | Recommended Agent | Notes |
|
||||
|------|-------------------|-------|
|
||||
| Research existing patterns | Explore | Find similar skills first |
|
||||
| Design skill structure | Plan | Define scope before coding |
|
||||
| Generate boilerplate | general-purpose | Use init_skill.py template |
|
||||
| Write SKILL.md/CLAUDE.md | Direct (no agent) | Simple file writing |
|
||||
| Implement scripts | Direct (no agent) | Write Python/Bash directly |
|
||||
| Validate skill | Bash | Run validation scripts |
|
||||
|
||||
### Auditing & Maintenance
|
||||
|
||||
| Task | Recommended Agent | Notes |
|
||||
|------|-------------------|-------|
|
||||
| Audit skill completion | Explore | Check for missing files |
|
||||
| Update multiple skills | general-purpose | Batch operations |
|
||||
| Refactor shared code | Plan + general-purpose | Plan first, then execute |
|
||||
| Test skill scripts | Bash | Run tests and verify |
|
||||
|
||||
### Documentation
|
||||
|
||||
| Task | Recommended Agent | Notes |
|
||||
|------|-------------------|-------|
|
||||
| Generate skill summaries | Explore | Gather info from all skills |
|
||||
| Update CLAUDE.md | Direct (no agent) | Simple documentation |
|
||||
| Create usage examples | Explore + Direct | Research then document |
|
||||
|
||||
## Parallel Agent Execution
|
||||
|
||||
For independent tasks, launch multiple agents simultaneously:
|
||||
|
||||
```
|
||||
# Good: These tasks are independent
|
||||
Task 1: Explore - "Find all skills missing requirements.txt"
|
||||
Task 2: Explore - "List all skills with desktop/SKILL.md"
|
||||
Task 3: Bash - "Count lines of Python code per skill"
|
||||
|
||||
# Bad: These depend on each other
|
||||
Task 1: Plan - "Design the new skill structure"
|
||||
Task 2: general-purpose - "Implement the planned skill" # Needs Task 1 result
|
||||
```
|
||||
|
||||
## Domain-Specific Routing
|
||||
|
||||
### SEO Skills (10-19)
|
||||
|
||||
- Use **seo-advisor** agent for SEO strategy questions
|
||||
- Use **Explore** to understand existing SEO script patterns
|
||||
- Python scripts in these skills follow `base_client.py` patterns
|
||||
|
||||
### GTM Skills (20-29)
|
||||
|
||||
- Use **gtm-manager** agent for GTM-specific debugging
|
||||
- Requires Chrome GTM Debug profile for live testing
|
||||
- Scripts interact with GTM API and dataLayer
|
||||
|
||||
### Jamie Clinic Skills (40-49)
|
||||
|
||||
- Brand compliance is critical - check `references/` for guidelines
|
||||
- Korean language content - verify encoding in scripts
|
||||
- Instagram/YouTube skills may need API credentials
|
||||
|
||||
### Notion Skills (31-39)
|
||||
|
||||
- Use Notion MCP tools (`mcp__plugin_Notion_notion__*`) directly
|
||||
- Skills export data to Working with AI database
|
||||
- Check schema compatibility before creating pages
|
||||
|
||||
## Background Agents
|
||||
|
||||
For long-running tasks, use `run_in_background: true`:
|
||||
|
||||
```
|
||||
# Good candidates for background execution:
|
||||
- Full skill audit across all 23 skills
|
||||
- Running Python tests on multiple skills
|
||||
- Generating comprehensive documentation
|
||||
|
||||
# Not suitable for background:
|
||||
- Interactive debugging
|
||||
- Tasks requiring user input
|
||||
- Quick file operations
|
||||
```
|
||||
|
||||
## Agent Handoff Patterns
|
||||
|
||||
### Research → Implementation
|
||||
|
||||
1. **Explore agent**: Gather context and patterns
|
||||
2. **Plan agent**: Design the approach
|
||||
3. **Direct implementation**: Write the code
|
||||
4. **Bash agent**: Test and validate
|
||||
|
||||
### Bug Fix Workflow
|
||||
|
||||
1. **Explore agent**: Find related code and understand the issue
|
||||
2. **Direct implementation**: Fix the bug
|
||||
3. **Bash agent**: Run tests to verify
|
||||
|
||||
### New Skill Creation
|
||||
|
||||
1. **Explore agent**: Study 2-3 similar existing skills
|
||||
2. **Plan agent**: Design skill scope and structure
|
||||
3. **Bash agent**: Run `init_skill.py` to generate boilerplate
|
||||
4. **Direct implementation**: Write SKILL.md/CLAUDE.md and scripts
|
||||
5. **Bash agent**: Validate and test
|
||||
|
||||
## Notes
|
||||
|
||||
- Always prefer **Explore** for open-ended questions about the codebase
|
||||
- Use **Plan** before major changes to get user approval
|
||||
- Direct tool use (Read, Edit, Write) is faster for simple operations
|
||||
- Agents have full context of the conversation when spawned
|
||||
58
CLAUDE.md
58
CLAUDE.md
@@ -4,22 +4,29 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## Repository Overview
|
||||
|
||||
**GitHub**: https://github.com/ourdigital/claude-skills-factory
|
||||
**GitHub**: https://github.com/ourdigital/claude-skills
|
||||
|
||||
This is a Claude Skills collection repository containing:
|
||||
- **custom-skills/**: 22 custom skills for OurDigital workflows, SEO, GTM, and Jamie Brand
|
||||
- **custom-skills/**: 23 custom skills for OurDigital workflows, SEO, GTM, and Jamie Brand
|
||||
- **example-skills/**: Reference examples from Anthropic's official skills repository
|
||||
- **official-skills/**: Notion integration skills (3rd party)
|
||||
- **reference/**: Skill format requirements documentation
|
||||
|
||||
## Custom Skills Summary
|
||||
|
||||
### General Automation (01-09)
|
||||
### Claude Code Settings (00)
|
||||
|
||||
| # | Skill | Purpose | Trigger |
|
||||
|---|-------|---------|---------|
|
||||
| 01 | notion-organizer | Notion workspace management | "organize Notion", "노션 정리" |
|
||||
| 02 | notion-data-migration | Database migration tools | "migrate Notion data" |
|
||||
| 00 | claude-code-setting | Settings optimization & token audit | "audit settings", "optimize Claude Code" |
|
||||
|
||||
### OurDigital Core Workflows (01-09)
|
||||
|
||||
| # | Skill | Purpose | Trigger |
|
||||
|---|-------|---------|---------|
|
||||
| 01 | ourdigital-research | Research → Blog workflow | "research this", "blog post" |
|
||||
| 02 | ourdigital-designer | Visual storytelling, image prompts | "create image prompt", "visual design" |
|
||||
| 03 | ourdigital-presentation | Notion → PPT/Figma | "create presentation" |
|
||||
|
||||
### SEO Tools (10-19)
|
||||
|
||||
@@ -32,32 +39,33 @@ This is a Claude Skills collection repository containing:
|
||||
| 14 | seo-schema-generator | Schema markup creation | "generate schema", "create JSON-LD" |
|
||||
| 15 | seo-core-web-vitals | LCP, CLS, FID, INP metrics | "Core Web Vitals", "page speed" |
|
||||
| 16 | seo-search-console | GSC data analysis | "Search Console", "rankings" |
|
||||
| 17 | seo-gateway-architect | Gateway page strategy | "SEO strategy", "게이트웨이 전략" |
|
||||
| 17 | seo-gateway-architect | Gateway page strategy | "SEO strategy", "gateway pages" |
|
||||
| 18 | seo-gateway-builder | Gateway page content | "build gateway page" |
|
||||
|
||||
### GTM/GA Tools (20-29)
|
||||
|
||||
| # | Skill | Purpose | Trigger |
|
||||
|---|-------|---------|---------|
|
||||
| 20 | gtm-audit | GTM container audit | "audit GTM", "GTM 검사" |
|
||||
| 20 | gtm-audit | GTM container audit | "audit GTM", "GTM analysis" |
|
||||
| 21 | gtm-manager | GTM management + dataLayer | "GTM manager", "dataLayer" |
|
||||
| 22 | gtm-guardian | Live tag monitoring & validation | "monitor GTM", "tag validation" |
|
||||
|
||||
### OurDigital Channel (30-39)
|
||||
### Notion Tools (31-39)
|
||||
|
||||
| # | Skill | Purpose | Trigger |
|
||||
|---|-------|---------|---------|
|
||||
| 30 | ourdigital-designer | Visual storytelling, image prompts | "create image prompt", "블로그 이미지" |
|
||||
| 31 | ourdigital-research | Research → Blog workflow | "research this", "블로그 작성" |
|
||||
| 32 | ourdigital-presentation | Notion → PPT/Figma | "create presentation" |
|
||||
| 31 | notion-organizer | Notion workspace management | "organize Notion", "workspace cleanup" |
|
||||
| 32 | notion-writer | Content writing to Notion | "write to Notion", "export to Notion" |
|
||||
|
||||
### Jamie Clinic (40-49)
|
||||
|
||||
| # | Skill | Purpose | Trigger |
|
||||
|---|-------|---------|---------|
|
||||
| 40 | jamie-brand-editor | Content **generation** | "write Jamie blog", "제이미 콘텐츠" |
|
||||
| 41 | jamie-brand-audit | Content **review/evaluation** | "review content", "브랜드 검토" |
|
||||
| 42 | jamie-instagram-manager | Instagram account management | "Instagram 관리", "인스타 계획" |
|
||||
| 43 | jamie-youtube-manager | YouTube SEO audit & management | "YouTube SEO", "유튜브 검토" |
|
||||
| 40 | jamie-brand-editor | Content **generation** | "write Jamie blog", "Jamie content" |
|
||||
| 41 | jamie-brand-audit | Content **review/evaluation** | "review content", "brand audit" |
|
||||
| 42 | jamie-instagram-manager | Instagram account management | "Instagram management", "IG strategy" |
|
||||
| 43 | jamie-youtube-manager | YouTube SEO audit & management | "YouTube SEO", "YT optimization" |
|
||||
| 44 | jamie-youtube-subtitle-checker | YouTube subtitle validation | "check subtitles", "subtitle QA" |
|
||||
|
||||
## Dual-Platform Skill Structure
|
||||
|
||||
@@ -102,10 +110,13 @@ XX-skill-name/
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
claude-skills-factory/
|
||||
claude-skills/
|
||||
├── custom-skills/
|
||||
│ ├── 01-notion-organizer/
|
||||
│ ├── 02-notion-data-migration/
|
||||
│ ├── 00-claude-code-setting/
|
||||
│ │
|
||||
│ ├── 01-ourdigital-research/
|
||||
│ ├── 02-ourdigital-designer/
|
||||
│ ├── 03-ourdigital-presentation/
|
||||
│ │
|
||||
│ ├── 10-seo-technical-audit/
|
||||
│ ├── 11-seo-on-page-audit/
|
||||
@@ -119,17 +130,18 @@ claude-skills-factory/
|
||||
│ │
|
||||
│ ├── 20-gtm-audit/
|
||||
│ ├── 21-gtm-manager/
|
||||
│ ├── 22-gtm-guardian/
|
||||
│ │
|
||||
│ ├── 30-ourdigital-designer/
|
||||
│ ├── 31-ourdigital-research/
|
||||
│ ├── 32-ourdigital-presentation/
|
||||
│ ├── 31-notion-organizer/
|
||||
│ ├── 32-notion-writer/
|
||||
│ │
|
||||
│ ├── 40-jamie-brand-editor/
|
||||
│ ├── 41-jamie-brand-audit/
|
||||
│ ├── 42-jamie-instagram-manager/
|
||||
│ ├── 43-jamie-youtube-manager/
|
||||
│ ├── 44-jamie-youtube-subtitle-checker/
|
||||
│ │
|
||||
│ └── _archive/
|
||||
│ └── 99_archive/
|
||||
│
|
||||
├── example-skills/skills-main/
|
||||
├── official-skills/
|
||||
@@ -147,3 +159,5 @@ python example-skills/skills-main/skill-creator/scripts/init_skill.py <skill-nam
|
||||
|
||||
- `reference/SKILL-FORMAT-REQUIREMENTS.md` - Format specification
|
||||
- `example-skills/skills-main/skill-creator/SKILL.md` - Skill creation guide
|
||||
- `custom-skills/AUDIT_REPORT.md` - Skills completion status
|
||||
- `custom-skills/REFACTORING_PLAN.md` - Original refactoring plan
|
||||
|
||||
@@ -73,7 +73,7 @@ XX-skill-name/
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
claude-skills-factory/
|
||||
claude-skills/
|
||||
├── custom-skills/ # 20 custom skills for production use
|
||||
├── example-skills/ # Anthropic reference examples
|
||||
├── ga-agent-skills/ # GA Agent decomposed architecture
|
||||
|
||||
@@ -92,8 +92,12 @@ class TokenAnalyzer:
|
||||
return tokens
|
||||
return 5000 # Default estimate
|
||||
|
||||
def get_load_strategy(self, name: str) -> str:
|
||||
"""Get recommended load strategy."""
|
||||
def get_load_strategy(self, name: str, config: dict = None) -> str:
|
||||
"""Get load strategy - checks actual config first, then recommendations."""
|
||||
# Check actual autoStart setting in config
|
||||
if config and config.get("autoStart") is False:
|
||||
return "lazy"
|
||||
|
||||
name_lower = name.lower()
|
||||
for key, strategy in LOAD_STRATEGIES.items():
|
||||
if key in name_lower:
|
||||
@@ -124,7 +128,7 @@ class TokenAnalyzer:
|
||||
|
||||
tokens = self.estimate_server_tokens(name)
|
||||
has_instructions = "serverInstructions" in config
|
||||
strategy = self.get_load_strategy(name)
|
||||
strategy = self.get_load_strategy(name, config)
|
||||
|
||||
self.mcp_servers[name] = {
|
||||
"tokens": tokens,
|
||||
@@ -133,7 +137,9 @@ class TokenAnalyzer:
|
||||
"source": str(settings_path)
|
||||
}
|
||||
|
||||
self.mcp_tokens += tokens
|
||||
# Only count "always" servers for baseline
|
||||
if strategy == "always":
|
||||
self.mcp_tokens += tokens
|
||||
|
||||
# Generate findings
|
||||
if not has_instructions:
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
# Claude Code Settings Optimizer
|
||||
# No external dependencies - uses only Python standard library
|
||||
# json, sys, pathlib are built-in
|
||||
|
||||
# Optional: For future enhancements
|
||||
# pyyaml>=6.0 # YAML parsing for MCP configs
|
||||
# rich>=13.0 # Better terminal output
|
||||
@@ -0,0 +1,181 @@
|
||||
{
|
||||
"timestamp": "2026-01-23T18:06:32.896761",
|
||||
"tokens": {
|
||||
"total_tokens": 18911,
|
||||
"mcp_tokens": 17500,
|
||||
"claude_md_tokens": 1411,
|
||||
"mcp_count": 10,
|
||||
"mcp_servers": {
|
||||
"filesystem": {
|
||||
"tokens": 4000,
|
||||
"has_instructions": true,
|
||||
"strategy": "always",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
},
|
||||
"sqlite": {
|
||||
"tokens": 5000,
|
||||
"has_instructions": true,
|
||||
"strategy": "lazy",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
},
|
||||
"playwright": {
|
||||
"tokens": 13500,
|
||||
"has_instructions": true,
|
||||
"strategy": "always",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
},
|
||||
"figma": {
|
||||
"tokens": 5000,
|
||||
"has_instructions": true,
|
||||
"strategy": "lazy",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
},
|
||||
"osascript": {
|
||||
"tokens": 5000,
|
||||
"has_instructions": true,
|
||||
"strategy": "lazy",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
},
|
||||
"firecrawl": {
|
||||
"tokens": 6000,
|
||||
"has_instructions": true,
|
||||
"strategy": "lazy",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
},
|
||||
"google-analytics": {
|
||||
"tokens": 5000,
|
||||
"has_instructions": true,
|
||||
"strategy": "lazy",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
},
|
||||
"chrome-devtools": {
|
||||
"tokens": 8000,
|
||||
"has_instructions": true,
|
||||
"strategy": "lazy",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
},
|
||||
"exa": {
|
||||
"tokens": 5000,
|
||||
"has_instructions": true,
|
||||
"strategy": "lazy",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
},
|
||||
"dtm-agent": {
|
||||
"tokens": 5000,
|
||||
"has_instructions": true,
|
||||
"strategy": "lazy",
|
||||
"source": "/Users/ourdigital/.claude/settings.json"
|
||||
}
|
||||
},
|
||||
"claude_md_files": [
|
||||
{
|
||||
"path": "/Users/ourdigital/.claude/CLAUDE.md",
|
||||
"lines": 110,
|
||||
"words": 616,
|
||||
"tokens": 800
|
||||
},
|
||||
{
|
||||
"path": "/Users/ourdigital/Project/claude-skills/custom-skills/00-claude-code-setting/code/CLAUDE.md",
|
||||
"lines": 120,
|
||||
"words": 470,
|
||||
"tokens": 611
|
||||
}
|
||||
],
|
||||
"usage_percentage": 9.5,
|
||||
"findings": {
|
||||
"critical": [],
|
||||
"warnings": [],
|
||||
"passing": [
|
||||
"MCP 'filesystem': Has serverInstructions",
|
||||
"MCP 'sqlite': Has serverInstructions",
|
||||
"MCP 'playwright': Has serverInstructions",
|
||||
"MCP 'figma': Has serverInstructions",
|
||||
"MCP 'osascript': Has serverInstructions",
|
||||
"MCP 'firecrawl': Has serverInstructions",
|
||||
"MCP 'google-analytics': Has serverInstructions",
|
||||
"MCP 'chrome-devtools': Has serverInstructions",
|
||||
"MCP 'exa': Has serverInstructions",
|
||||
"MCP 'dtm-agent': Has serverInstructions",
|
||||
"CLAUDE.md (CLAUDE.md): 110 lines, ~800 tokens - Good",
|
||||
"CLAUDE.md (CLAUDE.md): 120 lines, ~611 tokens - Good"
|
||||
],
|
||||
"recommendations": []
|
||||
}
|
||||
},
|
||||
"extensions": {
|
||||
"commands_count": 1,
|
||||
"skills_count": 1,
|
||||
"agents_count": 5,
|
||||
"commands": {
|
||||
"settings-audit": {
|
||||
"name": "settings-audit",
|
||||
"lines": 120,
|
||||
"has_frontmatter": false,
|
||||
"has_description": null,
|
||||
"issues": [
|
||||
"Missing YAML frontmatter",
|
||||
"Too long: 120 lines (max 100)"
|
||||
]
|
||||
}
|
||||
},
|
||||
"skills": {
|
||||
"jamie-brand-guardian": {
|
||||
"name": "jamie-brand-guardian",
|
||||
"lines": 480,
|
||||
"has_frontmatter": true,
|
||||
"has_description": true,
|
||||
"issues": []
|
||||
}
|
||||
},
|
||||
"agents": {
|
||||
"data-analyst": {
|
||||
"name": "data-analyst",
|
||||
"has_frontmatter": true,
|
||||
"tools_restricted": "Read, Glob, Grep, Bash, Write",
|
||||
"issues": []
|
||||
},
|
||||
"seo-advisor": {
|
||||
"name": "seo-advisor",
|
||||
"has_frontmatter": true,
|
||||
"tools_restricted": "Read, Glob, Grep, WebFetch, WebSearch",
|
||||
"issues": []
|
||||
},
|
||||
"python-coach": {
|
||||
"name": "python-coach",
|
||||
"has_frontmatter": true,
|
||||
"tools_restricted": "Read, Glob, Grep, Bash, Write",
|
||||
"issues": []
|
||||
},
|
||||
"gtm-manager": {
|
||||
"name": "gtm-manager",
|
||||
"has_frontmatter": true,
|
||||
"tools_restricted": "Read, Glob, Grep, Bash, WebFetch, mcp__plugin_playwright_playwright__*",
|
||||
"issues": []
|
||||
},
|
||||
"data-engineer": {
|
||||
"name": "data-engineer",
|
||||
"has_frontmatter": true,
|
||||
"tools_restricted": "Read, Glob, Grep, Bash, Write",
|
||||
"issues": []
|
||||
}
|
||||
},
|
||||
"findings": {
|
||||
"critical": [],
|
||||
"warnings": [
|
||||
"Command 'settings-audit': Missing YAML frontmatter",
|
||||
"Command 'settings-audit': Too long: 120 lines (max 100)"
|
||||
],
|
||||
"passing": [
|
||||
"Skill 'jamie-brand-guardian': OK",
|
||||
"Agent 'data-analyst': OK",
|
||||
"Agent 'seo-advisor': OK",
|
||||
"Agent 'python-coach': OK",
|
||||
"Agent 'gtm-manager': OK",
|
||||
"Agent 'data-engineer': OK"
|
||||
],
|
||||
"recommendations": []
|
||||
}
|
||||
},
|
||||
"total_baseline_tokens": 18911,
|
||||
"health": "Good"
|
||||
}
|
||||
@@ -0,0 +1,88 @@
|
||||
# Claude Code Settings Audit Report
|
||||
|
||||
**Generated:** 2026-01-23 18:06:32
|
||||
|
||||
---
|
||||
|
||||
## Token Budget Summary
|
||||
|
||||
| Component | Tokens | % of 200K | Status |
|
||||
|-----------|--------|-----------|--------|
|
||||
| CLAUDE.md | 1,411 | 0.7% | 🟢 |
|
||||
| MCP Servers | 17,500 | 8.8% | 🟡 |
|
||||
| **Baseline Total** | **18,911** | **9.5%** | 🟢 |
|
||||
| **Available for Work** | **181,089** | **90.5%** | — |
|
||||
|
||||
**Target:** Baseline under 30% (60,000 tokens), Available over 70%
|
||||
|
||||
---
|
||||
|
||||
## Overall Health: 🟢 Good
|
||||
|
||||
- Critical Issues: 0
|
||||
- Warnings: 2
|
||||
- Passing Checks: 18
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Analysis
|
||||
|
||||
**Servers:** 10 configured
|
||||
|
||||
| Server | Tokens | Instructions | Strategy |
|
||||
|--------|--------|--------------|----------|
|
||||
| filesystem | ~4,000 | ✅ | always |
|
||||
| sqlite | ~5,000 | ✅ | lazy |
|
||||
| playwright | ~13,500 | ✅ | always |
|
||||
| figma | ~5,000 | ✅ | lazy |
|
||||
| osascript | ~5,000 | ✅ | lazy |
|
||||
| firecrawl | ~6,000 | ✅ | lazy |
|
||||
| google-analytics | ~5,000 | ✅ | lazy |
|
||||
| chrome-devtools | ~8,000 | ✅ | lazy |
|
||||
| exa | ~5,000 | ✅ | lazy |
|
||||
| dtm-agent | ~5,000 | ✅ | lazy |
|
||||
|
||||
---
|
||||
|
||||
## CLAUDE.md Analysis
|
||||
|
||||
- **/Users/ourdigital/.claude/CLAUDE.md**: 110 lines, ~800 tokens 🟢
|
||||
- **/Users/ourdigital/Project/claude-skills/custom-skills/00-claude-code-setting/code/CLAUDE.md**: 120 lines, ~611 tokens 🟢
|
||||
|
||||
---
|
||||
|
||||
## Extensions Analysis
|
||||
|
||||
- Commands: 1
|
||||
- Skills: 1
|
||||
- Agents: 5
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Warnings
|
||||
|
||||
- Command 'settings-audit': Missing YAML frontmatter
|
||||
- Command 'settings-audit': Too long: 120 lines (max 100)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Passing
|
||||
|
||||
- MCP 'filesystem': Has serverInstructions
|
||||
- MCP 'sqlite': Has serverInstructions
|
||||
- MCP 'playwright': Has serverInstructions
|
||||
- MCP 'figma': Has serverInstructions
|
||||
- MCP 'osascript': Has serverInstructions
|
||||
- *...and 13 more*
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Run `python3 scripts/auto_fix.py` to preview fixes
|
||||
2. Run `python3 scripts/auto_fix.py --apply` to apply fixes
|
||||
3. Re-run audit to verify improvements
|
||||
|
||||
---
|
||||
|
||||
*Generated by Claude Code Settings Optimizer*
|
||||
@@ -82,7 +82,7 @@ GTM Guardian은 GTM 태깅의 전체 라이프사이클을 체계적으로 관
|
||||
|
||||
## Related Resources
|
||||
|
||||
- [D.intelligence GTM Toolkit](https://github.com/ourdigital/dintel-gtm-toolkit)
|
||||
- [D.intelligence GTM Toolkit](https://github.com/ourdigital/dintel-gtm-agent)
|
||||
- [GTM Knowledge Base (Notion)](https://www.notion.so/dintelligence/2cf581e58a1e80c8b358f1625356e931)
|
||||
|
||||
## Triggers
|
||||
|
||||
@@ -10,7 +10,7 @@ GTM 태깅 라이프사이클의 자동화 및 유지보수 단계를 지원하
|
||||
|
||||
```bash
|
||||
# D.intelligence GTM Toolkit 클론
|
||||
git clone https://github.com/ourdigital/dintel-gtm-toolkit.git
|
||||
git clone https://github.com/ourdigital/dintel-gtm-agent.git
|
||||
|
||||
# GTM Container 분석
|
||||
python analyze_container.py GTM-XXXXXX.json --output report.md
|
||||
@@ -33,7 +33,7 @@ python find_unused.py container.json --type all
|
||||
|
||||
### D.intelligence GTM Toolkit Integration
|
||||
|
||||
**Repository**: https://github.com/ourdigital/dintel-gtm-toolkit
|
||||
**Repository**: https://github.com/ourdigital/dintel-gtm-agent
|
||||
|
||||
### Capabilities
|
||||
|
||||
@@ -123,7 +123,7 @@ Google Apps Script 기반 Event Taxonomy 조회 앱 배포.
|
||||
|
||||
### Container 분석 실행
|
||||
```bash
|
||||
cd dintel-gtm-toolkit
|
||||
cd dintel-gtm-agent
|
||||
python analyze_container.py /path/to/GTM-XXXXXX.json \
|
||||
--output /path/to/report.md \
|
||||
--format markdown
|
||||
|
||||
@@ -48,7 +48,7 @@
|
||||
|
||||
### Repository
|
||||
```
|
||||
https://github.com/ourdigital/dintel-gtm-toolkit
|
||||
https://github.com/ourdigital/dintel-gtm-agent
|
||||
```
|
||||
|
||||
### Capabilities
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
메인 분석 도구는 별도 레포지토리에서 관리됩니다:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/ourdigital/dintel-gtm-toolkit.git
|
||||
git clone https://github.com/ourdigital/dintel-gtm-agent.git
|
||||
```
|
||||
|
||||
## 사용법
|
||||
|
||||
@@ -39,7 +39,7 @@
|
||||
### 3. Configure Environment
|
||||
|
||||
```bash
|
||||
cd ~/Project/claude-skills-factory/custom-skills/02-notion-writer/code/scripts
|
||||
cd ~/Project/claude-skills/custom-skills/02-notion-writer/code/scripts
|
||||
|
||||
# Create .env from example
|
||||
cp .env.example .env
|
||||
@@ -212,7 +212,7 @@ The script automatically batches large content.
|
||||
|
||||
```bash
|
||||
# Navigate
|
||||
cd ~/Project/claude-skills-factory/custom-skills/02-notion-writer/code/scripts
|
||||
cd ~/Project/claude-skills/custom-skills/02-notion-writer/code/scripts
|
||||
source venv/bin/activate
|
||||
|
||||
# Test
|
||||
@@ -0,0 +1,5 @@
|
||||
# Notion Writer
|
||||
# Push markdown content to Notion pages or databases
|
||||
|
||||
python-dotenv>=1.0.0 # Environment variable management
|
||||
notion-client>=2.0.0 # Official Notion API client
|
||||
@@ -10,14 +10,14 @@ Push markdown content to Notion pages or databases via Claude Code.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python virtual environment at `~/Project/claude-skills-factory/custom-skills/02-notion-writer/code/scripts/venv`
|
||||
- Python virtual environment at `~/Project/claude-skills/custom-skills/02-notion-writer/code/scripts/venv`
|
||||
- Notion API key configured in `.env` file
|
||||
- Target pages/databases must be shared with the integration
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
cd ~/Project/claude-skills-factory/custom-skills/02-notion-writer/code/scripts
|
||||
cd ~/Project/claude-skills/custom-skills/02-notion-writer/code/scripts
|
||||
source venv/bin/activate
|
||||
```
|
||||
|
||||
@@ -35,7 +35,7 @@
|
||||
|
||||
```bash
|
||||
# Navigate to scripts directory
|
||||
cd ~/Project/claude-skills-factory/custom-skills/43-jamie-youtube-manager/code/scripts
|
||||
cd ~/Project/claude-skills/custom-skills/43-jamie-youtube-manager/code/scripts
|
||||
|
||||
# Activate virtual environment
|
||||
source venv/bin/activate
|
||||
@@ -511,7 +511,7 @@ User: "영어 자막/메타데이터 추천해줘"
|
||||
|
||||
```bash
|
||||
# Navigate to scripts directory
|
||||
cd ~/Project/claude-skills-factory/custom-skills/43-jamie-youtube-manager/code/scripts
|
||||
cd ~/Project/claude-skills/custom-skills/43-jamie-youtube-manager/code/scripts
|
||||
|
||||
# Activate environment
|
||||
source venv/bin/activate
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
# Jamie YouTube Manager
|
||||
# YouTube SEO Auditor & Content Manager for Jamie Plastic Surgery Clinic
|
||||
|
||||
python-dotenv>=1.0.0 # Environment variable management
|
||||
google-api-python-client>=2.100.0 # YouTube Data API v3
|
||||
google-auth-oauthlib>=1.2.0 # OAuth 2.0 authentication
|
||||
google-auth>=2.23.0 # Google authentication library
|
||||
@@ -20,7 +20,7 @@ license: Internal-use Only
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
cd ~/Project/claude-skills-factory/custom-skills/43-jamie-youtube-manager/code/scripts
|
||||
cd ~/Project/claude-skills/custom-skills/43-jamie-youtube-manager/code/scripts
|
||||
source venv/bin/activate
|
||||
```
|
||||
|
||||
@@ -49,7 +49,7 @@ python jamie_video_info.py "https://youtu.be/VIDEO_ID"
|
||||
```bash
|
||||
# Save video info to Notion
|
||||
python jamie_video_info.py "URL" > ../output/video_status.md
|
||||
cd ~/Project/claude-skills-factory/custom-skills/02-notion-writer/code/scripts
|
||||
cd ~/Project/claude-skills/custom-skills/02-notion-writer/code/scripts
|
||||
source venv/bin/activate
|
||||
python notion_writer.py -p NOTION_PAGE_URL -f ../../43-jamie-youtube-manager/code/output/video_status.md
|
||||
```
|
||||
|
||||
@@ -1,119 +1,158 @@
|
||||
# Skills Audit Report
|
||||
|
||||
Generated: 2024-12-21
|
||||
**Generated**: 2025-01-23
|
||||
**Previous Audit**: 2024-12-21
|
||||
|
||||
## Summary
|
||||
|
||||
| Status | Count |
|
||||
|--------|-------|
|
||||
| Complete (code + desktop) | 8 |
|
||||
| Partial (missing CLAUDE.md or scripts) | 9 |
|
||||
| Empty (placeholder only) | 1 |
|
||||
| Status | Count | Change |
|
||||
|--------|-------|--------|
|
||||
| Complete (code + desktop) | 19 | +11 |
|
||||
| Partial (missing desktop or scripts) | 4 | -5 |
|
||||
| Total Skills | 23 | +5 new |
|
||||
|
||||
### Key Improvements Since Last Audit
|
||||
|
||||
1. **All 23 skills now have `code/CLAUDE.md`** (was 8)
|
||||
2. **Reorganized numbering scheme** - OurDigital moved to 01-03, Notion to 31-32
|
||||
3. **5 new skills added**: 00-claude-code-setting, 22-gtm-guardian, 44-jamie-youtube-subtitle-checker
|
||||
4. **notion-data-migration renamed to notion-writer** (32)
|
||||
|
||||
---
|
||||
|
||||
## Detailed Audit by Skill
|
||||
|
||||
### 01-09: General Automation
|
||||
### Claude Code Settings (00)
|
||||
|
||||
| # | Skill | code/CLAUDE.md | code/scripts | code/requirements.txt | desktop/SKILL.md | Status |
|
||||
|---|-------|----------------|--------------|----------------------|------------------|--------|
|
||||
| 01 | notion-organizer | **MISSING** | async_organizer.py, schema_migrator.py | YES | YES | Partial |
|
||||
| 02 | notion-data-migration | **MISSING** | **EMPTY** | **MISSING** | **MISSING** | Empty |
|
||||
| # | Skill | code/CLAUDE.md | desktop/SKILL.md | Scripts | Status |
|
||||
|---|-------|----------------|------------------|---------|--------|
|
||||
| 00 | claude-code-setting | YES | **MISSING** | 4 | Partial |
|
||||
|
||||
### 10-19: SEO Tools
|
||||
### OurDigital Core (01-09)
|
||||
|
||||
| # | Skill | code/CLAUDE.md | code/scripts | code/requirements.txt | desktop/SKILL.md | Status |
|
||||
|---|-------|----------------|--------------|----------------------|------------------|--------|
|
||||
| 10 | seo-technical-audit | YES | robots_checker, sitemap_validator, sitemap_crawler, page_analyzer, base_client | YES | YES | **Complete** |
|
||||
| 11 | seo-on-page-audit | YES | page_analyzer, base_client | YES | YES | **Complete** |
|
||||
| 12 | seo-local-audit | YES | **EMPTY** (new skill) | **MISSING** | YES | Partial |
|
||||
| 13 | seo-schema-validator | YES | schema_validator, base_client | YES | YES | **Complete** |
|
||||
| 14 | seo-schema-generator | YES | schema_generator, base_client + templates/ | YES | YES | **Complete** |
|
||||
| 15 | seo-core-web-vitals | YES | pagespeed_client, base_client | YES | YES | **Complete** |
|
||||
| 16 | seo-search-console | YES | gsc_client, base_client | YES | YES | **Complete** |
|
||||
| 17 | seo-gateway-architect | **MISSING** | keyword_analyzer.py | YES | YES | Partial |
|
||||
| 18 | seo-gateway-builder | **MISSING** | generate_pages.py | **MISSING** | YES | Partial |
|
||||
| # | Skill | code/CLAUDE.md | desktop/SKILL.md | Scripts | Status |
|
||||
|---|-------|----------------|------------------|---------|--------|
|
||||
| 01 | ourdigital-research | YES | YES | 1 | **Complete** |
|
||||
| 02 | ourdigital-designer | YES | YES | 2 | **Complete** |
|
||||
| 03 | ourdigital-presentation | YES | YES | 4 | **Complete** |
|
||||
|
||||
### 20-29: GTM/GA Tools
|
||||
### SEO Tools (10-19)
|
||||
|
||||
| # | Skill | code/CLAUDE.md | code/scripts | code/requirements.txt | desktop/SKILL.md | Status |
|
||||
|---|-------|----------------|--------------|----------------------|------------------|--------|
|
||||
| 20 | gtm-audit | YES | gtm_audit.py | YES | YES | **Complete** |
|
||||
| 21 | gtm-manager | YES | gtm_manager.py + docs/ | YES | YES | **Complete** |
|
||||
| # | Skill | code/CLAUDE.md | desktop/SKILL.md | Scripts | Status |
|
||||
|---|-------|----------------|------------------|---------|--------|
|
||||
| 10 | seo-technical-audit | YES | YES | 5 | **Complete** |
|
||||
| 11 | seo-on-page-audit | YES | YES | 2 | **Complete** |
|
||||
| 12 | seo-local-audit | YES | YES | 0 (guidance) | **Complete** |
|
||||
| 13 | seo-schema-validator | YES | YES | 2 | **Complete** |
|
||||
| 14 | seo-schema-generator | YES | YES | 2 | **Complete** |
|
||||
| 15 | seo-core-web-vitals | YES | YES | 2 | **Complete** |
|
||||
| 16 | seo-search-console | YES | YES | 2 | **Complete** |
|
||||
| 17 | seo-gateway-architect | YES | YES | 1 | **Complete** |
|
||||
| 18 | seo-gateway-builder | YES | YES | 1 | **Complete** |
|
||||
|
||||
### 30-39: OurDigital Channel
|
||||
### GTM/GA Tools (20-29)
|
||||
|
||||
| # | Skill | code/CLAUDE.md | code/scripts | code/requirements.txt | desktop/SKILL.md | Status |
|
||||
|---|-------|----------------|--------------|----------------------|------------------|--------|
|
||||
| 30 | ourdigital-designer | **MISSING** | generate_prompt.py, mood_calibrator.py | **MISSING** | YES | Partial |
|
||||
| 31 | ourdigital-research | **MISSING** | export_to_ulysses.py | **MISSING** | YES | Partial |
|
||||
| 32 | ourdigital-presentation | **MISSING** | apply_brand.py, extract_notion.py, run_workflow.py, synthesize_content.py | **MISSING** | YES | Partial |
|
||||
| # | Skill | code/CLAUDE.md | desktop/SKILL.md | Scripts | Status |
|
||||
|---|-------|----------------|------------------|---------|--------|
|
||||
| 20 | gtm-audit | YES | YES | 1 | **Complete** |
|
||||
| 21 | gtm-manager | YES | **MISSING** | 1 | Partial |
|
||||
| 22 | gtm-guardian | YES | YES | 0 (guidance) | **Complete** |
|
||||
|
||||
### 40-49: Jamie Clinic
|
||||
### Notion Tools (31-39)
|
||||
|
||||
| # | Skill | code/CLAUDE.md | code/scripts | code/requirements.txt | desktop/SKILL.md | Status |
|
||||
|---|-------|----------------|--------------|----------------------|------------------|--------|
|
||||
| 40 | jamie-brand-editor | **MISSING** | compliance_checker.py | **MISSING** | YES | Partial |
|
||||
| 41 | jamie-brand-audit | **MISSING** | **EMPTY** | **MISSING** | YES | Partial |
|
||||
| # | Skill | code/CLAUDE.md | desktop/SKILL.md | Scripts | Status |
|
||||
|---|-------|----------------|------------------|---------|--------|
|
||||
| 31 | notion-organizer | YES | YES | 2 | **Complete** |
|
||||
| 32 | notion-writer | YES | YES | 1 | **Complete** |
|
||||
|
||||
### Jamie Clinic (40-49)
|
||||
|
||||
| # | Skill | code/CLAUDE.md | desktop/SKILL.md | Scripts | Status |
|
||||
|---|-------|----------------|------------------|---------|--------|
|
||||
| 40 | jamie-brand-editor | YES | YES | 1 | **Complete** |
|
||||
| 41 | jamie-brand-audit | YES | YES | 0 (guidance) | **Complete** |
|
||||
| 42 | jamie-instagram-manager | YES | YES | 0 (guidance) | **Complete** |
|
||||
| 43 | jamie-youtube-manager | YES | YES | 4 | **Complete** |
|
||||
| 44 | jamie-youtube-subtitle-checker | YES | YES | 0 (guidance) | **Complete** |
|
||||
|
||||
---
|
||||
|
||||
## Issues to Fix
|
||||
|
||||
### Priority 1: Missing CLAUDE.md (Claude Code directive)
|
||||
### Priority 1: Missing desktop/SKILL.md
|
||||
|
||||
| Skill | Has Scripts | Action |
|
||||
|-------|-------------|--------|
|
||||
| 01-notion-organizer | YES | Create CLAUDE.md |
|
||||
| 17-seo-gateway-architect | YES | Create CLAUDE.md |
|
||||
| 18-seo-gateway-builder | YES | Create CLAUDE.md |
|
||||
| 30-ourdigital-designer | YES | Create CLAUDE.md |
|
||||
| 31-ourdigital-research | YES | Create CLAUDE.md |
|
||||
| 32-ourdigital-presentation | YES | Create CLAUDE.md |
|
||||
| 40-jamie-brand-editor | YES | Create CLAUDE.md |
|
||||
| 41-jamie-brand-audit | NO | Create CLAUDE.md (guidance only) |
|
||||
| 00-claude-code-setting | YES (4) | Create desktop/SKILL.md |
|
||||
| 21-gtm-manager | YES (1) | Create desktop/SKILL.md |
|
||||
|
||||
### Priority 2: Missing requirements.txt
|
||||
### Priority 2: Guidance-Only Skills (No Scripts - Intentional)
|
||||
|
||||
| Skill | Scripts Present | Action |
|
||||
|-------|-----------------|--------|
|
||||
| 12-seo-local-audit | NO | Skip (no scripts) |
|
||||
| 18-seo-gateway-builder | YES | Create requirements.txt |
|
||||
| 30-ourdigital-designer | YES | Create requirements.txt |
|
||||
| 31-ourdigital-research | YES | Create requirements.txt |
|
||||
| 32-ourdigital-presentation | YES | Create requirements.txt |
|
||||
| 40-jamie-brand-editor | YES | Create requirements.txt |
|
||||
These skills are designed to work through MCP tools or direct guidance:
|
||||
|
||||
### Priority 3: Empty/Placeholder Skills
|
||||
|
||||
| Skill | Action |
|
||||
| Skill | Reason |
|
||||
|-------|--------|
|
||||
| 02-notion-data-migration | Decide: implement or remove |
|
||||
| 12-seo-local-audit | Implement scripts or make guidance-only |
|
||||
| 41-jamie-brand-audit | Already guidance-only (has references, no scripts needed) |
|
||||
| 12-seo-local-audit | Uses MCP tools for NAP/GBP checks |
|
||||
| 22-gtm-guardian | Uses Chrome DevTools MCP + DTM Agent |
|
||||
| 41-jamie-brand-audit | Review/evaluation guidance only |
|
||||
| 42-jamie-instagram-manager | Strategy/planning guidance |
|
||||
| 44-jamie-youtube-subtitle-checker | QA workflow guidance |
|
||||
|
||||
---
|
||||
|
||||
## Complete Skills (Ready to Use)
|
||||
## Completion Metrics
|
||||
|
||||
These skills have all required components:
|
||||
### By Domain
|
||||
|
||||
1. **10-seo-technical-audit** - Robots.txt, sitemap validation
|
||||
2. **11-seo-on-page-audit** - Page meta tags, headings
|
||||
3. **13-seo-schema-validator** - Structured data validation
|
||||
4. **14-seo-schema-generator** - Schema markup generation
|
||||
5. **15-seo-core-web-vitals** - PageSpeed Insights
|
||||
6. **16-seo-search-console** - GSC data retrieval
|
||||
7. **20-gtm-audit** - GTM container audit
|
||||
8. **21-gtm-manager** - GTM management + injection
|
||||
| Domain | Complete | Partial | Total |
|
||||
|--------|----------|---------|-------|
|
||||
| Claude Code Settings | 0 | 1 | 1 |
|
||||
| OurDigital Core | 3 | 0 | 3 |
|
||||
| SEO Tools | 9 | 0 | 9 |
|
||||
| GTM/GA Tools | 2 | 1 | 3 |
|
||||
| Notion Tools | 2 | 0 | 2 |
|
||||
| Jamie Clinic | 5 | 0 | 5 |
|
||||
| **Total** | **21** | **2** | **23** |
|
||||
|
||||
### Overall Progress
|
||||
|
||||
```
|
||||
Complete: [====================] 91% (21/23)
|
||||
Partial: [== ] 9% (2/23)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
## Requirements.txt Coverage
|
||||
|
||||
1. **Create missing CLAUDE.md files** for skills with existing scripts (8 files needed)
|
||||
2. **Create missing requirements.txt** for skills with scripts (5 files needed)
|
||||
3. **12-seo-local-audit**: Keep as guidance-only skill (no scripts needed - uses MCP tools)
|
||||
4. **41-jamie-brand-audit**: Keep as guidance-only (uses desktop/references for review criteria)
|
||||
5. **02-notion-data-migration**: Either implement or remove from directory
|
||||
Skills with `code/scripts/requirements.txt`:
|
||||
|
||||
1. 01-ourdigital-research
|
||||
2. 02-ourdigital-designer
|
||||
3. 03-ourdigital-presentation
|
||||
4. 10-seo-technical-audit
|
||||
5. 11-seo-on-page-audit
|
||||
6. 13-seo-schema-validator
|
||||
7. 14-seo-schema-generator
|
||||
8. 15-seo-core-web-vitals
|
||||
9. 16-seo-search-console
|
||||
10. 17-seo-gateway-architect
|
||||
11. 18-seo-gateway-builder
|
||||
12. 20-gtm-audit
|
||||
13. 21-gtm-manager
|
||||
14. 31-notion-organizer
|
||||
15. 40-jamie-brand-editor
|
||||
|
||||
**All skills with scripts now have requirements.txt**
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Create desktop/SKILL.md** for:
|
||||
- 00-claude-code-setting
|
||||
- 21-gtm-manager
|
||||
|
||||
2. ~~**Add requirements.txt**~~ - Completed 2025-01-23
|
||||
|
||||
3. ~~**Archive REFACTORING_PLAN.md**~~ - Moved to `99_archive/` on 2025-01-23
|
||||
|
||||
26
ga-agent-skills/.gitignore
vendored
26
ga-agent-skills/.gitignore
vendored
@@ -1,26 +0,0 @@
|
||||
# Credentials - NEVER commit these
|
||||
config/*.json
|
||||
config/*.key
|
||||
*.credentials.json
|
||||
service-account*.json
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
*.env
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.pyc
|
||||
.venv/
|
||||
venv/
|
||||
|
||||
# Node
|
||||
node_modules/
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
@@ -1,143 +0,0 @@
|
||||
# Component 1: MCP Setup
|
||||
|
||||
**Type:** Infrastructure
|
||||
**Priority:** P0
|
||||
**Status:** Not Started
|
||||
|
||||
## Goal
|
||||
|
||||
Install and configure GA4 + BigQuery MCP servers for Claude Code.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Google Cloud account
|
||||
- GA4 property access
|
||||
- `gcloud` CLI installed
|
||||
|
||||
## Setup Steps
|
||||
|
||||
### Step 1: Google Cloud Project
|
||||
|
||||
```bash
|
||||
# Authenticate
|
||||
gcloud auth login
|
||||
|
||||
# Set project (create if needed)
|
||||
gcloud config set project YOUR_PROJECT_ID
|
||||
|
||||
# Enable APIs
|
||||
gcloud services enable \
|
||||
analyticsdata.googleapis.com \
|
||||
analyticsadmin.googleapis.com \
|
||||
bigquery.googleapis.com
|
||||
```
|
||||
|
||||
### Step 2: Service Account
|
||||
|
||||
```bash
|
||||
# Create service account
|
||||
gcloud iam service-accounts create ga-mcp-agent \
|
||||
--display-name="GA MCP Agent"
|
||||
|
||||
# Get email
|
||||
SA_EMAIL="ga-mcp-agent@YOUR_PROJECT_ID.iam.gserviceaccount.com"
|
||||
|
||||
# Grant BigQuery roles
|
||||
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
|
||||
--member="serviceAccount:$SA_EMAIL" \
|
||||
--role="roles/bigquery.dataViewer"
|
||||
|
||||
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
|
||||
--member="serviceAccount:$SA_EMAIL" \
|
||||
--role="roles/bigquery.jobUser"
|
||||
|
||||
# Download key
|
||||
gcloud iam service-accounts keys create \
|
||||
../config/service-account.json \
|
||||
--iam-account=$SA_EMAIL
|
||||
```
|
||||
|
||||
### Step 3: GA4 Property Access
|
||||
|
||||
1. Go to [GA4 Admin](https://analytics.google.com/)
|
||||
2. Property → Property Access Management
|
||||
3. Add user: `ga-mcp-agent@YOUR_PROJECT_ID.iam.gserviceaccount.com`
|
||||
4. Role: Viewer
|
||||
|
||||
### Step 4: Install GA4 MCP Server
|
||||
|
||||
```bash
|
||||
# Clone official server
|
||||
git clone https://github.com/googleanalytics/google-analytics-mcp.git
|
||||
cd google-analytics-mcp
|
||||
|
||||
# Setup Python environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -e .
|
||||
|
||||
# Test
|
||||
export GOOGLE_APPLICATION_CREDENTIALS="../config/service-account.json"
|
||||
python -m google_analytics_mcp --help
|
||||
```
|
||||
|
||||
### Step 5: Install BigQuery MCP Server
|
||||
|
||||
```bash
|
||||
# Test with npx (no install needed)
|
||||
npx -y @ergut/mcp-bigquery-server \
|
||||
--project-id YOUR_PROJECT_ID \
|
||||
--location us-central1 \
|
||||
--key-file ../config/service-account.json
|
||||
```
|
||||
|
||||
### Step 6: Configure Claude Code
|
||||
|
||||
Add to `~/.claude/mcp_servers.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"google-analytics": {
|
||||
"command": "python",
|
||||
"args": ["-m", "google_analytics_mcp"],
|
||||
"cwd": "/path/to/google-analytics-mcp",
|
||||
"env": {
|
||||
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
|
||||
}
|
||||
},
|
||||
"bigquery": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@ergut/mcp-bigquery-server",
|
||||
"--project-id", "YOUR_PROJECT_ID",
|
||||
"--location", "us-central1",
|
||||
"--key-file", "/path/to/service-account.json"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 7: Verify
|
||||
|
||||
```bash
|
||||
# Restart Claude Code, then:
|
||||
mcp-cli servers
|
||||
# Should show: google-analytics, bigquery
|
||||
|
||||
mcp-cli tools google-analytics
|
||||
mcp-cli tools bigquery
|
||||
```
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] GCP project configured
|
||||
- [ ] APIs enabled
|
||||
- [ ] Service account created
|
||||
- [ ] GA4 access granted
|
||||
- [ ] GA4 MCP installed
|
||||
- [ ] BigQuery MCP installed
|
||||
- [ ] Claude Code configured
|
||||
- [ ] Connection verified
|
||||
@@ -1,117 +0,0 @@
|
||||
# Component 2: GA Agent Skill
|
||||
|
||||
**Type:** Claude Skill
|
||||
**Priority:** P0
|
||||
**Status:** Not Started
|
||||
**Final Location:** `ourdigital-custom-skills/15-ourdigital-ga-agent/`
|
||||
|
||||
## Goal
|
||||
|
||||
Interactive GA4 analysis and reporting skill for Claude Code.
|
||||
|
||||
## Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| Traffic Analysis | Users, sessions, pageviews with trends |
|
||||
| Period Comparison | WoW, MoM, YoY comparisons |
|
||||
| Top Content | Pages, sources, campaigns |
|
||||
| Report Generation | HTML reports |
|
||||
| BigQuery Queries | Complex analysis on exported data |
|
||||
|
||||
## Triggers
|
||||
|
||||
**English:**
|
||||
- "Analyze GA4 traffic"
|
||||
- "Compare last week vs this week"
|
||||
- "Generate traffic report"
|
||||
- "Top landing pages"
|
||||
- "Query BigQuery for GA data"
|
||||
|
||||
**Korean:**
|
||||
- "GA4 트래픽 분석"
|
||||
- "지난주 대비 비교"
|
||||
- "트래픽 리포트 생성"
|
||||
- "인기 랜딩 페이지"
|
||||
- "BigQuery GA 데이터 조회"
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
15-ourdigital-ga-agent/
|
||||
├── SKILL.md # Skill definition
|
||||
├── scripts/
|
||||
│ ├── analyze_traffic.py # Traffic analysis
|
||||
│ ├── compare_periods.py # Period comparisons
|
||||
│ ├── top_content.py # Top pages/sources
|
||||
│ └── generate_report.py # HTML report generation
|
||||
├── templates/
|
||||
│ └── report.html # Report template
|
||||
├── references/
|
||||
│ └── ga4-api-reference.md # Quick API reference
|
||||
└── examples/
|
||||
└── sample-queries.md # Example usage
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Requires Component 1 (MCP Setup) to be complete.
|
||||
|
||||
## Scripts
|
||||
|
||||
### analyze_traffic.py
|
||||
|
||||
Fetches traffic metrics for a date range:
|
||||
- Active users
|
||||
- Sessions
|
||||
- Pageviews
|
||||
- Bounce rate
|
||||
- Session duration
|
||||
|
||||
### compare_periods.py
|
||||
|
||||
Compares metrics between two periods:
|
||||
- Current vs previous period
|
||||
- Percentage changes
|
||||
- Trend indicators
|
||||
|
||||
### top_content.py
|
||||
|
||||
Lists top performing content:
|
||||
- Landing pages
|
||||
- Traffic sources
|
||||
- Campaigns
|
||||
- Countries/cities
|
||||
|
||||
### generate_report.py
|
||||
|
||||
Generates HTML report with:
|
||||
- Summary metrics
|
||||
- Charts (via Plotly)
|
||||
- Top content tables
|
||||
- Period comparison
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Work in this directory
|
||||
cd 02-ga-agent-skill
|
||||
|
||||
# Create skill structure
|
||||
mkdir -p skill/{scripts,templates,references,examples}
|
||||
|
||||
# When complete, move to final location
|
||||
mv skill ../ourdigital-custom-skills/15-ourdigital-ga-agent
|
||||
```
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] SKILL.md created
|
||||
- [ ] analyze_traffic.py
|
||||
- [ ] compare_periods.py
|
||||
- [ ] top_content.py
|
||||
- [ ] generate_report.py
|
||||
- [ ] report.html template
|
||||
- [ ] Examples documented
|
||||
- [ ] Tested with Claude Code
|
||||
- [ ] Moved to ourdigital-custom-skills/
|
||||
@@ -1,154 +0,0 @@
|
||||
# Component 3: Dimension Explorer
|
||||
|
||||
**Type:** Utility (MCP Server / CLI / Reference)
|
||||
**Priority:** P1
|
||||
**Status:** Not Started
|
||||
|
||||
## Goal
|
||||
|
||||
Validate GA4 dimensions and metrics with detailed explanations.
|
||||
|
||||
## Features
|
||||
|
||||
- List all available dimensions/metrics
|
||||
- Validate if a dimension/metric exists
|
||||
- Get description, data type, category
|
||||
- Fuzzy search for typos
|
||||
- Compatibility checking
|
||||
|
||||
## Implementation Options
|
||||
|
||||
| Option | Approach | Effort |
|
||||
|--------|----------|--------|
|
||||
| A | Reference JSON in skill | Low |
|
||||
| B | CLI tool | Low |
|
||||
| C | MCP Server | Medium |
|
||||
|
||||
**Recommendation:** Start with A, upgrade to C later.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
03-dimension-explorer/
|
||||
├── README.md
|
||||
├── fetch_metadata.py # Fetch from GA4 Admin API
|
||||
├── data/
|
||||
│ ├── dimensions.json # All dimensions
|
||||
│ └── metrics.json # All metrics
|
||||
├── explorer.py # CLI tool (optional)
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
## Data Format
|
||||
|
||||
### dimensions.json
|
||||
|
||||
```json
|
||||
{
|
||||
"dimensions": [
|
||||
{
|
||||
"apiName": "sessionSource",
|
||||
"uiName": "Session source",
|
||||
"description": "The source that initiated a session",
|
||||
"category": "Traffic source",
|
||||
"deprecatedApiNames": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### metrics.json
|
||||
|
||||
```json
|
||||
{
|
||||
"metrics": [
|
||||
{
|
||||
"apiName": "activeUsers",
|
||||
"uiName": "Active users",
|
||||
"description": "Number of distinct users who visited",
|
||||
"category": "User",
|
||||
"type": "TYPE_INTEGER",
|
||||
"expression": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## fetch_metadata.py
|
||||
|
||||
```python
|
||||
from google.analytics.admin import AnalyticsAdminServiceClient
|
||||
|
||||
def fetch_metadata(property_id: str):
|
||||
"""Fetch all dimensions and metrics for a property."""
|
||||
client = AnalyticsAdminServiceClient()
|
||||
|
||||
# Get metadata
|
||||
metadata = client.get_metadata(
|
||||
name=f"properties/{property_id}/metadata"
|
||||
)
|
||||
|
||||
dimensions = [
|
||||
{
|
||||
"apiName": d.api_name,
|
||||
"uiName": d.ui_name,
|
||||
"description": d.description,
|
||||
"category": d.category,
|
||||
}
|
||||
for d in metadata.dimensions
|
||||
]
|
||||
|
||||
metrics = [
|
||||
{
|
||||
"apiName": m.api_name,
|
||||
"uiName": m.ui_name,
|
||||
"description": m.description,
|
||||
"category": m.category,
|
||||
"type": m.type_.name,
|
||||
}
|
||||
for m in metadata.metrics
|
||||
]
|
||||
|
||||
return {"dimensions": dimensions, "metrics": metrics}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### As Reference (Option A)
|
||||
|
||||
Include `data/dimensions.json` and `data/metrics.json` in the GA Agent skill's `references/` folder.
|
||||
|
||||
### As CLI (Option B)
|
||||
|
||||
```bash
|
||||
# Validate a dimension
|
||||
python explorer.py validate --dimension sessionSource
|
||||
|
||||
# Search for metrics
|
||||
python explorer.py search --query "user"
|
||||
|
||||
# List by category
|
||||
python explorer.py list --category "Traffic source"
|
||||
```
|
||||
|
||||
### As MCP Server (Option C)
|
||||
|
||||
```bash
|
||||
# Run server
|
||||
python server.py
|
||||
|
||||
# Claude can use tools like:
|
||||
# - validate_dimension
|
||||
# - validate_metric
|
||||
# - search_metadata
|
||||
# - list_by_category
|
||||
```
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] fetch_metadata.py created
|
||||
- [ ] Metadata fetched and saved
|
||||
- [ ] dimensions.json generated
|
||||
- [ ] metrics.json generated
|
||||
- [ ] explorer.py (optional)
|
||||
- [ ] Integrated with GA Agent skill
|
||||
@@ -1,160 +0,0 @@
|
||||
# Component 4: Slack Reporter
|
||||
|
||||
**Type:** Standalone Service
|
||||
**Priority:** P2
|
||||
**Status:** Not Started
|
||||
|
||||
## Goal
|
||||
|
||||
Automated GA4 reports delivered to Slack channels.
|
||||
|
||||
## Features
|
||||
|
||||
| Report | Schedule | Content |
|
||||
|--------|----------|---------|
|
||||
| Daily Summary | 9:00 AM | Users, sessions, top 5 pages |
|
||||
| Weekly Digest | Monday 9 AM | WoW comparison, trends |
|
||||
| Anomaly Alert | Real-time | Traffic ±30% from baseline |
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
04-slack-reporter/
|
||||
├── README.md
|
||||
├── config.yaml # Configuration
|
||||
├── reporter.py # Main service
|
||||
├── queries/
|
||||
│ ├── daily_summary.py
|
||||
│ ├── weekly_digest.py
|
||||
│ └── anomaly_check.py
|
||||
├── templates/
|
||||
│ └── slack_blocks.py # Slack Block Kit
|
||||
├── requirements.txt
|
||||
├── Dockerfile
|
||||
└── docker-compose.yml
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### config.yaml
|
||||
|
||||
```yaml
|
||||
slack:
|
||||
bot_token: ${SLACK_BOT_TOKEN}
|
||||
default_channel: "#analytics-reports"
|
||||
|
||||
ga4:
|
||||
property_id: "123456789"
|
||||
credentials_path: "/path/to/credentials.json"
|
||||
|
||||
reports:
|
||||
daily_summary:
|
||||
enabled: true
|
||||
schedule: "0 9 * * *" # 9 AM daily
|
||||
channel: "#analytics-reports"
|
||||
|
||||
weekly_digest:
|
||||
enabled: true
|
||||
schedule: "0 9 * * 1" # 9 AM Monday
|
||||
channel: "#analytics-reports"
|
||||
|
||||
anomaly_alert:
|
||||
enabled: true
|
||||
check_interval: 3600 # Check every hour
|
||||
threshold: 0.3 # 30% deviation
|
||||
channel: "#analytics-alerts"
|
||||
```
|
||||
|
||||
## Slack App Setup
|
||||
|
||||
1. Go to [api.slack.com/apps](https://api.slack.com/apps)
|
||||
2. Create New App → From scratch
|
||||
3. Add OAuth scopes:
|
||||
- `chat:write`
|
||||
- `files:write`
|
||||
- `channels:read`
|
||||
4. Install to workspace
|
||||
5. Copy Bot Token (`xoxb-...`)
|
||||
|
||||
## Dependencies
|
||||
|
||||
```
|
||||
# requirements.txt
|
||||
google-analytics-data>=0.18.0
|
||||
google-auth>=2.23.0
|
||||
slack-sdk>=3.23.0
|
||||
apscheduler>=3.10.0
|
||||
pandas>=2.0.0
|
||||
plotly>=5.18.0
|
||||
kaleido>=0.2.1
|
||||
pyyaml>=6.0
|
||||
```
|
||||
|
||||
## Slack Message Format
|
||||
|
||||
Using Block Kit for rich formatting:
|
||||
|
||||
```python
|
||||
def daily_summary_blocks(data: dict) -> list:
|
||||
return [
|
||||
{
|
||||
"type": "header",
|
||||
"text": {"type": "plain_text", "text": "📊 Daily GA4 Summary"}
|
||||
},
|
||||
{
|
||||
"type": "section",
|
||||
"fields": [
|
||||
{"type": "mrkdwn", "text": f"*Users:* {data['users']:,}"},
|
||||
{"type": "mrkdwn", "text": f"*Sessions:* {data['sessions']:,}"},
|
||||
{"type": "mrkdwn", "text": f"*Pageviews:* {data['pageviews']:,}"},
|
||||
{"type": "mrkdwn", "text": f"*Bounce Rate:* {data['bounce_rate']:.1%}"},
|
||||
]
|
||||
},
|
||||
{"type": "divider"},
|
||||
{
|
||||
"type": "section",
|
||||
"text": {"type": "mrkdwn", "text": "*Top Pages:*\n" + data['top_pages']}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Set environment variables
|
||||
export SLACK_BOT_TOKEN=xoxb-...
|
||||
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/creds.json
|
||||
|
||||
# Run
|
||||
python reporter.py
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Cloud Options
|
||||
|
||||
- Google Cloud Run (scheduled via Cloud Scheduler)
|
||||
- AWS Lambda + EventBridge
|
||||
- Railway / Render
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Slack App created
|
||||
- [ ] config.yaml template
|
||||
- [ ] daily_summary.py
|
||||
- [ ] weekly_digest.py
|
||||
- [ ] anomaly_check.py
|
||||
- [ ] slack_blocks.py templates
|
||||
- [ ] reporter.py scheduler
|
||||
- [ ] Dockerfile
|
||||
- [ ] Tested locally
|
||||
- [ ] Deployed
|
||||
@@ -1,98 +0,0 @@
|
||||
# Component 5: Realtime Watcher
|
||||
|
||||
**Type:** Standalone Service
|
||||
**Priority:** P3
|
||||
**Status:** Deferred
|
||||
|
||||
## Goal
|
||||
|
||||
Real-time GA4 monitoring with periodic snapshots to Slack.
|
||||
|
||||
## Status
|
||||
|
||||
**Deferred** — Complete components 1-4 first.
|
||||
|
||||
## Original Concept
|
||||
|
||||
- Screenshot GA4 real-time dashboard every 5 minutes
|
||||
- Send screenshots to Slack channel
|
||||
- Trigger via Slack command or user request
|
||||
|
||||
## Challenges
|
||||
|
||||
| Challenge | Issue |
|
||||
|-----------|-------|
|
||||
| Browser auth | GA4 requires Google login |
|
||||
| Maintenance | Screenshots break when UI changes |
|
||||
| Complexity | Headless browser + auth + scheduling |
|
||||
| Value | Screenshots may not be best UX |
|
||||
|
||||
## Simplified Approach (Recommended)
|
||||
|
||||
Instead of screenshots, use the GA4 Real-time API:
|
||||
|
||||
1. Fetch real-time data via API
|
||||
2. Generate chart image with Plotly
|
||||
3. Send image to Slack
|
||||
|
||||
### Benefits
|
||||
|
||||
- No browser automation
|
||||
- More reliable
|
||||
- Cleaner output
|
||||
- Programmatic data access
|
||||
|
||||
## Structure (Future)
|
||||
|
||||
```
|
||||
05-realtime-watcher/
|
||||
├── README.md
|
||||
├── realtime_api.py # GA4 Real-time API client
|
||||
├── chart_generator.py # Generate chart images
|
||||
├── slack_sender.py # Upload to Slack
|
||||
├── watcher.py # Main service
|
||||
├── config.yaml
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
## GA4 Real-time API
|
||||
|
||||
```python
|
||||
from google.analytics.data_v1beta import BetaAnalyticsDataClient
|
||||
from google.analytics.data_v1beta.types import RunRealtimeReportRequest
|
||||
|
||||
def get_realtime_users(property_id: str):
|
||||
client = BetaAnalyticsDataClient()
|
||||
|
||||
request = RunRealtimeReportRequest(
|
||||
property=f"properties/{property_id}",
|
||||
dimensions=[{"name": "unifiedScreenName"}],
|
||||
metrics=[{"name": "activeUsers"}]
|
||||
)
|
||||
|
||||
response = client.run_realtime_report(request)
|
||||
return response
|
||||
```
|
||||
|
||||
## Trigger Options
|
||||
|
||||
1. **Slack Command:** `/ga-realtime start`
|
||||
2. **Scheduled:** During campaign launches
|
||||
3. **API Endpoint:** Webhook trigger
|
||||
|
||||
## Implementation (When Ready)
|
||||
|
||||
1. Build real-time API client
|
||||
2. Create chart generator
|
||||
3. Add Slack integration
|
||||
4. Implement start/stop controls
|
||||
5. Add session timeout (1 hour default)
|
||||
|
||||
## Checklist (Future)
|
||||
|
||||
- [ ] Real-time API client
|
||||
- [ ] Chart generation
|
||||
- [ ] Slack integration
|
||||
- [ ] Trigger mechanism
|
||||
- [ ] Session management
|
||||
- [ ] Deployment
|
||||
@@ -1,90 +0,0 @@
|
||||
# GA Agent Project
|
||||
|
||||
Build workspace for Google Analytics tools and the `15-ourdigital-ga-agent` Claude Skill.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Infrastructure │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │ GA4 MCP │ │ BigQuery MCP │ │ Dimension Explorer│ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 15-ourdigital-ga-agent (Claude Skill) │
|
||||
│ • Interactive analysis • Reports • Period comparisons │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Standalone Services │
|
||||
│ ┌────────────────────┐ ┌────────────────────────────┐ │
|
||||
│ │ Slack Reporter │ │ Realtime Watcher (deferred)│ │
|
||||
│ └────────────────────┘ └────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
| # | Component | Type | Priority | Status |
|
||||
|---|-----------|------|----------|--------|
|
||||
| 1 | [MCP Setup](01-mcp-setup/) | Infrastructure | P0 | Pending |
|
||||
| 2 | [GA Agent Skill](02-ga-agent-skill/) | Claude Skill | P0 | Pending |
|
||||
| 3 | [Dimension Explorer](03-dimension-explorer/) | Utility | P1 | Pending |
|
||||
| 4 | [Slack Reporter](04-slack-reporter/) | Service | P2 | Pending |
|
||||
| 5 | [Realtime Watcher](05-realtime-watcher/) | Service | P3 | Deferred |
|
||||
|
||||
## Build Order
|
||||
|
||||
```
|
||||
Phase 1: Foundation
|
||||
├── [1] MCP Setup ←── START HERE
|
||||
└── [2] GA Agent Skill
|
||||
|
||||
Phase 2: Enhancements
|
||||
├── [3] Dimension Explorer
|
||||
└── [4] Slack Reporter
|
||||
|
||||
Phase 3: Advanced
|
||||
└── [5] Realtime Watcher (deferred)
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
ga-agent-project/
|
||||
├── README.md
|
||||
├── .gitignore
|
||||
├── config/ # Credentials (gitignored)
|
||||
├── docs/
|
||||
│ ├── PROJECT-PLAN.md # Full implementation plan
|
||||
│ ├── 01-mcp-servers-overview.md
|
||||
│ ├── 02-setup-guide.md
|
||||
│ └── 03-visualization-setup.md
|
||||
├── 01-mcp-setup/ # MCP server installation
|
||||
├── 02-ga-agent-skill/ # Core Claude Skill
|
||||
├── 03-dimension-explorer/ # Dimension/metric validator
|
||||
├── 04-slack-reporter/ # Automated Slack reports
|
||||
└── 05-realtime-watcher/ # Real-time monitoring (deferred)
|
||||
```
|
||||
|
||||
## Quick Resume
|
||||
|
||||
```bash
|
||||
cd /Users/ourdigital/Projects/claude-skills-factory/ga-agent-project
|
||||
|
||||
# Read the full plan
|
||||
cat docs/PROJECT-PLAN.md
|
||||
|
||||
# Start with Component 1
|
||||
cat 01-mcp-setup/README.md
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Google Cloud account with billing enabled
|
||||
- GA4 property access (Admin or Viewer)
|
||||
- Python 3.10+
|
||||
- Node.js 18+ (for BigQuery MCP)
|
||||
- Slack workspace (for Component 4)
|
||||
@@ -1,94 +0,0 @@
|
||||
# MCP Servers Overview for GA Agent
|
||||
|
||||
## Available MCP Servers
|
||||
|
||||
### Google Analytics MCP Servers
|
||||
|
||||
| Server | Language | Source | Status |
|
||||
|--------|----------|--------|--------|
|
||||
| **google-analytics-mcp** (Official) | Python | [googleanalytics/google-analytics-mcp](https://github.com/googleanalytics/google-analytics-mcp) | Recommended |
|
||||
| mcp-server-google-analytics | TypeScript | [ruchernchong/mcp-server-google-analytics](https://github.com/ruchernchong/mcp-server-google-analytics) | Community |
|
||||
|
||||
**Official Google GA MCP Features:**
|
||||
- Real-time reporting
|
||||
- Custom/standard dimensions/metrics
|
||||
- Natural language queries (e.g., "top products by revenue")
|
||||
- `order_by` support
|
||||
- OAuth + Service Account auth
|
||||
|
||||
### BigQuery MCP Servers
|
||||
|
||||
| Server | Language | npm | Status |
|
||||
|--------|----------|-----|--------|
|
||||
| **@ergut/mcp-bigquery-server** | Node.js | `npx -y @ergut/mcp-bigquery-server` | Recommended |
|
||||
| mcp-server-bigquery | Python | - | Alternative |
|
||||
| Google MCP Toolbox | Python | - | Official (multi-DB) |
|
||||
|
||||
**ergut/mcp-bigquery-server Features:**
|
||||
- Read-only secure access
|
||||
- Schema discovery
|
||||
- Natural language to SQL
|
||||
- 1GB query limit
|
||||
|
||||
## Recommended Stack
|
||||
|
||||
For our GA Agent, we recommend:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Claude Code │
|
||||
│ │ │
|
||||
│ ┌───────────┴───────────┐ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Google Analytics│ │ BigQuery │ │
|
||||
│ │ MCP Server │ │ MCP Server │ │
|
||||
│ └────────┬────────┘ └────────┬────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ GA4 Data API │ │ BigQuery API │ │
|
||||
│ │ GA4 Admin API │ │ (GA4 Export) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Why Both?
|
||||
|
||||
1. **GA4 MCP** - Direct API access for:
|
||||
- Real-time data
|
||||
- Quick metrics queries
|
||||
- Account/property management
|
||||
|
||||
2. **BigQuery MCP** - For advanced analysis:
|
||||
- Historical data (GA4 → BigQuery export)
|
||||
- Complex SQL queries
|
||||
- Cross-dataset joins
|
||||
- Large-scale analysis
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Google Cloud Setup
|
||||
|
||||
1. Create a Google Cloud Project (or use existing)
|
||||
2. Enable these APIs:
|
||||
- Google Analytics Data API
|
||||
- Google Analytics Admin API
|
||||
- BigQuery API
|
||||
|
||||
3. Create Service Account:
|
||||
- Go to IAM & Admin → Service Accounts
|
||||
- Create new service account
|
||||
- Grant roles:
|
||||
- `Analytics Viewer` (or Admin for write ops)
|
||||
- `BigQuery Data Viewer`
|
||||
- `BigQuery Job User`
|
||||
- Download JSON key file
|
||||
|
||||
4. Grant GA4 Access:
|
||||
- In GA4 Admin → Property Access Management
|
||||
- Add service account email with Viewer role
|
||||
|
||||
## Next Steps
|
||||
|
||||
See `02-setup-guide.md` for installation instructions.
|
||||
@@ -1,203 +0,0 @@
|
||||
# MCP Server Setup Guide
|
||||
|
||||
## Step 1: Google Cloud Prerequisites
|
||||
|
||||
### 1.1 Create/Select Project
|
||||
|
||||
```bash
|
||||
# List existing projects
|
||||
gcloud projects list
|
||||
|
||||
# Create new project (optional)
|
||||
gcloud projects create ga-agent-project --name="GA Agent Project"
|
||||
|
||||
# Set active project
|
||||
gcloud config set project YOUR_PROJECT_ID
|
||||
```
|
||||
|
||||
### 1.2 Enable Required APIs
|
||||
|
||||
```bash
|
||||
# Enable all required APIs
|
||||
gcloud services enable \
|
||||
analyticsdata.googleapis.com \
|
||||
analyticsadmin.googleapis.com \
|
||||
bigquery.googleapis.com
|
||||
```
|
||||
|
||||
### 1.3 Create Service Account
|
||||
|
||||
```bash
|
||||
# Create service account
|
||||
gcloud iam service-accounts create ga-agent-sa \
|
||||
--display-name="GA Agent Service Account"
|
||||
|
||||
# Get the email
|
||||
SA_EMAIL="ga-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com"
|
||||
|
||||
# Grant BigQuery roles
|
||||
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
|
||||
--member="serviceAccount:$SA_EMAIL" \
|
||||
--role="roles/bigquery.dataViewer"
|
||||
|
||||
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
|
||||
--member="serviceAccount:$SA_EMAIL" \
|
||||
--role="roles/bigquery.jobUser"
|
||||
|
||||
# Create and download key
|
||||
gcloud iam service-accounts keys create \
|
||||
~/ga-agent-credentials.json \
|
||||
--iam-account=$SA_EMAIL
|
||||
|
||||
# Move to secure location
|
||||
mv ~/ga-agent-credentials.json /path/to/secure/location/
|
||||
```
|
||||
|
||||
### 1.4 Grant GA4 Property Access
|
||||
|
||||
1. Go to [Google Analytics Admin](https://analytics.google.com/analytics/web/)
|
||||
2. Select your property
|
||||
3. Admin → Property Access Management
|
||||
4. Click "+" → Add users
|
||||
5. Enter service account email: `ga-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com`
|
||||
6. Select role: **Viewer** (or Analyst for more access)
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Install Google Analytics MCP Server
|
||||
|
||||
### Option A: Official Google GA MCP (Python)
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/googleanalytics/google-analytics-mcp.git
|
||||
cd google-analytics-mcp
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -e .
|
||||
|
||||
# Set credentials
|
||||
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/ga-agent-credentials.json"
|
||||
|
||||
# Test the server
|
||||
python -m google_analytics_mcp
|
||||
```
|
||||
|
||||
### Option B: TypeScript Community Server
|
||||
|
||||
```bash
|
||||
# Install globally
|
||||
npm install -g @anthropic/mcp-server-google-analytics
|
||||
|
||||
# Or run with npx
|
||||
npx @anthropic/mcp-server-google-analytics
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Install BigQuery MCP Server
|
||||
|
||||
```bash
|
||||
# Using npx (recommended - no install needed)
|
||||
npx -y @ergut/mcp-bigquery-server \
|
||||
--project-id YOUR_PROJECT_ID \
|
||||
--location us-central1 \
|
||||
--key-file /path/to/ga-agent-credentials.json
|
||||
|
||||
# Or install globally
|
||||
npm install -g @ergut/mcp-bigquery-server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Configure Claude Code
|
||||
|
||||
Add to your Claude Code MCP configuration (`~/.claude/mcp_servers.json` or project `.mcp.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"google-analytics": {
|
||||
"command": "python",
|
||||
"args": ["-m", "google_analytics_mcp"],
|
||||
"env": {
|
||||
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/ga-agent-credentials.json"
|
||||
}
|
||||
},
|
||||
"bigquery": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@ergut/mcp-bigquery-server",
|
||||
"--project-id", "YOUR_PROJECT_ID",
|
||||
"--location", "us-central1",
|
||||
"--key-file", "/path/to/ga-agent-credentials.json"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Verify Installation
|
||||
|
||||
After restarting Claude Code:
|
||||
|
||||
```bash
|
||||
# Check servers are connected
|
||||
mcp-cli servers
|
||||
|
||||
# List available tools
|
||||
mcp-cli tools google-analytics
|
||||
mcp-cli tools bigquery
|
||||
```
|
||||
|
||||
Expected output should show tools like:
|
||||
- `google-analytics/run_report`
|
||||
- `google-analytics/run_realtime_report`
|
||||
- `bigquery/execute-query`
|
||||
- `bigquery/list-tables`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Authentication Errors
|
||||
|
||||
```bash
|
||||
# Verify credentials
|
||||
gcloud auth application-default print-access-token
|
||||
|
||||
# Check service account permissions
|
||||
gcloud projects get-iam-policy YOUR_PROJECT_ID \
|
||||
--filter="bindings.members:ga-agent-sa"
|
||||
```
|
||||
|
||||
### GA4 Access Issues
|
||||
|
||||
- Ensure service account email is added to GA4 property
|
||||
- Wait 5-10 minutes after adding access
|
||||
- Check property ID is correct (numeric, not "UA-" format)
|
||||
|
||||
### BigQuery Connection Issues
|
||||
|
||||
```bash
|
||||
# Test BigQuery access directly
|
||||
bq ls YOUR_PROJECT_ID:analytics_*
|
||||
|
||||
# Check dataset exists
|
||||
bq show YOUR_PROJECT_ID:analytics_PROPERTY_ID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Set up GA4 → BigQuery export (if not already)
|
||||
2. Create visualization tools (see `03-visualization-setup.md`)
|
||||
3. Build the Claude Skill
|
||||
@@ -1,286 +0,0 @@
|
||||
# Visualization Tools Setup
|
||||
|
||||
## Overview
|
||||
|
||||
For lightweight dashboards displaying GA4/BigQuery insights, we recommend:
|
||||
|
||||
| Tool | Best For | Complexity |
|
||||
|------|----------|------------|
|
||||
| **Streamlit** | Quick Python dashboards | Low |
|
||||
| **Plotly Dash** | Interactive charts | Medium |
|
||||
| **HTML + Chart.js** | Portable, no server | Low |
|
||||
|
||||
## Option 1: Streamlit Dashboard (Recommended)
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
```bash
|
||||
cd /path/to/ga-agent-project/visualization
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate
|
||||
|
||||
# Install packages
|
||||
pip install streamlit pandas plotly google-cloud-bigquery google-analytics-data
|
||||
```
|
||||
|
||||
### Basic Dashboard Template
|
||||
|
||||
Create `visualization/streamlit_dashboard.py`:
|
||||
|
||||
```python
|
||||
import streamlit as st
|
||||
import pandas as pd
|
||||
import plotly.express as px
|
||||
from google.cloud import bigquery
|
||||
from google.analytics.data_v1beta import BetaAnalyticsDataClient
|
||||
from google.analytics.data_v1beta.types import RunReportRequest
|
||||
|
||||
# Page config
|
||||
st.set_page_config(
|
||||
page_title="GA4 Analytics Dashboard",
|
||||
page_icon="📊",
|
||||
layout="wide"
|
||||
)
|
||||
|
||||
st.title("📊 GA4 Analytics Dashboard")
|
||||
|
||||
# Sidebar for configuration
|
||||
with st.sidebar:
|
||||
st.header("Settings")
|
||||
property_id = st.text_input("GA4 Property ID", "YOUR_PROPERTY_ID")
|
||||
date_range = st.selectbox(
|
||||
"Date Range",
|
||||
["Last 7 days", "Last 30 days", "Last 90 days"]
|
||||
)
|
||||
|
||||
# Date mapping
|
||||
date_map = {
|
||||
"Last 7 days": "7daysAgo",
|
||||
"Last 30 days": "30daysAgo",
|
||||
"Last 90 days": "90daysAgo"
|
||||
}
|
||||
|
||||
@st.cache_data(ttl=3600)
|
||||
def fetch_ga4_data(property_id: str, start_date: str):
|
||||
"""Fetch data from GA4 API"""
|
||||
client = BetaAnalyticsDataClient()
|
||||
|
||||
request = RunReportRequest(
|
||||
property=f"properties/{property_id}",
|
||||
dimensions=[{"name": "date"}],
|
||||
metrics=[
|
||||
{"name": "activeUsers"},
|
||||
{"name": "sessions"},
|
||||
{"name": "screenPageViews"}
|
||||
],
|
||||
date_ranges=[{"start_date": start_date, "end_date": "today"}]
|
||||
)
|
||||
|
||||
response = client.run_report(request)
|
||||
|
||||
data = []
|
||||
for row in response.rows:
|
||||
data.append({
|
||||
"date": row.dimension_values[0].value,
|
||||
"users": int(row.metric_values[0].value),
|
||||
"sessions": int(row.metric_values[1].value),
|
||||
"pageviews": int(row.metric_values[2].value)
|
||||
})
|
||||
|
||||
return pd.DataFrame(data)
|
||||
|
||||
# Fetch and display data
|
||||
try:
|
||||
df = fetch_ga4_data(property_id, date_map[date_range])
|
||||
|
||||
# Metrics row
|
||||
col1, col2, col3 = st.columns(3)
|
||||
with col1:
|
||||
st.metric("Total Users", f"{df['users'].sum():,}")
|
||||
with col2:
|
||||
st.metric("Total Sessions", f"{df['sessions'].sum():,}")
|
||||
with col3:
|
||||
st.metric("Total Pageviews", f"{df['pageviews'].sum():,}")
|
||||
|
||||
# Charts
|
||||
st.subheader("Traffic Over Time")
|
||||
fig = px.line(df, x="date", y=["users", "sessions"],
|
||||
title="Users & Sessions")
|
||||
st.plotly_chart(fig, use_container_width=True)
|
||||
|
||||
# Raw data
|
||||
with st.expander("View Raw Data"):
|
||||
st.dataframe(df)
|
||||
|
||||
except Exception as e:
|
||||
st.error(f"Error fetching data: {e}")
|
||||
st.info("Ensure GOOGLE_APPLICATION_CREDENTIALS is set")
|
||||
```
|
||||
|
||||
### Run Dashboard
|
||||
|
||||
```bash
|
||||
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
|
||||
streamlit run visualization/streamlit_dashboard.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Option 2: Static HTML Dashboard
|
||||
|
||||
For portable reports without a server:
|
||||
|
||||
Create `visualization/templates/report.html`:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>GA4 Report</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
|
||||
<style>
|
||||
body { font-family: -apple-system, sans-serif; margin: 40px; }
|
||||
.metrics { display: flex; gap: 20px; margin-bottom: 40px; }
|
||||
.metric-card {
|
||||
background: #f5f5f5;
|
||||
padding: 20px;
|
||||
border-radius: 8px;
|
||||
flex: 1;
|
||||
}
|
||||
.metric-value { font-size: 32px; font-weight: bold; }
|
||||
.metric-label { color: #666; }
|
||||
.chart-container { max-width: 800px; margin: 40px 0; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>📊 GA4 Analytics Report</h1>
|
||||
<p>Generated: <span id="date"></span></p>
|
||||
|
||||
<div class="metrics">
|
||||
<div class="metric-card">
|
||||
<div class="metric-value" id="users">--</div>
|
||||
<div class="metric-label">Active Users</div>
|
||||
</div>
|
||||
<div class="metric-card">
|
||||
<div class="metric-value" id="sessions">--</div>
|
||||
<div class="metric-label">Sessions</div>
|
||||
</div>
|
||||
<div class="metric-card">
|
||||
<div class="metric-value" id="pageviews">--</div>
|
||||
<div class="metric-label">Page Views</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="chart-container">
|
||||
<canvas id="trafficChart"></canvas>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
// Data will be injected by Python script
|
||||
const reportData = {{ DATA_JSON }};
|
||||
|
||||
document.getElementById('date').textContent = new Date().toLocaleDateString();
|
||||
document.getElementById('users').textContent = reportData.totals.users.toLocaleString();
|
||||
document.getElementById('sessions').textContent = reportData.totals.sessions.toLocaleString();
|
||||
document.getElementById('pageviews').textContent = reportData.totals.pageviews.toLocaleString();
|
||||
|
||||
new Chart(document.getElementById('trafficChart'), {
|
||||
type: 'line',
|
||||
data: {
|
||||
labels: reportData.dates,
|
||||
datasets: [{
|
||||
label: 'Users',
|
||||
data: reportData.users,
|
||||
borderColor: '#4285f4',
|
||||
tension: 0.1
|
||||
}, {
|
||||
label: 'Sessions',
|
||||
data: reportData.sessions,
|
||||
borderColor: '#34a853',
|
||||
tension: 0.1
|
||||
}]
|
||||
},
|
||||
options: {
|
||||
responsive: true,
|
||||
plugins: {
|
||||
title: { display: true, text: 'Traffic Over Time' }
|
||||
}
|
||||
}
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Option 3: Python Chart Generation
|
||||
|
||||
For generating standalone chart images:
|
||||
|
||||
```python
|
||||
# visualization/scripts/generate_charts.py
|
||||
import pandas as pd
|
||||
import plotly.express as px
|
||||
import plotly.io as pio
|
||||
|
||||
def generate_traffic_chart(df: pd.DataFrame, output_path: str):
|
||||
"""Generate traffic chart as HTML or PNG"""
|
||||
fig = px.line(
|
||||
df,
|
||||
x="date",
|
||||
y=["users", "sessions"],
|
||||
title="Traffic Overview",
|
||||
template="plotly_white"
|
||||
)
|
||||
|
||||
fig.update_layout(
|
||||
xaxis_title="Date",
|
||||
yaxis_title="Count",
|
||||
legend_title="Metric"
|
||||
)
|
||||
|
||||
# Save as interactive HTML
|
||||
fig.write_html(f"{output_path}/traffic_chart.html")
|
||||
|
||||
# Save as static image (requires kaleido)
|
||||
# pip install kaleido
|
||||
fig.write_image(f"{output_path}/traffic_chart.png", scale=2)
|
||||
|
||||
return fig
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Claude Skill
|
||||
|
||||
The Claude Skill will use these visualization tools via Python scripts:
|
||||
|
||||
```
|
||||
15-ourdigital-ga-agent/
|
||||
├── SKILL.md
|
||||
├── scripts/
|
||||
│ ├── fetch_ga4_data.py # Get data from GA4/BigQuery
|
||||
│ ├── generate_report.py # Create visualizations
|
||||
│ └── streamlit_app.py # Launch dashboard
|
||||
├── templates/
|
||||
│ └── report.html # Static report template
|
||||
└── assets/
|
||||
└── styles.css # Dashboard styling
|
||||
```
|
||||
|
||||
## Requirements File
|
||||
|
||||
Create `visualization/requirements.txt`:
|
||||
|
||||
```
|
||||
streamlit>=1.28.0
|
||||
pandas>=2.0.0
|
||||
plotly>=5.18.0
|
||||
google-cloud-bigquery>=3.12.0
|
||||
google-analytics-data>=0.18.0
|
||||
kaleido>=0.2.1
|
||||
```
|
||||
@@ -1,319 +0,0 @@
|
||||
# GA Agent Project Plan (Revised)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Infrastructure │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||||
│ │ GA4 MCP │ │ BigQuery MCP │ │ Dimension Explorer│ │
|
||||
│ │ (install) │ │ (install) │ │ (build - small) │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Claude Skill │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ 15-ourdigital-ga-agent │ │
|
||||
│ │ • Interactive analysis │ │
|
||||
│ │ • Report generation │ │
|
||||
│ │ • Period comparisons │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Standalone Services (Later) │
|
||||
│ ┌────────────────────┐ ┌────────────────────────────┐ │
|
||||
│ │ ga4-slack-reporter │ │ ga4-realtime-watcher │ │
|
||||
│ │ (Python service) │ │ (defer or API-based) │ │
|
||||
│ └────────────────────┘ └────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Components
|
||||
|
||||
| # | Component | Type | Priority | Effort |
|
||||
|---|-----------|------|----------|--------|
|
||||
| 1 | MCP Setup | Infrastructure | P0 | Low |
|
||||
| 2 | ga-agent-skill | Claude Skill | P0 | Medium |
|
||||
| 3 | dimension-explorer | MCP Server / CLI | P1 | Low |
|
||||
| 4 | slack-reporter | Standalone Service | P2 | Medium |
|
||||
| 5 | realtime-watcher | Standalone Service | P3 | High (defer) |
|
||||
|
||||
---
|
||||
|
||||
## Component 1: MCP Setup
|
||||
|
||||
**Location:** `01-mcp-setup/`
|
||||
|
||||
**Goal:** Install and configure existing MCP servers
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] Google Cloud project setup
|
||||
- [ ] Enable Analytics Data API
|
||||
- [ ] Enable Analytics Admin API
|
||||
- [ ] Enable BigQuery API
|
||||
- [ ] Service account creation
|
||||
- [ ] Create service account
|
||||
- [ ] Grant Analytics Viewer role
|
||||
- [ ] Grant BigQuery Data Viewer role
|
||||
- [ ] Download JSON key
|
||||
- [ ] GA4 property access
|
||||
- [ ] Add service account to GA4 property
|
||||
- [ ] Install GA4 MCP server
|
||||
- [ ] Clone `googleanalytics/google-analytics-mcp`
|
||||
- [ ] Configure credentials
|
||||
- [ ] Test connection
|
||||
- [ ] Install BigQuery MCP server
|
||||
- [ ] Configure `@ergut/mcp-bigquery-server`
|
||||
- [ ] Verify GA4 export dataset access
|
||||
- [ ] Add to Claude Code config
|
||||
- [ ] Update `~/.claude/mcp_servers.json`
|
||||
- [ ] Verify with `mcp-cli servers`
|
||||
|
||||
### Deliverables
|
||||
|
||||
- `01-mcp-setup/setup-guide.md` - Step-by-step instructions
|
||||
- `01-mcp-setup/mcp-config.example.json` - Example MCP configuration
|
||||
- Working MCP connections verified
|
||||
|
||||
---
|
||||
|
||||
## Component 2: GA Agent Skill (Core)
|
||||
|
||||
**Location:** `02-ga-agent-skill/` → Final: `ourdigital-custom-skills/15-ourdigital-ga-agent/`
|
||||
|
||||
**Goal:** Interactive GA4 analysis and reporting skill
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| Traffic Analysis | Users, sessions, pageviews with trends |
|
||||
| Period Comparison | WoW, MoM, YoY comparisons |
|
||||
| Top Content | Pages, sources, campaigns |
|
||||
| Report Generation | HTML/PDF reports |
|
||||
| BigQuery Queries | Complex analysis on exported data |
|
||||
|
||||
### Triggers (EN/KR)
|
||||
|
||||
- "Analyze GA4 traffic" / "GA4 트래픽 분석"
|
||||
- "Compare last week vs this week" / "지난주 대비 비교"
|
||||
- "Generate traffic report" / "트래픽 리포트 생성"
|
||||
- "Top landing pages" / "인기 랜딩 페이지"
|
||||
- "Query BigQuery for GA data" / "BigQuery GA 데이터 조회"
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
15-ourdigital-ga-agent/
|
||||
├── SKILL.md
|
||||
├── scripts/
|
||||
│ ├── analyze_traffic.py
|
||||
│ ├── compare_periods.py
|
||||
│ ├── top_content.py
|
||||
│ └── generate_report.py
|
||||
├── templates/
|
||||
│ └── report.html
|
||||
├── references/
|
||||
│ └── ga4-api-reference.md
|
||||
└── examples/
|
||||
└── sample-queries.md
|
||||
```
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] Create SKILL.md with triggers
|
||||
- [ ] Build analysis scripts
|
||||
- [ ] analyze_traffic.py
|
||||
- [ ] compare_periods.py
|
||||
- [ ] top_content.py
|
||||
- [ ] Create report template
|
||||
- [ ] Add examples
|
||||
- [ ] Test with Claude Code
|
||||
- [ ] Move to `ourdigital-custom-skills/15-ourdigital-ga-agent/`
|
||||
|
||||
---
|
||||
|
||||
## Component 3: Dimension Explorer
|
||||
|
||||
**Location:** `03-dimension-explorer/`
|
||||
|
||||
**Goal:** Validate GA4 dimensions/metrics with explanations
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Pros | Cons |
|
||||
|--------|------|------|
|
||||
| **A. MCP Server** | Claude can use directly | More setup |
|
||||
| **B. CLI Tool** | Simple, standalone | Manual invocation |
|
||||
| **C. Reference JSON** | No code needed | Static, needs refresh |
|
||||
|
||||
**Recommendation:** Start with C (Reference JSON), upgrade to A (MCP Server) later
|
||||
|
||||
### Features
|
||||
|
||||
- List all available dimensions/metrics
|
||||
- Validate if a dimension/metric exists
|
||||
- Get description, data type, category
|
||||
- Fuzzy search for typos
|
||||
- Compatibility checking
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
03-dimension-explorer/
|
||||
├── README.md
|
||||
├── fetch_metadata.py # Script to refresh metadata
|
||||
├── data/
|
||||
│ ├── dimensions.json # All dimensions with descriptions
|
||||
│ └── metrics.json # All metrics with descriptions
|
||||
└── explorer.py # CLI tool (optional)
|
||||
```
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] Fetch metadata from GA4 Admin API
|
||||
- [ ] Structure as searchable JSON
|
||||
- [ ] Create CLI explorer (optional)
|
||||
- [ ] Document usage
|
||||
|
||||
---
|
||||
|
||||
## Component 4: Slack Reporter
|
||||
|
||||
**Location:** `04-slack-reporter/`
|
||||
|
||||
**Goal:** Automated GA4 reports to Slack
|
||||
|
||||
### Features
|
||||
|
||||
| Report | Schedule | Content |
|
||||
|--------|----------|---------|
|
||||
| Daily Summary | 9:00 AM | Users, sessions, top pages |
|
||||
| Weekly Digest | Monday 9 AM | WoW comparison, trends |
|
||||
| Anomaly Alert | Real-time | Traffic ±30% from baseline |
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
04-slack-reporter/
|
||||
├── README.md
|
||||
├── config.yaml # Schedules, channels, properties
|
||||
├── reporter.py # Main service
|
||||
├── queries/
|
||||
│ ├── daily_summary.py
|
||||
│ ├── weekly_digest.py
|
||||
│ └── anomaly_check.py
|
||||
├── templates/
|
||||
│ └── slack_blocks.py # Slack Block Kit templates
|
||||
├── requirements.txt
|
||||
└── Dockerfile # For deployment
|
||||
```
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] Create Slack App
|
||||
- [ ] Build query functions
|
||||
- [ ] Create Slack message templates
|
||||
- [ ] Implement scheduler
|
||||
- [ ] Add Docker deployment
|
||||
- [ ] Document setup
|
||||
|
||||
---
|
||||
|
||||
## Component 5: Realtime Watcher (Deferred)
|
||||
|
||||
**Location:** `05-realtime-watcher/`
|
||||
|
||||
**Goal:** Real-time monitoring snapshots to Slack
|
||||
|
||||
**Status:** Deferred — revisit after components 1-4 complete
|
||||
|
||||
### Simplified Approach (API-based)
|
||||
|
||||
Instead of screenshots:
|
||||
1. Fetch real-time data via GA4 Real-time API
|
||||
2. Generate chart image with Plotly/Matplotlib
|
||||
3. Send to Slack
|
||||
|
||||
### Structure (Future)
|
||||
|
||||
```
|
||||
05-realtime-watcher/
|
||||
├── README.md
|
||||
├── realtime_api.py # Fetch real-time data
|
||||
├── chart_generator.py # Generate chart images
|
||||
├── watcher.py # Main service
|
||||
└── config.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Order
|
||||
|
||||
```
|
||||
Phase 1: Foundation
|
||||
├── [1] MCP Setup ←── START HERE
|
||||
└── [2] GA Agent Skill (core)
|
||||
|
||||
Phase 2: Enhancements
|
||||
├── [3] Dimension Explorer
|
||||
└── [4] Slack Reporter
|
||||
|
||||
Phase 3: Advanced (Deferred)
|
||||
└── [5] Realtime Watcher
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Setup
|
||||
|
||||
### Required Credentials
|
||||
|
||||
```bash
|
||||
# Google Cloud
|
||||
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
|
||||
GA4_PROPERTY_ID=123456789
|
||||
BIGQUERY_PROJECT_ID=your-project
|
||||
|
||||
# Slack (for Component 4)
|
||||
SLACK_BOT_TOKEN=xoxb-...
|
||||
SLACK_CHANNEL_ID=C0123456789
|
||||
```
|
||||
|
||||
### Python Dependencies
|
||||
|
||||
```
|
||||
# Core (Components 1-3)
|
||||
google-analytics-data>=0.18.0
|
||||
google-cloud-bigquery>=3.12.0
|
||||
google-auth>=2.23.0
|
||||
pandas>=2.0.0
|
||||
|
||||
# Visualization
|
||||
plotly>=5.18.0
|
||||
jinja2>=3.1.0
|
||||
|
||||
# Slack Reporter (Component 4)
|
||||
slack-sdk>=3.23.0
|
||||
apscheduler>=3.10.0
|
||||
pyyaml>=6.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Navigate to project
|
||||
cd /Users/ourdigital/Projects/claude-skills-factory/ga-agent-project
|
||||
|
||||
# Start with MCP setup
|
||||
cat 01-mcp-setup/setup-guide.md
|
||||
```
|
||||
@@ -85,7 +85,7 @@
|
||||
"tokens": 800
|
||||
},
|
||||
{
|
||||
"path": "/Users/ourdigital/Project/claude-skills-factory/CLAUDE.md",
|
||||
"path": "/Users/ourdigital/Project/claude-skills/CLAUDE.md",
|
||||
"lines": 150,
|
||||
"words": 722,
|
||||
"tokens": 938
|
||||
|
||||
@@ -50,7 +50,7 @@
|
||||
## CLAUDE.md Analysis
|
||||
|
||||
- **/Users/ourdigital/.claude/CLAUDE.md**: 110 lines, ~800 tokens 🟢
|
||||
- **/Users/ourdigital/Project/claude-skills-factory/CLAUDE.md**: 150 lines, ~938 tokens 🟢
|
||||
- **/Users/ourdigital/Project/claude-skills/CLAUDE.md**: 150 lines, ~938 tokens 🟢
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user