refactor: Reorganize skill numbering and update documentation
Skill Numbering Changes: - 01-03: OurDigital core (was 30-32) - 31-32: Notion tools (was 01-02) - 99_archive: Renamed from _archive for sorting New Files: - AGENTS.md: Claude Code agent routing guide - requirements.txt for 00-claude-code-setting, 32-notion-writer, 43-jamie-youtube-manager Documentation Updates: - CLAUDE.md: Updated skill inventory (23 skills) - AUDIT_REPORT.md: Current completion status (91%) - Archived REFACTORING_PLAN.md (most tasks complete) Removed: - ga-agent-skills/ (moved to separate repo ~/Project/dintel-ga4-agent) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
186
AGENTS.md
Normal file
186
AGENTS.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# 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
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user