our-claude-skills/docs/USER-GUIDE.md

# OurDigital Custom Skills — User Guide

> A comprehensive guide to the 52 custom skills in the **our-claude-skills** collection.

---

## Table of Contents

1. [Introduction](#1-introduction)
2. [Quick Start](#2-quick-start)
3. [Skill Categories at a Glance](#3-skill-categories-at-a-glance)
4. [OurDigital Core (00-10)](#4-ourdigital-core-00-10)
5. [SEO Tools (11-34)](#5-seo-tools-11-34)
6. [Jamie Clinic (40-45)](#6-jamie-clinic-40-45)
7. [NotebookLM Tools (50-53)](#7-notebooklm-tools-50-53)
8. [GTM / Analytics (60-62)](#8-gtm--analytics-60-62)
9. [Notion Tools (31-32)](#9-notion-tools-31-32)
10. [Reference Curator (90)](#10-reference-curator-90)
11. [Multi-Agent Guide (91)](#11-multi-agent-guide-91)
12. [Architecture & Conventions](#12-architecture--conventions)
13. [Creating New Skills](#13-creating-new-skills)
14. [Troubleshooting](#14-troubleshooting)

---

## 1. Introduction

### What Are Custom Skills?

Custom skills are reusable, domain-specific instruction sets that extend Claude's capabilities. Each skill teaches Claude how to perform a particular task — writing a blog post in the OurDigital brand voice, running an SEO audit, managing a GTM container, or curating reference documentation.

### Two Platforms, One Collection

Every skill is designed to work on **two independent platforms**:

| Platform | Directive File | How It Runs | Best For |
|----------|---------------|-------------|----------|
| **Claude Code** (CLI) | `code/CLAUDE.md` | Direct Bash/Python execution, slash commands | Developers, automation, scripting |
| **Claude Desktop** (App) | `desktop/SKILL.md` | MCP tools only, conversational | Non-technical users, guided workflows |

You do not need both. Pick the platform you use and follow the corresponding directive.

### How Skills Are Invoked

**Claude Code** — Type a slash command in the CLI:

```
/seo-technical https://ourdigital.org
/reference-curator "MCP documentation" --depth deep
/notebooklm-studio generate audio "AI trends summary"
```

**Claude Desktop** — Use natural language triggers:

```
"Run a technical SEO audit on ourdigital.org"
"Create a podcast from my notebook"
"Write a blog post about AI marketing"
```

---

## 2. Quick Start

### Prerequisites

| Requirement | Used By | Install |
|-------------|---------|---------|
| Python 3.10+ | SEO scripts, NotebookLM | `brew install python` |
| Node.js 18+ | GTM scripts, crawlers | `brew install node` |
| Firecrawl MCP | Reference Curator, crawling | Configured in Claude Code MCP settings |
| Notion MCP | Notion skills | Configured in Claude Code MCP settings |
| Ahrefs MCP | SEO skills (11-34) | Configured in Claude Code MCP settings |
| notebooklm-py | NotebookLM skills (50-53) | `pip install notebooklm-py && playwright install chromium` |

### Installation

```bash
# Clone the repository
git clone https://github.com/ourdigital/our-claude-skills.git
cd our-claude-skills

# (Optional) Install SEO dependencies
pip install -r custom-skills/_ourdigital-shared/requirements/base.txt

# (Optional) Install Reference Curator
cd custom-skills/90-reference-curator && ./install.sh

# (Optional) Set up NotebookLM
pip install notebooklm-py
playwright install chromium
notebooklm login
```

### Verifying Slash Commands

Once the repository is cloned and opened in Claude Code, slash commands are automatically available from `.claude/commands/`. Type `/` in Claude Code to see the full list.

---

## 3. Skill Categories at a Glance

| Range | Domain | Count | Description |
|-------|--------|-------|-------------|
| 00 | Settings & Meta | 1 | Claude Code settings optimization |
| 01-10 | OurDigital Core | 10 | Brand, content, design, business tools |
| 11-34 | SEO | 24 | Technical audit through executive reporting |
| 40-45 | Jamie Clinic | 5 | Medical brand content and social media |
| 50-53 | NotebookLM | 4 | AI notebook management and content generation |
| 60-62 | GTM / Analytics | 3 | Tag management and monitoring |
| 31-32 | Notion | 2 | Workspace organization and writing |
| 90 | Reference Curator | 1 (6 sub-skills) | Documentation curation pipeline |
| 91 | Multi-Agent | 1 | Agent collaboration framework |

**Total: 52 skills** (including Reference Curator sub-skills)

---

## 4. OurDigital Core (00-10)

### Overview

The core skills handle brand identity, content creation across multiple channels, visual design, advertising, training, and business operations.

### 00 — Settings Audit

| | |
|---|---|
| **Purpose** | Optimize Claude Code settings, audit token usage, diagnose MCP errors |
| **Command** | `/settings-audit` |
| **Triggers** | "settings audit", "exceed response limit", "MCP error" |
| **Platforms** | Code + Desktop |

**What it does:**
- Analyzes `~/.claude/settings.json` for optimization opportunities
- Reports token usage patterns
- Diagnoses MCP server connection issues
- Recommends permission and hook configurations

**Example:**
```
/settings-audit
```

### 01 — Brand Guide

| | |
|---|---|
| **Purpose** | OurDigital brand standards, writing style, visual identity reference |
| **Command** | `/ourdigital-brand-guide` |
| **Triggers** | "brand guide", "writing style", "brand standards" |
| **Platforms** | Desktop (slash command adapted from desktop) |

**What it does:**
- Provides the OurDigital "Digital Clinic" brand metaphor guidelines
- Defines tone and voice per channel (ourdigital.org, blog, journal, ourstory.day)
- Specifies color palette, typography (Noto Sans KR, Inter), and visual rules
- Enforces the three brand values: Data-driven, In-action, Marketing Science

**Brand channels:**

| Channel | Domain | Tone |
|---------|--------|------|
| Main Site | ourdigital.org | Professional, data-driven |
| Blog | blog.ourdigital.org | Analytical, educational |
| Journal | journal.ourdigital.org | Conversational, poetic |
| OurStory | ourstory.day | Intimate, authentic |
| Corporate | dintelligence.co.kr | Professional, B2B |

### 02 — Blog Writer

| | |
|---|---|
| **Purpose** | Korean blog creation for blog.ourdigital.org (Ghost) |
| **Triggers** | "write blog post", "블로그 작성" |
| **Platforms** | Desktop |

**What it does:**
- Writes Korean-language blog posts following OurDigital editorial standards
- Structures content with proper headings, subheadings, and CTA
- Applies the "Digital Clinic" analytical tone
- Targets 800-1,200 words per post

### 03 — Journal Writer

| | |
|---|---|
| **Purpose** | English essay/article for journal.ourdigital.org (Ghost) |
| **Triggers** | "write essay", "journal article" |
| **Platforms** | Desktop |

**What it does:**
- Creates English-language essays and long-form articles
- Uses the conversational, poetic tone defined for the Journal channel
- Handles personal narratives and cultural commentary

### 04 — Research

| | |
|---|---|
| **Purpose** | Research-to-Blog workflow |
| **Command** | `/ourdigital-research` |
| **Triggers** | "research this", "blog post research" |
| **Platforms** | Code + Desktop |

**What it does:**
- Conducts web research on a given topic
- Synthesizes findings into a structured outline
- Optionally transitions into blog/journal writing with the appropriate skill

### 05 — Document

| | |
|---|---|
| **Purpose** | Notion-to-Presentation workflow |
| **Command** | `/ourdigital-presentation` |
| **Triggers** | "create document", "Notion export", "presentation" |
| **Platforms** | Code + Desktop |

**What it does:**
- Exports Notion content into presentation-ready format
- Structures slides with OurDigital brand visual identity
- Supports Korean and English bilingual content

### 06 — Designer

| | |
|---|---|
| **Purpose** | Visual storytelling and image prompt generation |
| **Command** | `/ourdigital-designer` |
| **Triggers** | "create image prompt", "visual design" |
| **Platforms** | Code + Desktop |

**What it does:**
- Generates detailed image prompts for AI image generators
- Follows OurDigital visual brand guidelines (color palette, typography)
- Creates visual storytelling concepts for blog posts and social media

### 07 — Ad Manager

| | |
|---|---|
| **Purpose** | Ad copywriting and keyword research |
| **Triggers** | "ad copy", "keyword research", "광고 카피" |
| **Platforms** | Desktop |

**What it does:**
- Writes ad copy for Google Ads, Meta Ads, and Naver Ads
- Conducts keyword research for paid campaigns
- Generates A/B test variants
- Supports Korean and English ad copy

### 08 — Trainer

| | |
|---|---|
| **Purpose** | Training material creation |
| **Triggers** | "create training", "교육 자료" |
| **Platforms** | Desktop |

**What it does:**
- Creates structured training materials and curricula
- Generates quizzes, exercises, and assessment rubrics
- Supports bilingual (Korean/English) training content

### 09 — Back Office

| | |
|---|---|
| **Purpose** | Business document creation |
| **Triggers** | "create proposal", "견적서", "invoice" |
| **Platforms** | Desktop |

**What it does:**
- Generates business documents: proposals, invoices, contracts
- Applies OurDigital corporate branding
- Supports Korean business document conventions

### 10 — Skill Creator

| | |
|---|---|
| **Purpose** | Meta skill for creating new skills |
| **Triggers** | "create skill", "init skill" |
| **Platforms** | Desktop |

**What it does:**
- Scaffolds new skill directory structure
- Generates boilerplate `CLAUDE.md` and `SKILL.md` files
- Follows the dual-platform convention automatically
- Assigns the next available skill number

**Example:**
```bash
python example-skills/skills-main/skill-creator/scripts/init_skill.py my-new-skill --path custom-skills/
```

---

## 5. SEO Tools (11-34)

### Overview

The SEO suite is the largest skill group, covering everything from technical crawlability to executive dashboards. Skills 11-18 focus on site-level audits, 19-28 on strategy and intelligence, and 29-34 on specialized operations and reporting.

All SEO skills integrate with:
- **Ahrefs MCP** — Domain metrics, backlinks, keyword data
- **Notion** — SEO Audit Log database for persistent records
- **Python scripts** — Shared `base_client.py` patterns (RateLimiter, ConfigManager, BaseAsyncClient)

### Audit & Technical (11-18)

#### 11 — Comprehensive Audit

| | |
|---|---|
| **Purpose** | Unified 6-stage SEO audit orchestrator |
| **Triggers** | "comprehensive SEO", "full SEO audit" |
| **Platforms** | Code + Desktop |

**What it does:**
Orchestrates skills 12-18 into a single comprehensive audit. Runs technical, on-page, Core Web Vitals, Search Console, schema, and local audits in sequence, producing a unified report.

#### 12 — Technical Audit

| | |
|---|---|
| **Purpose** | Robots.txt, sitemap, crawlability analysis |
| **Command** | `/seo-technical` |
| **Triggers** | "technical SEO", "crawlability" |
| **Platforms** | Code + Desktop |

**What it does:**
- Validates robots.txt directives
- Checks XML sitemap completeness and structure
- Analyzes crawl errors and redirect chains
- Tests HTTPS configuration and canonical tags

**Example:**
```
/seo-technical https://ourdigital.org
```

#### 13 — On-Page Audit

| | |
|---|---|
| **Purpose** | Meta tags, headings, internal links |
| **Command** | `/seo-on-page` |
| **Triggers** | "on-page SEO", "meta tags" |
| **Platforms** | Code + Desktop |

**What it does:**
- Analyzes title tags, meta descriptions, heading hierarchy
- Checks internal linking structure and anchor text
- Validates Open Graph and Twitter Card tags
- Reviews content quality signals

#### 14 — Core Web Vitals

| | |
|---|---|
| **Purpose** | LCP, CLS, FID, INP performance metrics |
| **Command** | `/seo-vitals` |
| **Triggers** | "Core Web Vitals", "page speed" |
| **Platforms** | Code + Desktop |

**What it does:**
- Measures Largest Contentful Paint (LCP)
- Measures Cumulative Layout Shift (CLS)
- Measures First Input Delay (FID) / Interaction to Next Paint (INP)
- Provides actionable optimization recommendations

#### 15 — Search Console

| | |
|---|---|
| **Purpose** | Google Search Console data analysis |
| **Command** | `/seo-gsc` |
| **Triggers** | "Search Console", "GSC", "rankings" |
| **Platforms** | Code + Desktop |

**What it does:**
- Analyzes search performance data (clicks, impressions, CTR, position)
- Identifies keyword opportunities and declining pages
- Reports on index coverage issues
- Tracks ranking changes over time

#### 16 — Schema Validator

| | |
|---|---|
| **Purpose** | Structured data validation |
| **Command** | `/seo-schema-validator` |
| **Triggers** | "validate schema", "JSON-LD check" |
| **Platforms** | Code + Desktop |

**What it does:**
- Validates existing JSON-LD, Microdata, and RDFa markup
- Checks against Google's rich result requirements
- Reports missing required and recommended properties
- Tests against Schema.org vocabulary

#### 17 — Schema Generator

| | |
|---|---|
| **Purpose** | Structured data creation |
| **Command** | `/seo-schema-generator` |
| **Triggers** | "generate schema", "create JSON-LD" |
| **Platforms** | Code + Desktop |

**What it does:**
- Generates JSON-LD markup for various schema types
- Supports: Article, LocalBusiness, Product, FAQ, HowTo, Organization, BreadcrumbList
- Validates output before delivery
- Provides implementation instructions

#### 18 — Local Audit

| | |
|---|---|
| **Purpose** | Local SEO: NAP consistency, GBP, citations |
| **Command** | `/seo-local` |
| **Triggers** | "local SEO", "Google Business Profile" |
| **Platforms** | Code + Desktop |

**What it does:**
- Checks Name-Address-Phone (NAP) consistency across the web
- Audits Google Business Profile completeness
- Analyzes local citation sources
- Reviews local keyword targeting

### Strategy & Intelligence (19-28)

#### 19 — Keyword Strategy

| | |
|---|---|
| **Purpose** | Keyword expansion, intent classification, clustering, gap analysis |
| **Command** | `/seo-keyword-strategy` |
| **Triggers** | "keyword research", "keyword strategy" |
| **Platforms** | Code + Desktop |

**What it does:**
- Expands seed keywords using Ahrefs data
- Classifies search intent (informational, navigational, commercial, transactional)
- Clusters keywords by topic and SERP similarity
- Identifies content gaps vs. competitors

**Example:**
```
/seo-keyword-strategy "digital marketing Seoul" --competitors competitor1.com,competitor2.com
```

#### 20 — SERP Analysis

| | |
|---|---|
| **Purpose** | Google/Naver SERP features and competitor positions |
| **Command** | `/seo-serp-analysis` |
| **Triggers** | "SERP analysis", "SERP features" |
| **Platforms** | Code + Desktop |

**What it does:**
- Detects SERP features (featured snippets, PAA, knowledge panels, local packs)
- Analyzes competitor positioning for target keywords
- Supports both Google and Naver (Korean search engine)
- Identifies SERP feature opportunities

#### 21 — Position Tracking

| | |
|---|---|
| **Purpose** | Rank monitoring, visibility scores, alerts |
| **Command** | `/seo-position-tracking` |
| **Triggers** | "rank tracking", "position monitoring" |
| **Platforms** | Code + Desktop |

**What it does:**
- Monitors keyword rankings over time
- Calculates visibility scores and share of voice
- Generates alerts for significant ranking changes
- Tracks competitor movements

#### 22 — Link Building

| | |
|---|---|
| **Purpose** | Backlink audit, toxic link detection, link gap analysis |
| **Command** | `/seo-link-building` |
| **Triggers** | "backlink audit", "link building" |
| **Platforms** | Code + Desktop |

**What it does:**
- Audits existing backlink profile using Ahrefs data
- Identifies toxic or spammy links for disavow
- Finds link gap opportunities vs. competitors
- Suggests outreach targets and link-worthy content

#### 23 — Content Strategy

| | |
|---|---|
| **Purpose** | Content audit, decay detection, content briefs, topic clusters |
| **Command** | `/seo-content-strategy` |
| **Triggers** | "content strategy", "content audit" |
| **Platforms** | Code + Desktop |

**What it does:**
- Audits existing content inventory and performance
- Detects content decay (declining traffic/rankings)
- Generates content briefs with keyword targets
- Maps topic clusters and internal linking strategy

#### 24 — E-commerce SEO

| | |
|---|---|
| **Purpose** | Product page audit, product schema validation |
| **Command** | `/seo-ecommerce` |
| **Triggers** | "e-commerce SEO", "product SEO" |
| **Platforms** | Code + Desktop |

**What it does:**
- Audits product page SEO elements (titles, descriptions, images)
- Validates Product schema markup
- Checks category page optimization
- Reviews faceted navigation and crawl efficiency

#### 25 — KPI Framework

| | |
|---|---|
| **Purpose** | Unified SEO KPIs, health scores, ROI calculation |
| **Command** | `/seo-kpi-framework` |
| **Triggers** | "SEO KPI", "SEO performance" |
| **Platforms** | Code + Desktop |

**What it does:**
- Defines and tracks unified SEO KPIs across all audit dimensions
- Calculates composite health scores
- Estimates SEO ROI based on traffic and conversion data
- Generates KPI dashboards for stakeholder reporting

#### 26 — International SEO

| | |
|---|---|
| **Purpose** | Hreflang validation, content parity, multi-language analysis |
| **Command** | `/seo-international` |
| **Triggers** | "international SEO", "hreflang" |
| **Platforms** | Code + Desktop |

**What it does:**
- Validates hreflang tag implementation
- Checks content parity across language versions
- Analyzes international URL structure (subdomain vs. subdirectory vs. ccTLD)
- Reviews geo-targeting settings

#### 27 — AI Visibility

| | |
|---|---|
| **Purpose** | AI search citations, brand radar, share of voice in AI |
| **Command** | `/seo-ai-visibility` |
| **Triggers** | "AI visibility", "AI search" |
| **Platforms** | Code + Desktop |

**What it does:**
- Monitors brand mentions in AI-generated search results
- Tracks share of voice in AI search (ChatGPT, Perplexity, Google AI Overview)
- Analyzes citation patterns and cited domains
- Measures AI impression history and trends

#### 28 — Knowledge Graph

| | |
|---|---|
| **Purpose** | Entity SEO, Knowledge Panel optimization, PAA analysis |
| **Command** | `/seo-knowledge-graph` |
| **Triggers** | "knowledge graph", "entity SEO" |
| **Platforms** | Code + Desktop |

**What it does:**
- Audits entity presence in Google's Knowledge Graph
- Optimizes for Knowledge Panel appearance
- Analyzes "People Also Ask" opportunities
- Reviews entity disambiguation and structured data connections

### Specialized Operations (29-34)

#### 29 — Gateway Architect

| | |
|---|---|
| **Purpose** | Gateway page strategy and architecture design |
| **Command** | `/seo-gateway-architect` |
| **Triggers** | "SEO strategy", "gateway pages" |
| **Platforms** | Code + Desktop |

**What it does:**
- Designs gateway page architecture for target keyword clusters
- Maps URL structures and internal linking
- Plans content hierarchy and pillar-cluster relationships

#### 30 — Gateway Builder

| | |
|---|---|
| **Purpose** | Gateway page content generation |
| **Command** | `/seo-gateway-builder` |
| **Triggers** | "build gateway page" |
| **Platforms** | Code + Desktop |

**What it does:**
- Generates optimized gateway page content based on architect blueprints
- Includes meta tags, headings, body copy, and internal links
- Follows SEO best practices for content structure

#### 31 — Competitor Intel

| | |
|---|---|
| **Purpose** | Competitor profiling, benchmarking, threat analysis |
| **Command** | `/seo-competitor-intel` |
| **Triggers** | "competitor analysis", "competitive intel" |
| **Platforms** | Code + Desktop |

**What it does:**
- Profiles competitor SEO strategies using Ahrefs data
- Benchmarks domain authority, traffic, and keyword overlap
- Identifies competitive threats and opportunities
- Generates comparative reports

#### 32 — Crawl Budget

| | |
|---|---|
| **Purpose** | Server log analysis, bot profiling, crawl waste identification |
| **Command** | `/seo-crawl-budget` |
| **Triggers** | "crawl budget", "log analysis" |
| **Platforms** | Code + Desktop |

**What it does:**
- Analyzes server access logs for bot crawl patterns
- Profiles Googlebot, Bingbot, and other crawler behavior
- Identifies crawl waste (duplicate content, soft 404s, parameter URLs)
- Recommends crawl budget optimization strategies

#### 33 — Migration Planner

| | |
|---|---|
| **Purpose** | Site migration planning, redirect mapping, risk assessment |
| **Command** | `/seo-migration-planner` |
| **Triggers** | "site migration", "domain move", "사이트 이전" |
| **Platforms** | Code + Desktop |

**What it does:**
- Creates pre-migration baseline snapshots
- Generates redirect mapping (old URL → new URL)
- Assesses migration risk factors
- Plans post-migration monitoring checkpoints
- Supports domain moves, CMS migrations, HTTPS transitions, and URL restructuring

#### 34 — Reporting Dashboard

| | |
|---|---|
| **Purpose** | Executive reports, HTML dashboards, data aggregation |
| **Command** | `/seo-reporting-dashboard` |
| **Triggers** | "SEO report", "SEO dashboard", "보고서" |
| **Platforms** | Code + Desktop |

**What it does:**
- Aggregates data from all other SEO skills into unified reports
- Generates executive summaries with key metrics and trends
- Creates interactive HTML dashboards
- Supports Korean-language report summaries
- Exports to multiple formats (Markdown, HTML, PDF-ready)

---

## 6. Jamie Clinic (40-45)

### Overview

Skills for Jamie Plastic Surgery Clinic's digital presence. All content must follow strict medical brand compliance guidelines and supports Korean-language content.

#### 40 — Brand Editor

| | |
|---|---|
| **Purpose** | Jamie Clinic branded content generation |
| **Command** | `/jamie-editor` |
| **Triggers** | "write Jamie blog", "Jamie content" |
| **Platforms** | Code + Desktop |

**What it does:**
- Generates blog posts and marketing content in Jamie's brand voice
- Follows medical content compliance guidelines
- Maintains consistent tone: professional yet approachable
- Supports Korean and English content

#### 41 — Brand Audit

| | |
|---|---|
| **Purpose** | Content review and brand compliance checking |
| **Command** | `/jamie-audit` |
| **Triggers** | "review content", "brand audit" |
| **Platforms** | Code + Desktop |

**What it does:**
- Reviews existing content for brand consistency
- Checks medical claims against compliance standards
- Validates tone, terminology, and visual brand adherence
- Generates compliance reports with specific revision suggestions

#### 43 — YouTube Manager

| | |
|---|---|
| **Purpose** | YouTube channel SEO audit and content optimization |
| **Command** | N/A (use trigger) |
| **Triggers** | "YouTube SEO", "YT optimization" |
| **Platforms** | Code + Desktop |

**What it does:**
- Audits YouTube channel and video SEO
- Optimizes titles, descriptions, tags, and thumbnails
- Analyzes competitor YouTube channels
- Suggests content strategy for video SEO

#### 44 — Subtitle Checker

| | |
|---|---|
| **Purpose** | YouTube subtitle file (SBV) validation and typo correction |
| **Command** | N/A (use trigger) |
| **Triggers** | "check subtitles", "subtitle QA" |
| **Platforms** | Code + Desktop |

**What it does:**
- Validates SBV subtitle file format and timing
- Detects and corrects Korean/English typos
- Checks subtitle synchronization
- Ensures accessibility compliance

#### 45 — Instagram Manager

| | |
|---|---|
| **Purpose** | Instagram account management and strategy |
| **Command** | N/A (use trigger) |
| **Triggers** | "Instagram management", "IG strategy" |
| **Platforms** | Code + Desktop |

**What it does:**
- Plans Instagram content calendar
- Generates caption copy and hashtag strategies
- Analyzes engagement metrics
- Maintains brand visual consistency on the platform

---

## 7. NotebookLM Tools (50-53)

### Overview

Four specialized skills for Google's NotebookLM platform, powered by the `notebooklm-py` CLI.

**Prerequisites (all skills):**
```bash
pip install notebooklm-py
playwright install chromium
notebooklm login    # Browser-based Google OAuth
```

#### 50 — Agent

| | |
|---|---|
| **Purpose** | Q&A from notebooks with Gemini-powered citations |
| **Command** | `/notebooklm-agent` |
| **Triggers** | "ask NotebookLM", "query notebook", "노트북 질문" |
| **Platforms** | Code + Desktop |

**What it does:**
- Queries NotebookLM notebooks with natural language questions
- Returns answers with source citations
- Supports JSON output for programmatic use
- Can target specific notebooks by name or ID

**Example:**
```bash
notebooklm ask "What are the key findings about AI adoption?" --json
```

#### 51 — Automation

| | |
|---|---|
| **Purpose** | Programmatic notebook, source, and artifact management |
| **Command** | `/notebooklm-automation` |
| **Triggers** | "create notebook", "add sources", "노트북 관리" |
| **Platforms** | Code + Desktop |

**What it does:**
- Creates and manages notebooks programmatically
- Adds sources (URLs, documents, text) to notebooks
- Lists and manages existing notebooks and sources
- Handles batch operations

**Example:**
```bash
notebooklm create "Research Project Alpha"
notebooklm source add "https://example.com/paper.pdf"
notebooklm list --json
```

#### 52 — Studio

| | |
|---|---|
| **Purpose** | Content generation: audio, video, quizzes, flashcards, slides, mind maps |
| **Command** | `/notebooklm-studio` |
| **Triggers** | "create podcast", "generate video", "make quiz", "팟캐스트 만들기" |
| **Platforms** | Code + Desktop |

**What it does:**
- Generates audio podcasts (deep-dive, brief, critique, debate formats)
- Creates videos (classic, whiteboard, kawaii, anime, pixel, and more styles)
- Builds quizzes and flashcards from notebook content
- Generates slide decks, infographics, and mind maps

**Generation times:**

| Content Type | Approximate Time |
|-------------|-----------------|
| Mind map | Instant |
| Quiz/Flashcards | 5-15 min |
| Audio podcast | 10-20 min |
| Video | 15-45 min |

**Example:**
```bash
notebooklm generate audio "Create a debate about AI ethics" --format debate
notebooklm generate video --style whiteboard
notebooklm download audio ./podcast.mp3
```

#### 53 — Research

| | |
|---|---|
| **Purpose** | Web and Google Drive research, source discovery |
| **Command** | `/notebooklm-research` |
| **Triggers** | "research topic", "find sources", "리서치" |
| **Platforms** | Code + Desktop |

**What it does:**
- Conducts web research and auto-imports results into notebooks
- Searches Google Drive for relevant documents
- Supports fast mode (5-10 sources, seconds) and deep mode (20+ sources, 2-5 min)
- Non-blocking operation with status polling

**Example:**
```bash
# Fast web research
notebooklm source add-research "machine learning trends"

# Deep research with auto-import
notebooklm source add-research "AI regulation" --mode deep --import-all

# Drive research
notebooklm source add-research "quarterly report" --from drive
```

---

## 8. GTM / Analytics (60-62)

### Overview

Google Tag Manager skills for auditing, managing, and monitoring tag implementations.

#### 60 — GTM Audit

| | |
|---|---|
| **Purpose** | GTM container audit and analysis |
| **Command** | `/gtm-audit` |
| **Triggers** | "audit GTM", "GTM analysis" |
| **Platforms** | Code + Desktop |

**What it does:**
- Audits GTM container configuration
- Identifies unused or broken tags
- Checks trigger configurations and firing rules
- Reviews variable definitions and data layer usage
- Generates audit report with recommendations

#### 61 — GTM Manager

| | |
|---|---|
| **Purpose** | GTM management and dataLayer operations |
| **Command** | `/gtm-manager` |
| **Triggers** | "GTM manager", "dataLayer" |
| **Platforms** | Code |

**What it does:**
- Manages GTM tags, triggers, and variables
- Configures dataLayer push events
- Creates and modifies GTM workspace configurations
- Supports batch tag operations

#### 62 — GTM Guardian

| | |
|---|---|
| **Purpose** | Live tag monitoring and validation |
| **Command** | N/A (use trigger) |
| **Triggers** | "monitor GTM", "tag validation" |
| **Platforms** | Code + Desktop |

**What it does:**
- Monitors live tag firing in real-time
- Validates tag configurations against best practices
- Alerts on tag errors, slow-firing tags, or missing data
- Acts as a knowledge assistant for GTM questions

---

## 9. Notion Tools (31-32)

### Overview

Skills for managing and writing content within Notion workspaces. Requires the Notion MCP integration.

#### 31 — Notion Organizer

| | |
|---|---|
| **Purpose** | Notion workspace management and organization |
| **Command** | `/notion-organizer` |
| **Triggers** | "organize Notion", "workspace cleanup" |
| **Platforms** | Code + Desktop |

**What it does:**
- Organizes Notion pages and databases
- Cleans up workspace structure
- Manages page properties and relations
- Supports batch operations on Notion content

#### 32 — Notion Writer

| | |
|---|---|
| **Purpose** | Push markdown content to Notion pages or databases |
| **Command** | `/notion-writer` |
| **Triggers** | "write to Notion", "export to Notion" |
| **Platforms** | Code + Desktop |

**What it does:**
- Converts markdown content to Notion blocks
- Creates new pages in specified databases
- Updates existing page content
- Preserves formatting, headings, code blocks, and lists

---

## 10. Reference Curator (90)

### Overview

A modular pipeline for curating, processing, and exporting reference documentation from the web. Consists of 6 sub-skills orchestrated by a single pipeline command.

### Pipeline Command

| | |
|---|---|
| **Command** | `/reference-curator` |
| **Purpose** | Full pipeline: discover → crawl → store → distill → review → export |

### Input Modes

| Mode | Example | Pipeline Start |
|------|---------|---------------|
| **Topic** | `"Claude system prompts"` | Discovery (Stage 1) |
| **URLs** | `https://docs.anthropic.com/...` | Crawler (Stage 2, skip discovery) |
| **Manifest** | `./manifest.json` | Crawler (resume) |

### Key Arguments

| Argument | Default | Description |
|----------|---------|-------------|
| `--depth` | `standard` | Crawl depth: `light`, `standard`, `deep`, `full` |
| `--output` | `~/Documents/reference-library/` | Output directory (asks permission to create) |
| `--max-sources` | `100` | Max sources to discover |
| `--max-pages` | varies by depth | Max pages per source |
| `--auto-approve` | off | Auto-approve documents scoring above threshold |
| `--threshold` | `0.85` | QA approval threshold |
| `--export-format` | `project_files` | Output format: `project_files`, `fine_tuning`, `jsonl` |

### Depth Levels

```
light       ████░░░░░░░░░░░░  ~20 pages   Main content only      Fastest
standard    ████████░░░░░░░░  ~50 pages   Main + links           Fast
deep        ████████████░░░░  ~150 pages  Full page + HTML       Moderate
full        ████████████████  ~500 pages  Everything + raw HTML  Slow
```

### Pipeline Stages

```
1. reference-discovery     Search & validate authoritative sources
2. web-crawler             Crawl pages using Firecrawl (depth-controlled)
3. content-repository      Store documents with version tracking
4. content-distiller       Summarize and extract key concepts
        ↕ QA Loop
5. quality-reviewer        Score, approve, refactor, or reject
6. markdown-exporter       Export to final format
```

### Output Structure

```
~/Documents/reference-library/
├── {topic-slug}/
│   ├── README.md                   # Index with table of contents
│   ├── 00-page-name.md             # Individual page files
│   ├── 01-page-name.md
│   ├── {topic-slug}-complete.md    # Combined bundle
│   └── manifest.json               # Crawl metadata
├── pipeline_state/                 # Resume state
└── exports/                        # Fine-tuning / JSONL exports
```

### Examples

```bash
# Quick scan of a single doc page
/reference-curator https://docs.example.com/api --depth light

# Standard documentation crawl
/reference-curator "Glossary for WordPress" --max-sources 5

# Deep crawl with full page content
/reference-curator https://docs.codeat.co/glossary/ --depth deep

# Full archival crawl
/reference-curator https://docs.anthropic.com --depth full --max-pages 300

# Auto-approve with fine-tuning export
/reference-curator "MCP servers" --depth deep --auto-approve --export-format fine_tuning
```

### Sub-skills (Individual Use)

| Sub-skill | Command | Purpose |
|-----------|---------|---------|
| reference-discovery | `/reference-discovery` | Search & validate sources |
| web-crawler | `/web-crawler` | Multi-backend crawling |
| content-repository | `/content-repository` | MySQL storage with versioning |
| content-distiller | `/content-distiller` | Summarization & extraction |
| quality-reviewer | `/quality-reviewer` | QA loop routing |
| markdown-exporter | `/markdown-exporter` | Export to markdown/JSONL |

---

## 11. Multi-Agent Guide (91)

### Overview

Sets up a multi-agent collaboration framework for projects where Claude Code, Gemini, Codex, and human reviewers work together.

| | |
|---|---|
| **Command** | `/multi-agent-guide` |
| **Triggers** | "set up multi-agent", "agent guardrails" |

### Agent Hierarchy

```
            ┌─────────────────┐
            │   Claude Code   │
            │  (Lead Agent)   │
            └────────┬────────┘
                     │
      ┌──────────────┼──────────────┐
      v              v              v
┌──────────┐  ┌──────────┐  ┌──────────┐
│  Gemini  │  │  Codex   │  │  Human   │
│(Research)│  │ (Speed)  │  │ (Review) │
└──────────┘  └──────────┘  └──────────┘
```

### What It Creates

```
your-project/
├── .agent-state/
│   ├── tasks.yaml          # Task registry
│   └── locks.yaml          # Lock registry
├── tools/
│   └── check-ownership.py  # Ownership verification
├── MULTI_AGENT_FRAMEWORK.md  # Consolidated rules
├── GEMINI.md               # Gemini agent directive
└── CODEX.md                # Codex agent directive
```

### Commit Convention

```
[Agent] type(scope): description

[Claude] feat(core): implement authentication
[Gemini] docs(api): update API documentation
[Codex] test(models): add unit tests
```

---

## 12. Architecture & Conventions

### Dual-Platform Structure

Every skill follows a consistent directory structure:

```
XX-skill-name/
├── code/                    # Claude Code version
│   ├── CLAUDE.md            # Action-oriented directive
│   ├── scripts/             # Executable Python/Bash
│   └── docs/                # Documentation
│
├── desktop/                 # Claude Desktop version
│   ├── SKILL.md             # Skill directive with YAML frontmatter
│   ├── skill.yaml           # Extended metadata (optional)
│   └── tools/               # MCP tool documentation
│
├── shared/                  # Shared resources (optional)
│   ├── references/          # Brand guidelines, data files
│   ├── templates/           # Output templates
│   └── scripts/             # Shared scripts
│
└── README.md                # Skill overview
```

### Platform Differences

| Aspect | `code/` (Claude Code) | `desktop/` (Claude Desktop) |
|--------|----------------------|----------------------------|
| Directive | CLAUDE.md | SKILL.md (YAML frontmatter) |
| Execution | Direct Bash/Python | MCP tools only |
| Scripts | Required for automation | Reference only |
| Slash commands | `.claude/commands/*.md` | N/A |

### Shared Configuration

All skills share common configuration at:
```
custom-skills/_ourdigital-shared/
├── config/
│   └── ourdigital.yaml      # Brand, channels, colors, Notion, exports
├── requirements/
│   └── base.txt             # Python dependencies
└── installer/               # Shared setup scripts
```

### Skill Numbering Convention

| Range | Domain | Status |
|-------|--------|--------|
| 00 | Settings & Meta | Active |
| 01-09 | OurDigital Core | Active |
| 10 | Skill Creator | Active |
| 11-34 | SEO Tools | Active |
| 35-39 | SEO (Reserved) | Available |
| 40-49 | Jamie Clinic | Active (40-45) |
| 50-59 | NotebookLM | Active (50-53) |
| 60-69 | GTM/Analytics | Active (60-62) |
| 70-89 | Unassigned | Available |
| 90-99 | Infrastructure | Active (90-91) |

### Design Principles

1. **One thing done well** — Each skill focuses on a single capability
2. **Directives under 1,500 words** — Concise and actionable
3. **Self-contained** — Each platform version is fully independent
4. **Code-first** — Build the Claude Code version first, then Desktop
5. **Progressive numbering** — Logical grouping by domain

---

## 13. Creating New Skills

### Using the Skill Creator

```bash
python example-skills/skills-main/skill-creator/scripts/init_skill.py my-new-skill --path custom-skills/
```

### Manual Creation

1. **Choose a number** from the available ranges (see numbering convention above)
2. **Create the directory structure:**
   ```bash
   mkdir -p custom-skills/XX-my-skill/{code,desktop,shared}
   ```
3. **Write `code/CLAUDE.md`** — Action-oriented directive for Claude Code
4. **Write `desktop/SKILL.md`** — Conversational directive with YAML frontmatter
5. **Add scripts** if needed in `code/scripts/`
6. **Create a slash command** in `.claude/commands/my-skill.md`
7. **Update `CLAUDE.md`** at the repo root to include your skill in the summary table

### SKILL.md Frontmatter Format

```markdown
---
name: my-skill-name
description: |
  Brief description of what the skill does.
  Triggers: keyword1, keyword2, 한국어 트리거.
---

# Skill Title

Directive content starts here...
```

### Slash Command Format

```markdown
---
description: Short description shown in command list
argument-hint: <required-arg> [--optional flag]
allowed-tools: Read, Write, Bash, WebSearch, WebFetch
---

# Skill Title

Instructions for Claude Code when this command is invoked...
```

---

## 14. Troubleshooting

### Common Issues

**Slash commands not showing up:**
- Ensure the repo is opened as the working directory in Claude Code
- Check that `.claude/commands/*.md` files have valid YAML frontmatter
- Restart Claude Code if commands were recently added

**MCP tool errors:**
- Run `/settings-audit` to diagnose MCP connection issues
- Verify MCP servers are configured in Claude Code settings
- Check that API keys are set in environment variables

**NotebookLM authentication:**
```bash
notebooklm login    # Re-authenticate if session expired
```

**SEO skill Python errors:**
```bash
pip install -r custom-skills/_ourdigital-shared/requirements/base.txt
```

**Reference Curator output directory:**
- Default output: `~/Documents/reference-library/`
- The pipeline will ask permission before creating new directories
- Never stores output in skill-related directories

### Getting Help

- Repository: https://github.com/ourdigital/our-claude-skills
- Issues: https://github.com/ourdigital/our-claude-skills/issues
- Run `/settings-audit` for self-diagnostics

---

*Last updated: 2026-02-24*