Andrew Yim
d2d0a2d460
New skills: - Skill 33: Site migration planner with redirect mapping and monitoring - Skill 34: Reporting dashboard with HTML charts and Korean executive reports Bug fixes (Skill 34 - report_aggregator.py): - Add audit_type fallback for skill identification (was only using audit_id prefix) - Extract health scores from nested data dict (technical_score, onpage_score, etc.) - Support subdomain matching in domain filter (blog.ourdigital.org matches ourdigital.org) - Skip self-referencing DASH- aggregated reports Bug fixes (Skill 20 - naver_serp_analyzer.py): - Remove VIEW tab selectors (removed by Naver in 2026) - Add new section detectors: books (도서), shortform (숏폼), influencer (인플루언서) Improvements (Skill 34 - dashboard/executive report): - Add Korean category labels for Chart.js charts (기술 SEO, 온페이지, etc.) - Add Korean trend labels (개선 중 ↑, 안정 →, 하락 중 ↓) - Add English→Korean issue description translation layer (20 common patterns) Documentation improvements: - Add Korean triggers to 4 skill descriptions (19, 25, 28, 31) - Expand Skill 32 SKILL.md from 40→143 lines (was 6/10, added workflow, output format, limitations) - Add output format examples to Skills 27 and 28 SKILL.md - Add limitations sections to Skills 27 and 28 - Update README.md, CLAUDE.md, AGENTS.md for skills 33-34 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
246 lines
8.9 KiB
Markdown
246 lines
8.9 KiB
Markdown
# 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-34)
|
|
|
|
- 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
|
|
- Skill 33 provides site migration planning (pre-migration baseline, redirect mapping, risk assessment, post-migration monitoring)
|
|
- Skill 34 aggregates outputs from all SEO skills into executive reports, HTML dashboards, and Korean-language summaries
|
|
- 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`, `/seo-migration-planner`, `/seo-reporting-dashboard`
|
|
|
|
### 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 52 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
|