Andrew Yim
7c5efea817
Renumber 12 existing skills to new ranges: - SEO: 11→13, 12→18, 13→16, 14→17, 15→14, 16→15, 17→29, 18→30, 19→12 - GTM: 20→60, 21→61, 22→62 Update cross-references in gateway architect/builder skills, GTM guardian README, CLAUDE.md (skill tables + directory layout), and AGENTS.md (domain routing ranges). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
242 lines
8.0 KiB
Markdown
242 lines
8.0 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-30)
|
|
|
|
- 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
|
|
- `11-seo-comprehensive-audit` orchestrates skills 12-18 for unified audits
|
|
- Skills 19-28 are reserved for future SEO capabilities
|
|
|
|
### 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 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
|