our-claude-skills/AGENTS.md

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