Andrew Yim
d1cd1298a8
Pipeline Orchestrator: - Add 07-pipeline-orchestrator skill with code/CLAUDE.md and desktop/SKILL.md - Add /reference-curator-pipeline slash command for full workflow automation - Add pipeline_runs and pipeline_iteration_tracker tables to schema.sql - Add v_pipeline_status and v_pipeline_iterations views - Add pipeline_config.yaml configuration template - Update AGENTS.md with Reference Curator Skills section - Update claude-project files with pipeline documentation Skill Format Refactoring: - Extract YAML frontmatter from SKILL.md files to separate skill.yaml - Add tools/ directories with MCP tool documentation - Update SKILL-FORMAT-REQUIREMENTS.md with new structure - Add migrate-skill-structure.py script for format conversion Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
213 lines
6.8 KiB
Markdown
213 lines
6.8 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 (10-19)
|
|
|
|
- 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
|
|
|
|
### GTM Skills (20-29)
|
|
|
|
- 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
|
|
|
|
### 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
|