# 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 (11-32)

- Use **Explore** to understand existing SEO script patterns
- Python scripts in these skills follow `base_client.py` patterns (RateLimiter, ConfigManager, BaseAsyncClient)
- `11-seo-comprehensive-audit` orchestrates skills 12-18 for unified audits
- Skills 19-28 provide advanced SEO capabilities (keyword strategy, SERP analysis, position tracking, link building, content strategy, e-commerce, KPI framework, international SEO, AI visibility, knowledge graph)
- Skills 31-32 cover competitor intelligence and crawl budget optimization
- All SEO skills integrate with Ahrefs MCP tools and output to the Notion SEO Audit Log database
- Slash commands available: `/seo-keyword-strategy`, `/seo-serp-analysis`, `/seo-position-tracking`, `/seo-link-building`, `/seo-content-strategy`, `/seo-ecommerce`, `/seo-kpi-framework`, `/seo-international`, `/seo-ai-visibility`, `/seo-knowledge-graph`, `/seo-competitor-intel`, `/seo-crawl-budget`

### GTM Skills (60-69)

- 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

### NotebookLM Skills (50-59)

- Use `notebooklm` CLI for all operations (installed via `pip install notebooklm-py`)
- Requires authentication: `notebooklm login` (browser-based Google OAuth)
- Four specialized skills for different workflows:

| Skill | Purpose | Key Commands |
|-------|---------|--------------|
| 50-notebooklm-agent | Q&A with citations | `notebooklm ask "question" --json` |
| 51-notebooklm-automation | Notebook management | `notebooklm create`, `source add`, `list` |
| 52-notebooklm-studio | Content generation | `notebooklm generate audio/video/quiz` |
| 53-notebooklm-research | Research workflows | `notebooklm source add-research "topic"` |

**Long-running operations:** Use subagent pattern for generation/research:
```
# Start generation (non-blocking)
notebooklm generate audio "instructions" --json

# Spawn subagent to wait and download
Task(
  prompt="Wait for artifact {id} then download: notebooklm artifact wait {id} && notebooklm download audio ./output.mp3",
  subagent_type="general-purpose"
)
```

**Parallel workflows:** Set `NOTEBOOKLM_HOME` per agent to avoid context conflicts.

### Reference Curator Skills (90-99)

- Use **reference-curator-pipeline** for full automated curation workflows
- Runs as background task, coordinates all 6 skills in sequence
- Handles QA loops automatically (max 3 refactor, 2 deep_research iterations)
- Supports three input modes: topic (full pipeline), URLs (skip discovery), manifest (resume)

```
# Full pipeline from topic
/reference-curator-pipeline "Claude Code best practices" --max-sources 5

# Direct URL crawling (skip discovery)
/reference-curator-pipeline https://docs.anthropic.com/en/docs/prompt-caching

# Resume from manifest
/reference-curator-pipeline ./manifest.json --auto-approve
```

Individual skills can still be run separately:
- `/reference-discovery` - Search and validate sources
- `/web-crawler` - Crawl URLs with auto-backend selection
- `/content-repository` - Manage stored documents
- `/content-distiller` - Summarize and extract key concepts
- `/quality-reviewer` - QA scoring and routing
- `/markdown-exporter` - Export to project files or JSONL

## Background Agents

For long-running tasks, use `run_in_background: true`:

```
# Good candidates for background execution:
- Full skill audit across all 50 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