zhongwei/gh-francyjglisboa-agent-skill-creator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e18b9b4fa8b57fe7ca653bdb46b1948fa6758141
gh-francyjglisboa-agent-ski…/SKILL.md
Zhongwei Li e18b9b4fa8 Initial commit
2025-11-29 18:27:25 +08:00

4117 lines
109 KiB
Markdown
Raw Blame History

---
name: agent-skill-creator
description: This enhanced skill should be used when the user asks to create an agent, automate a repetitive workflow, create a custom skill, or needs advanced agent creation capabilities. Activates with phrases like every day, daily I have to, I need to repeat, create agent for, automate workflow, create skill for, need to automate, turn process into agent. Supports single agents, multi-agent suites, transcript processing, template-based creation, and interactive configuration. Claude will use the enhanced protocol to research APIs, define analyses, structure everything, implement functional code, and create complete skills autonomously with optional user guidance.
---
# Agent Creator - Meta-Skill
This skill teaches Claude Code how to autonomously create complete agents with Claude Skills.
## When to Use This Skill
Claude should automatically activate this skill when the user:
✅ **Asks to create an agent**
- "Create an agent for [objective]"
- "I need an agent that [description]"
- "Develop an agent to automate [workflow]"
✅ **Asks to automate a workflow**
- "Automate this process: [description]"
- "Every day I do [repetitive task], automate this"
- "Turn this workflow into an agent"
✅ **Asks to create a skill**
- "Create a skill for [objective]"
- "Develop a custom skill for [domain]"
✅ **Describes a repetitive process**
- "Every day I [process]... takes Xh"
- "I repeatedly need to [task]"
- "Manual workflow: [description]"
## Overview
When activated, this skill guides Claude through **5 autonomous phases** to create a complete production-ready agent:
```
PHASE 1: DISCOVERY
├─ Research available APIs
├─ Compare options
└─ DECIDE which to use (with justification)
PHASE 2: DESIGN
├─ Think about use cases
├─ DEFINE useful analyses
└─ Specify methodologies
PHASE 3: ARCHITECTURE
├─ STRUCTURE folders and files
├─ Define necessary scripts
└─ Plan caching and performance
PHASE 4: DETECTION
├─ DETERMINE keywords
└─ Create precise description
PHASE 5: IMPLEMENTATION
├─ 🚨 FIRST: Create marketplace.json (MANDATORY!)
├─ Create SKILL.md (5000+ words)
├─ Implement Python scripts (functional!)
├─ Write references (useful!)
├─ Generate configs (real!)
├─ Create README
└─ ✅ FINAL: Test installation
```
**Output**: Complete agent in subdirectory ready to install.
---
## 🏗️ **Claude Skills Architecture: Understanding What We Create**
### **Important Terminology Clarification**
This meta-skill creates **Claude Skills**, which come in different architectural patterns:
#### **📋 Skill Types We Can Create**
**1. Simple Skill** (Single focused capability)
```
skill-name/
├── SKILL.md ← Single comprehensive skill file
├── scripts/ ← Optional supporting code
├── references/ ← Optional documentation
└── assets/ ← Optional templates
```
*Use when: Single objective, simple workflow, <1000 lines code*
**2. Complex Skill Suite** (Multiple specialized capabilities)
```
skill-suite/
├── .claude-plugin/
│ └── marketplace.json ← Organizes multiple component skills
├── component-1/
│ └── SKILL.md ← Specialized sub-skill
├── component-2/
│ └── SKILL.md ← Another specialized sub-skill
└── shared/ ← Shared resources
```
*Use when: Multiple related workflows, >2000 lines code, team maintenance*
#### **🎯 Architecture Decision Process**
During **PHASE 3: ARCHITECTURE**, this skill will:
1. **Analyze Complexity Requirements**
- Number of distinct workflows
- Code complexity estimation
- Maintenance considerations
2. **Choose Appropriate Architecture**
- Simple task → Simple Skill
- Complex multi-domain task → Skill Suite
- Hybrid requirements → Simple skill with components
3. **Apply Naming Convention**
- Generate descriptive base name from requirements
- Add "-cskill" suffix to identify as Claude Skill created by Agent-Skill-Creator
- Ensure consistent, professional naming across all created skills
4. **Document the Decision**
- Create `DECISIONS.md` explaining architecture choice
- Provide rationale for selected pattern
- Include migration path if needed
- Document naming convention applied
#### **🏷️ Naming Convention: "-cskill" Suffix**
**All skills created by this Agent-Skill-Creator use the "-cskill" suffix:**
**Simple Skills:**
- `pdf-text-extractor-cskill/`
- `csv-data-cleaner-cskill/`
- `weekly-report-generator-cskill/`
**Complex Skill Suites:**
- `financial-analysis-suite-cskill/`
- `e-commerce-automation-cskill/`
- `research-workflow-cskill/`
**Component Skills (within suites):**
- `data-acquisition-cskill/`
- `technical-analysis-cskill/`
- `reporting-generator-cskill/`
**Purpose of "-cskill" suffix:**
- ✅ **Clear Identification**: Immediately recognizable as a Claude Skill
- ✅ **Origin Attribution**: Created by Agent-Skill-Creator
- ✅ **Consistent Convention**: Professional naming standard
- ✅ **Avoids Confusion**: Distinguishes from manually created skills
- ✅ **Easy Organization**: Simple to identify and group created skills
#### **📚 Reference Documentation**
For complete understanding of Claude Skills architecture, see:
- `docs/CLAUDE_SKILLS_ARCHITECTURE.md` (comprehensive guide)
- `docs/DECISION_LOGIC.md` (architecture decision framework)
- `examples/` (simple vs complex examples)
- `examples/simple-skill/` (minimal example)
- `examples/complex-skill-suite/` (comprehensive example)
#### **✅ What We Create**
**ALWAYS creates a valid Claude Skill** - either:
- **Simple Skill** (single SKILL.md)
- **Complex Skill Suite** (multiple component skills with marketplace.json)
**NEVER creates "plugins" in the traditional sense** - we create Skills, which may be organized using marketplace.json for complex suites.
This terminology consistency eliminates confusion between Skills and Plugins.
---
## 🧠 Invisible Intelligence: AgentDB Integration
### Enhanced Intelligence (v2.1)
This skill now includes **invisible AgentDB integration** that learns from every agent creation and provides progressively smarter assistance.
**What happens automatically:**
- 🧠 **Learning Memory**: Stores every creation attempt as episodes
- ⚡ **Progressive Enhancement**: Each creation becomes faster and more accurate
- 🎯 **Smart Validation**: Mathematical proofs for all decisions
- 🔄 **Graceful Operation**: Works perfectly with or without AgentDB
**User Experience**: Same simple commands, agents get smarter magically!
### Integration Points
The AgentDB integration is woven into the 5 phases:
```
PHASE 1: DISCOVERY
├─ Research APIs
├─ 🧠 Query AgentDB for similar past successes
├─ Compare options using learned patterns
└─ DECIDE with historical confidence
PHASE 2: DESIGN
├─ Think about use cases
├─ 🧠 Retrieve successful analysis patterns
├─ DEFINE using proven methodologies
└─ Enhance with learned improvements
PHASE 3: ARCHITECTURE
├─ STRUCTURE using validated patterns
├─ 🧠 Apply proven architectural decisions
├─ Plan based on success history
└─ Optimize with learned insights
PHASE 4: DETECTION
├─ DETERMINE keywords using learned patterns
├─ 🧠 Use successful keyword combinations
└─ Create optimized description
PHASE 5: IMPLEMENTATION
├─ Create marketplace.json
├─ 🧠 Apply proven code patterns
├─ Store episode for future learning
└─ ✅ Complete with enhanced validation
```
### Learning Progression
**First Creation:**
```
"Create financial analysis agent"
→ Standard agent creation process
→ Episode stored for learning
→ No visible difference to user
```
**After 10+ Creations:**
```
"Create financial analysis agent"
→ 40% faster (learned optimal queries)
→ Better API selection (historical success)
→ Proven architectural patterns
→ User sees: "⚡ Optimized based on similar successful agents"
```
**After 30+ Days:**
```
"Create financial analysis agent"
→ Personalized recommendations based on patterns
→ Predictive insights about user preferences
→ Automatic skill consolidation
→ User sees: "🌟 I notice you prefer comprehensive financial agents - shall I include portfolio optimization?"
```
---
## 🚀 Enhanced Features (v2.0)
### Multi-Agent Architecture
The enhanced agent-creator now supports:
**✅ Single Agent Creation** (Original functionality)
```
"Create an agent for stock analysis"
→ ./stock-analysis-agent/
```
**✅ Multi-Agent Suite Creation** (NEW)
```
"Create a financial analysis suite with 4 agents:
fundamental analysis, technical analysis,
portfolio management, and risk assessment"
→ ./financial-suite/
├── fundamental-analysis/
├── technical-analysis/
├── portfolio-management/
└── risk-assessment/
```
**✅ Transcript Intelligence Processing** (NEW)
```
"I have a YouTube transcript about e-commerce analytics,
can you create agents based on the workflows described?"
→ Automatically extracts multiple workflows
→ Creates integrated agent suite
```
**✅ Template-Based Creation** (NEW)
```
"Create an agent using the financial-analysis template"
→ Uses pre-configured APIs and analyses
→ 80% faster creation
```
**✅ Interactive Configuration** (NEW)
```
"Help me create an agent with preview options"
→ Step-by-step wizard
→ Real-time preview
→ Iterative refinement
```
### Enhanced Marketplace.json Support
**v1.0 Format** (Still supported):
```json
{
"name": "single-agent",
"plugins": [
{
"skills": ["./"]
}
]
}
```
**v2.0 Format** (NEW - Multi-skill support):
```json
{
"name": "agent-suite",
"plugins": [
{
"name": "fundamental-analysis",
"source": "./fundamental-analysis/",
"skills": ["./SKILL.md"]
},
{
"name": "technical-analysis",
"source": "./technical-analysis/",
"skills": ["./SKILL.md"]
}
]
}
```
---
## Autonomous Creation Protocol
### Fundamental Principles
**Autonomy**:
- ✅ Claude DECIDES which API to use (doesn't ask user)
- ✅ Claude DEFINES which analyses to perform (based on value)
- ✅ Claude STRUCTURES optimally (best practices)
- ✅ Claude IMPLEMENTS complete code (no placeholders)
- ✅ **NEW**: Claude LEARNS from experience (AgentDB integration)
**Quality**:
- ✅ Production-ready code (no TODOs)
- ✅ Useful documentation (not "see docs")
- ✅ Real configs (no placeholders)
- ✅ Robust error handling
- ✅ **NEW**: Intelligence validated with mathematical proofs
**Completeness**:
- ✅ Complete SKILL.md (5000+ words)
- ✅ Functional scripts (1000+ lines total)
- ✅ References with content (3000+ words)
- ✅ Valid assets/configs
- ✅ README with instructions
### Requirements Extraction
When user describes workflow vaguely, extract:
**From what the user said**:
- Domain (agriculture? finance? weather?)
- Data source (mentioned? if not, research)
- Main tasks (download? analyze? compare?)
- Frequency (daily? weekly? on-demand?)
- Current time spent (to calculate ROI)
**🆕 Enhanced Analysis (v2.0)**:
- **Multi-Agent Detection**: Look for keywords like "suite", "multiple", "separate agents"
- **Transcript Analysis**: Detect if input is a video/transcript requiring workflow extraction
- **Template Matching**: Identify if user wants template-based creation
- **Interactive Preference**: Detect if user wants guidance vs full autonomy
- **Integration Needs**: Determine if agents should communicate with each other
**🆕 Transcript Processing**:
When user provides transcripts:
```python
# Enhanced transcript analysis
def analyze_transcript(transcript: str) -> List[WorkflowSpec]:
"""Extract multiple workflows from transcripts automatically"""
workflows = []
# 1. Identify distinct processes
processes = extract_processes(transcript)
# 2. Group related steps
for process in processes:
steps = extract_sequence_steps(transcript, process)
apis = extract_mentioned_apis(transcript, process)
outputs = extract_desired_outputs(transcript, process)
workflows.append(WorkflowSpec(
name=process,
steps=steps,
apis=apis,
outputs=outputs
))
return workflows
```
**🆕 Multi-Agent Strategy Decision**:
```python
def determine_creation_strategy(user_input: str, workflows: List[WorkflowSpec]) -> CreationStrategy:
"""Decide whether to create single agent, suite, or integrated system"""
if len(workflows) > 1:
if workflows_are_related(workflows):
return CreationStrategy.INTEGRATED_SUITE
else:
return CreationStrategy.MULTI_AGENT_SUITE
else:
return CreationStrategy.SINGLE_AGENT
```
**Questions to ask** (only if critical and not inferable):
- "Prefer free API or paid is ok?"
- "Need historical data for how many years?"
- "Focus on which geography/country?"
- **🆕 "Create separate agents or integrated suite?"** (if multiple workflows detected)
- **🆕 "Want interactive preview before creation?"** (for complex projects)
**Rule**: Minimize questions. Infer/decide whenever possible.
## 🎯 Template-Based Creation (NEW v2.0)
### Available Templates
The enhanced agent-creator includes pre-built templates for common domains:
**📊 Financial Analysis Template**
```json
Domain: Finance & Investments
APIs: Alpha Vantage, Yahoo Finance
Analyses: Fundamental, Technical, Portfolio
Time: 15-20 minutes
```
**🌡️ Climate Analysis Template**
```json
Domain: Climate & Environmental
APIs: Open-Meteo, NOAA
Analyses: Anomalies, Trends, Seasonal
Time: 20-25 minutes
```
**🛒 E-commerce Analytics Template**
```json
Domain: Business & E-commerce
APIs: Google Analytics, Stripe, Shopify
Analyses: Traffic, Revenue, Cohort, Products
Time: 25-30 minutes
```
### Template Matching Process
```python
def match_template(user_input: str) -> TemplateMatch:
"""Automatically suggest best template based on user input"""
# 1. Extract keywords from user input
keywords = extract_keywords(user_input)
# 2. Calculate similarity scores with all templates
matches = []
for template in available_templates:
score = calculate_similarity(keywords, template.keywords)
matches.append((template, score))
# 3. Rank by similarity
matches.sort(key=lambda x: x[1], reverse=True)
# 4. Return best match if confidence > threshold
if matches[0][1] > 0.7:
return TemplateMatch(template=matches[0][0], confidence=matches[0][1])
else:
return None # No suitable template found
```
### Template Usage Examples
**Direct Template Request:**
```
"Create an agent using the financial-analysis template"
→ Uses pre-configured structure
→ 80% faster creation
→ Proven architecture
```
**Automatic Template Detection:**
```
"I need to analyze stock performance and calculate RSI, MACD"
→ Detects financial domain
→ Suggests financial-analysis template
→ User confirms or continues custom
```
**Template Customization:**
```
"Use the climate template but add drought analysis"
→ Starts with climate template
→ Adds custom drought analysis
→ Modifies structure accordingly
```
## 🚀 Batch Agent Creation (NEW v2.0)
### Multi-Agent Suite Creation
The enhanced agent-creator can create multiple agents in a single operation:
**When to Use Batch Creation:**
- Transcript describes multiple distinct workflows
- User explicitly asks for multiple agents
- Complex system requiring specialized components
- Microservices architecture preferred
### Batch Creation Process
```python
def create_agent_suite(user_input: str, workflows: List[WorkflowSpec]) -> AgentSuite:
"""Create multiple related agents in one operation"""
# 1. Analyze workflow relationships
relationships = analyze_workflow_relationships(workflows)
# 2. Determine optimal structure
if workflows_are_tightly_coupled(workflows):
structure = "integrated_suite"
else:
structure = "independent_agents"
# 3. Create suite directory
suite_name = generate_suite_name(user_input)
create_suite_directory(suite_name)
# 4. Create each agent
agents = []
for workflow in workflows:
agent = create_single_agent(workflow, suite_name)
agents.append(agent)
# 5. Create integration layer (if needed)
if structure == "integrated_suite":
create_integration_layer(agents, suite_name)
# 6. Create suite-level marketplace.json
create_suite_marketplace_json(suite_name, agents)
return AgentSuite(name=suite_name, agents=agents, structure=structure)
```
### Batch Creation Examples
**Financial Suite Example:**
```
"Create a complete financial analysis system with 4 agents:
1. Fundamental analysis for company valuation
2. Technical analysis for trading signals
3. Portfolio management and optimization
4. Risk assessment and compliance"
→ ./financial-analysis-suite/
├── .claude-plugin/marketplace.json (multi-skill)
├── fundamental-analysis/
│ ├── SKILL.md
│ ├── scripts/
│ └── tests/
├── technical-analysis/
├── portfolio-management/
└── risk-assessment/
```
**E-commerce Suite Example:**
```
"Build an e-commerce analytics system based on this transcript:
- Traffic analysis from Google Analytics
- Revenue tracking from Stripe
- Product performance from Shopify
- Customer cohort analysis
- Automated reporting dashboard"
→ ./e-commerce-analytics-suite/
├── traffic-analysis-agent/
├── revenue-tracking-agent/
├── product-performance-agent/
├── cohort-analysis-agent/
└── reporting-dashboard-agent/
```
### Multi-Skill Marketplace.json Structure
**Suite-Level Configuration:**
```json
{
"name": "financial-analysis-suite",
"metadata": {
"description": "Complete financial analysis system with fundamental, technical, portfolio, and risk analysis",
"version": "1.0.0",
"suite_type": "financial_analysis"
},
"plugins": [
{
"name": "fundamental-analysis-plugin",
"description": "Fundamental analysis for company valuation and financial metrics",
"source": "./fundamental-analysis/",
"skills": ["./SKILL.md"]
},
{
"name": "technical-analysis-plugin",
"description": "Technical analysis with trading indicators and signals",
"source": "./technical-analysis/",
"skills": ["./SKILL.md"]
},
{
"name": "portfolio-management-plugin",
"description": "Portfolio optimization and management analytics",
"source": "./portfolio-management/",
"skills": ["./SKILL.md"]
},
{
"name": "risk-assessment-plugin",
"description": "Risk analysis and compliance monitoring",
"source": "./risk-assessment/",
"skills": ["./SKILL.md"]
}
],
"integrations": {
"data_sharing": true,
"cross_agent_communication": true,
"shared_utils": "./shared/"
}
}
```
### Batch Creation Benefits
**✅ Time Efficiency:**
- Create 4 agents in ~60 minutes (vs 4 hours individually)
- Shared utilities and infrastructure
- Consistent architecture and documentation
**✅ Integration Benefits:**
- Agents designed to work together
- Shared data structures and formats
- Unified testing and deployment
**✅ Maintenance Benefits:**
- Single marketplace.json for installation
- Coordinated versioning and updates
- Shared troubleshooting documentation
### Batch Creation Commands
**Explicit Multi-Agent Request:**
```
"Create 3 agents for climate analysis:
1. Temperature anomaly detection
2. Precipitation pattern analysis
3. Extreme weather event tracking
Make them work together as a system."
```
**Transcript-Based Batch Creation:**
```
"Here's a transcript of a 2-hour tutorial on building
a complete business intelligence system. Create agents
for all the workflows described in the video."
```
**Template-Based Batch Creation:**
```
"Use the e-commerce template to create a full analytics suite:
- Traffic analysis
- Revenue tracking
- Customer analytics
- Product performance
- Marketing attribution"
```
## 🎮 Interactive Configuration Wizard (NEW v2.0)
### When to Use Interactive Mode
The enhanced agent-creator includes an interactive wizard for:
- **Complex Projects**: Multi-agent systems, integrations
- **User Preference**: When users want guidance vs full autonomy
- **High-Stakes Projects**: When preview and iteration are important
- **Learning**: Users who want to understand the creation process
### Interactive Wizard Process
```python
def interactive_agent_creation():
"""
Step-by-step guided agent creation with real-time preview
"""
# Step 1: Welcome and Requirements Gathering
print("🚀 Welcome to Enhanced Agent Creator!")
print("I'll help you create custom agents through an interactive process.")
user_needs = gather_requirements_interactively()
# Step 2: Workflow Analysis
print("\n📋 Analyzing your requirements...")
workflows = analyze_and_confirm_workflows(user_needs)
# Step 3: Strategy Selection
strategy = select_creation_strategy(workflows)
print(f"🎯 Recommended: {strategy.description}")
# Step 4: Preview and Refinement
while True:
preview = generate_interactive_preview(strategy)
show_preview(preview)
if user_approves():
break
else:
strategy = refine_based_on_feedback(strategy, preview)
# Step 5: Creation
print("\n⚙️ Creating your agent(s)...")
result = execute_creation(strategy)
# Step 6: Validation and Tutorial
validate_created_agents(result)
provide_usage_tutorial(result)
return result
```
### Interactive Interface Examples
**Step 1: Requirements Gathering**
```
🚀 Welcome to Enhanced Agent Creator!
Let me understand what you want to build:
1. What's your main goal?
[ ] Automate a repetitive workflow
[ ] Analyze data from specific sources
[ ] Create custom tools for my domain
[ ] Build a complete system with multiple components
2. What's your domain/industry?
[ ] Finance & Investing
[ ] E-commerce & Business
[ ] Climate & Environment
[ ] Healthcare & Medicine
[ ] Other (please specify): _______
3. Do you have existing materials?
[ ] YouTube transcript or video
[ ] Documentation or tutorials
[ ] Existing code/scripts
[ ] Starting from scratch
Your responses: [Finance & Investing] [Starting from scratch]
```
**Step 2: Workflow Analysis**
```
📋 Based on your input, I detect:
Domain: Finance & Investing
Potential Workflows:
1. Fundamental Analysis (P/E, ROE, valuation metrics)
2. Technical Analysis (RSI, MACD, trading signals)
3. Portfolio Management (allocation, optimization)
4. Risk Assessment (VaR, drawdown, compliance)
Which workflows interest you? Select all that apply:
[✓] Technical Analysis
[✓] Portfolio Management
[ ] Fundamental Analysis
[ ] Risk Assessment
Selected: 2 workflows detected
```
**Step 3: Strategy Selection**
```
🎯 Recommended Creation Strategy:
Multi-Agent Suite Creation
- Create 2 specialized agents
- Each agent handles one workflow
- Agents can communicate and share data
- Unified installation and documentation
Estimated Time: 35-45 minutes
Output: ./finance-suite/ (2 agents)
Options:
[✓] Accept recommendation
[ ] Create single integrated agent
[ ] Use template-based approach
[ ] Customize strategy
```
**Step 4: Interactive Preview**
```
📊 Preview of Your Finance Suite:
Structure:
./finance-suite/
├── .claude-plugin/marketplace.json
├── technical-analysis-agent/
│ ├── SKILL.md (2,100 words)
│ ├── scripts/ (Python, 450 lines)
│ └── tests/ (15 tests)
└── portfolio-management-agent/
├── SKILL.md (1,800 words)
├── scripts/ (Python, 380 lines)
└── tests/ (12 tests)
Features:
✅ Real-time stock data (Alpha Vantage API)
✅ 10 technical indicators (RSI, MACD, Bollinger...)
✅ Portfolio optimization algorithms
✅ Risk metrics and rebalancing alerts
✅ Automated report generation
APIs Required:
- Alpha Vantage (free tier available)
- Yahoo Finance (no API key needed)
Would you like to:
[✓] Proceed with creation
[ ] Modify technical indicators
[ ] Add risk management features
[ ] Change APIs
[ ] See more details
```
### Wizard Benefits
**🎯 User Empowerment:**
- Users see exactly what will be created
- Can modify and iterate before implementation
- Learn about the process and architecture
- Make informed decisions
**⚡ Efficiency:**
- Faster than custom development
- Better than black-box creation
- Reduces rework and iterations
- Higher satisfaction rates
**🛡️ Risk Reduction:**
- Preview prevents misunderstandings
- Iterative refinement catches issues early
- Users can validate requirements
- Clear expectations management
### Interactive Commands
**Start Interactive Mode:**
```
"Help me create an agent with interactive options"
"Walk me through creating a financial analysis system"
"I want to use the configuration wizard"
```
**Resume from Preview:**
```
"Show me the preview again before creating"
"Can I modify the preview you showed me?"
"I want to change something in the proposed structure"
```
**Learning Mode:**
```
"Create an agent and explain each step as you go"
"Teach me how agent creation works while building"
"I want to understand the architecture decisions"
```
### Wizard Customization Options
**Advanced Mode:**
```
⚙️ Advanced Configuration Options:
1. API Selection Strategy
[ ] Prefer free APIs
[ ] Prioritize data quality
[ ] Minimize rate limits
[ ] Multiple API fallbacks
2. Architecture Preference
[ ] Modular (separate scripts per function)
[ ] Integrated (all-in-one scripts)
[ ] Hybrid (core + specialized modules)
3. Testing Strategy
[ ] Basic functionality tests
[ ] Comprehensive test suite
[ ] Integration tests
[ ] Performance benchmarks
4. Documentation Level
[ ] Minimal (API docs only)
[ ] Standard (complete usage guide)
[ ] Extensive (tutorials + examples)
[ ] Academic (methodology + research)
```
**Template Customization:**
```
🎨 Template Customization:
Base Template: Financial Analysis
✓ Include technical indicators: RSI, MACD, Bollinger Bands
✓ Add portfolio optimization: Modern Portfolio Theory
✓ Risk metrics: VaR, Maximum Drawdown, Sharpe Ratio
Additional Features:
[ ] Machine learning predictions
[ ] Sentiment analysis from news
[ ] Options pricing models
[ ] Cryptocurrency support
Remove Features:
[ ] Fundamental analysis (not needed)
[ ] Economic calendar integration
```
## 🧠 Invisible Intelligence: AgentDB Integration (NEW v2.1)
### What This Means for Users
**The agent-creator now has "memory" and gets smarter over time - automatically!**
✅ **No setup required** - AgentDB initializes automatically in the background
✅ **No commands to learn** - You use the exact same natural language commands
✅ **Invisible enhancement** - Agents become more intelligent without you doing anything
✅ **Progressive learning** - Each agent learns from experience and shares knowledge
### How It Works (Behind the Scenes)
When you create an agent:
```
User: "Create agent for financial analysis"
🤖 Agent-Creator (v2.1):
"✅ Creating financial-analysis-agent with learned intelligence..."
"✅ Using template with 94% historical success rate..."
"✅ Applied 12 learned improvements from similar agents..."
"✅ Mathematical proof: template choice validated with 98% confidence..."
```
### Key Benefits (Automatic & Invisible)
**🧠 Learning Memory:**
- Agents remember what works and what doesn't
- Successful patterns are automatically reused
- Failed approaches are automatically avoided
**📊 Smart Decisions:**
- Template selection based on real success data
- Architecture optimized from thousands of similar agents
- API choices validated with mathematical proofs
**🔄 Continuous Improvement:**
- Each agent gets smarter with use
- Knowledge shared across all agents automatically
- Nightly reflection system refines capabilities
### User Experience: "The Magic Gets Better"
**First Week:**
```
"Analyze Tesla stock"
🤖 "📊 Tesla analysis: RSI 65.3, MACD bullish"
```
**After One Month:**
```
"Analyze Tesla stock"
🤖 "📊 Tesla analysis: RSI 65.3, MACD bullish (enhanced with your patterns)"
🤖 "🧠 Pattern detected: You always ask on Mondays - prepared weekly analysis"
🤖 "📈 Added volatility prediction based on your usage patterns"
```
### Technical Implementation (Invisible to Users)
```python
# This happens automatically behind the scenes
class AgentCreatorV21:
def create_agent(self, user_input):
# AgentDB enhancement (invisible)
intelligence = enhance_agent_creation(user_input)
# Enhanced template selection
template = intelligence.template_choice or self.default_template
# Learned improvements automatically applied
improvements = intelligence.learned_improvements
# Create agent with enhanced intelligence
return self.create_with_intelligence(template, improvements)
```
### Graceful Fallback
If AgentDB isn't available (rare), the agent-creator works exactly like v2.0:
```
"Create agent for financial analysis"
🤖 "✅ Agent created (standard mode)"
```
No interruption, no errors, just no learning enhancements.
### Privacy & Performance
- ✅ All learning happens locally on your machine
- ✅ No external dependencies required
- ✅ Automatic cleanup and optimization
- ✅ Zero impact on creation speed
---
## 📦 Cross-Platform Export (NEW v3.2)
### What This Feature Does
**Automatically package skills for use across all Claude platforms:**
Skills created in Claude Code can be exported for:
- ✅ **Claude Desktop** - Manual .zip upload
- ✅ **claude.ai** (Web) - Browser-based upload
- ✅ **Claude API** - Programmatic integration
This makes your skills portable and shareable across all Claude ecosystems.
### When to Activate Export
Claude should activate export capabilities when user says:
✅ **Export requests:**
- "Export [skill-name] for Desktop"
- "Package [skill-name] for claude.ai"
- "Create API package for [skill-name]"
- "Export [skill-name] for all platforms"
✅ **Cross-platform requests:**
- "Make [skill-name] compatible with Claude Desktop"
- "I need to share [skill-name] with Desktop users"
- "Package [skill-name] as .zip"
- "Create cross-platform version of [skill-name]"
✅ **Version-specific exports:**
- "Export [skill-name] with version 2.0.1"
- "Package [skill-name] v1.5.0 for API"
### Export Process
When user requests export:
**Step 1: Locate Skill**
```python
# Search common locations
locations = [
f"./{skill_name}-cskill/", # Current directory
f"references/examples/{skill_name}-cskill/", # Examples
user_specified_path # If provided
]
skill_path = find_skill(locations)
```
**Step 2: Validate Structure**
```python
# Ensure skill is export-ready
valid, issues = validate_skill_structure(skill_path)
if not valid:
report_issues_to_user(issues)
return
```
**Step 3: Execute Export**
```bash
# Run export utility
python scripts/export_utils.py {skill_path} \
--variant {desktop|api|both} \
--version {version} \
--output-dir exports/
```
**Step 4: Report Results**
```
✅ Export completed!
📦 Packages created:
- Desktop: exports/{skill}-desktop-v1.0.0.zip (2.3 MB)
- API: exports/{skill}-api-v1.0.0.zip (1.2 MB)
📄 Installation guide: exports/{skill}-v1.0.0_INSTALL.md
🎯 Ready for:
✅ Claude Desktop upload
✅ claude.ai upload
✅ Claude API integration
```
### Post-Creation Export (Opt-In)
After successfully creating a skill in PHASE 5, offer export:
```
✅ Skill created successfully: {skill-name-cskill}/
📦 Cross-Platform Export Options:
Would you like to create export packages for other Claude platforms?
1. Desktop/Web (.zip for manual upload)
2. API (.zip for programmatic use)
3. Both (comprehensive package)
4. Skip (Claude Code only)
Choice: _
```
**If user chooses 1, 2, or 3:**
- Execute export_utils.py with selected variants
- Report package locations
- Provide next steps for each platform
**If user chooses 4 or skips:**
- Continue with normal completion
- Skill remains Claude Code only
### Export Variants
**Desktop/Web Package** (`*-desktop-*.zip`):
- Complete documentation
- All scripts and assets
- Full references
- Optimized for user experience
- Typical size: 2-5 MB
**API Package** (`*-api-*.zip`):
- Execution-focused
- Size-optimized (< 8MB)
- Minimal documentation
- Essential scripts only
- Typical size: 0.5-2 MB
### Version Detection
Automatically detect version from:
1. **Git tags** (priority):
```bash
git describe --tags --abbrev=0
```
2. **SKILL.md frontmatter**:
```yaml
---
name: skill-name
version: 1.2.3
---
```
3. **Default**: `v1.0.0`
**User can override**:
- "Export with version 2.1.0"
- `--version 2.1.0` flag
### Export Validation
Before creating packages, validate:
✅ **Required:**
- SKILL.md exists
- Valid frontmatter (---...---)
- `name:` field present (≤ 64 chars)
- `description:` field present (≤ 1024 chars)
✅ **Size Checks:**
- Desktop: Reasonable size
- API: < 8MB (hard limit)
✅ **Security:**
- No .env files
- No credentials.json
- No sensitive data
If validation fails, report specific issues to user.
### Installation Guides
Auto-generate platform-specific guides:
**File**: `exports/{skill}-v{version}_INSTALL.md`
**Contents:**
- Package information
- Installation steps for Desktop
- Installation steps for claude.ai
- API integration code examples
- Platform comparison table
- Troubleshooting tips
### Export Commands Reference
```bash
# Export both variants (default)
python scripts/export_utils.py ./skill-name-cskill
# Export only Desktop
python scripts/export_utils.py ./skill-name-cskill --variant desktop
# Export only API
python scripts/export_utils.py ./skill-name-cskill --variant api
# With custom version
python scripts/export_utils.py ./skill-name-cskill --version 2.0.1
# To custom directory
python scripts/export_utils.py ./skill-name-cskill --output-dir ./releases
```
### Documentation References
Point users to comprehensive guides:
- **Export Guide**: `references/export-guide.md`
- **Cross-Platform Guide**: `references/cross-platform-guide.md`
- **Exports README**: `exports/README.md`
### Integration with AgentDB
Export process can leverage AgentDB learning:
- Remember successful export configurations
- Suggest optimal variant based on use case
- Track which exports are most commonly used
- Learn from export failures to improve validation
---
## PHASE 1: Discovery and Research
**Objective**: DECIDE which API/data source to use with AgentDB intelligence
### Process
**1.1 Identify domain and query AgentDB**
From user input, identify the domain and immediately query AgentDB for learned patterns:
```python
# Import AgentDB bridge (invisible to user)
from integrations.agentdb_bridge import get_agentdb_bridge
# Get AgentDB intelligence
bridge = get_agentdb_bridge()
intelligence = bridge.enhance_agent_creation(user_input, domain)
# Log: AgentDB provides insights if available
if intelligence.learned_improvements:
print(f"🧠 Found {len(intelligence.learned_improvements)} relevant patterns")
```
**Domain mapping with AgentDB insights:**
- Agriculture → APIs: USDA NASS, FAO, World Bank Ag
- Finance → APIs: Alpha Vantage, Yahoo Finance, Fed Economic Data
- Weather → APIs: NOAA, OpenWeather, Weather.gov
- Economy → APIs: World Bank, IMF, FRED
**1.2 Research available APIs with learned preferences**
For the domain, use WebSearch to find:
- Available public APIs
- Documentation
- Characteristics (free? rate limits? coverage?)
**AgentDB Enhancement**: Prioritize APIs that have shown higher success rates:
```python
# AgentDB influences search based on historical success
if intelligence.success_probability > 0.8:
print(f"🎯 High success domain detected - optimizing API selection")
```
**Example with AgentDB insights**:
```
WebSearch: "US agriculture API free historical data"
WebSearch: "USDA API documentation"
WebFetch: [doc URLs found]
# AgentDB check: "Has similar domain been successful before?"
# AgentDB provides: "USDA NASS: 94% success rate in agriculture domain"
```
**1.3 Compare options with AgentDB validation**
Create mental table comparing:
- Data coverage (fit with need)
- Cost (free vs paid)
- Rate limits (sufficient?)
- Data quality (official? reliable?)
- Documentation (good? examples?)
- Ease of use
- **🧠 AgentDB Success Rate** (historical validation)
**AgentDB Mathematical Validation**:
```python
# AgentDB provides mathematical proof for selection
if intelligence.mathematical_proof:
print(f"📊 API selection validated: {intelligence.mathematical_proof}")
```
**1.4 DECIDE with AgentDB confidence**
Choose 1 API and justify with AgentDB backing:
**Decision with AgentDB confidence:**
- **Selected API**: [API name]
- **Success Probability**: {intelligence.success_probability:.1%}
- **Mathematical Proof**: {intelligence.mathematical_proof}
- **Learned Improvements**: {intelligence.learned_improvements}
**Document decision** in separate file:
```markdown
# Architecture Decisions
## Selected API: [Name]
**Justification**:
- ✅ Coverage: [details]
- ✅ Cost: [free/paid]
- ✅ Rate limit: [number]
- ✅ Quality: [official/private]
- ✅ Docs: [quality]
**Alternatives considered**:
- API X: Rejected because [reason]
- API Y: Rejected because [reason]
**Conclusion**: [Chosen API] is the best option because [synthesis]
```
**1.5 Research technical details**
Use WebFetch to load API documentation and extract:
- Base URL
- Main endpoints
- Authentication
- Important parameters
- Response format
- Rate limits
- Request/response examples
**See** `references/phase1-discovery.md` for complete details.
## PHASE 2: Analysis Design
**Objective**: DEFINE which analyses the agent will perform
### Process
**2.1 Think about use cases**
For the described workflow, which questions will the user ask frequently?
**Brainstorm**: List 10-15 typical questions
**2.2 Group by analysis type**
Group similar questions:
- Simple queries (fetch + format)
- Temporal comparisons (YoY)
- Rankings (sort + share)
- Trends (time series + CAGR)
- Projections (forecasting)
- Aggregations (regional/categorical)
**2.3 DEFINE priority analyses**
Choose 4-6 analyses that cover 80% of use cases.
For each analysis:
- Name
- Objective
- Required inputs
- Expected outputs
- Methodology (formulas, transformations)
- Interpretation
**2.4 ADD Comprehensive Report Function** (🆕 Enhancement #8 - MANDATORY!)
**⚠️ COMMON PROBLEM:** v1.0 skills had isolated functions. When user asks for "complete report", Claude didn't know how to combine all analyses.
**Solution:** ALWAYS include as last analysis function:
```python
def comprehensive_{domain}_report(
entity: str,
year: Optional[int] = None,
include_metrics: Optional[List[str]] = None,
client: Optional[Any] = None
) -> Dict:
"""
Generate comprehensive report combining ALL available metrics.
This is a "one-stop" function that users can call to get
complete picture without knowing individual functions.
Args:
entity: Entity to analyze (e.g., commodity, stock, location)
year: Year (None for current year with auto-detection)
include_metrics: Which metrics to include (None = all available)
client: API client instance (optional, created if None)
Returns:
Dict with ALL metrics consolidated:
{
'entity': str,
'year': int,
'year_info': str,
'generated_at': str (ISO timestamp),
'metrics': {
'metric1_name': {metric1_data},
'metric2_name': {metric2_data},
...
},
'summary': str (overall insights),
'alerts': List[str] (important findings)
}
Example:
>>> report = comprehensive_{domain}_report("CORN")
>>> print(report['summary'])
"CORN 2025: Production up 5% YoY, yield at record high..."
"""
from datetime import datetime
from utils.helpers import get_{domain}_year_with_fallback, format_year_message
# Auto-detect year
year_requested = year
if year is None:
year, _ = get_{domain}_year_with_fallback()
# Initialize report
report = {
'entity': entity,
'year': year,
'year_requested': year_requested,
'year_info': format_year_message(year, year_requested),
'generated_at': datetime.now().isoformat(),
'metrics': {},
'alerts': []
}
# Determine which metrics to include
if include_metrics is None:
# Include ALL available metrics
metrics_to_fetch = ['{metric1}', '{metric2}', '{metric3}', ...]
else:
metrics_to_fetch = include_metrics
# Call ALL individual analysis functions
# Graceful degradation: if one fails, others still run
if '{metric1}' in metrics_to_fetch:
try:
report['metrics']['{metric1}'] = {metric1}_analysis(entity, year, client)
except Exception as e:
report['metrics']['{metric1}'] = {
'error': str(e),
'status': 'unavailable'
}
report['alerts'].append(f"{metric1} data unavailable: {e}")
if '{metric2}' in metrics_to_fetch:
try:
report['metrics']['{metric2}'] = {metric2}_analysis(entity, year, client)
except Exception as e:
report['metrics']['{metric2}'] = {
'error': str(e),
'status': 'unavailable'
}
# Repeat for ALL metrics...
# Generate summary based on all available data
report['summary'] = _generate_summary(report['metrics'], entity, year)
# Detect important findings
report['alerts'].extend(_detect_alerts(report['metrics']))
return report
def _generate_summary(metrics: Dict, entity: str, year: int) -> str:
"""Generate human-readable summary from all metrics."""
insights = []
# Extract key insights from each metric
for metric_name, metric_data in metrics.items():
if 'error' not in metric_data:
# Extract most important insight from this metric
key_insight = _extract_key_insight(metric_name, metric_data)
if key_insight:
insights.append(key_insight)
# Combine into coherent summary
if insights:
summary = f"{entity} {year}: " + ". ".join(insights[:3]) # Top 3 insights
else:
summary = f"{entity} {year}: No data available"
return summary
def _detect_alerts(metrics: Dict) -> List[str]:
"""Detect significant findings that need attention."""
alerts = []
# Check each metric for alert conditions
for metric_name, metric_data in metrics.items():
if 'error' in metric_data:
continue
# Domain-specific alert logic
# Example: Large changes, extreme values, anomalies
if metric_name == '{metric1}' and 'change_percent' in metric_data:
if abs(metric_data['change_percent']) > 15:
alerts.append(
f"⚠ Large {metric1} change: {metric_data['change_percent']:.1f}%"
)
return alerts
```
**Why it's mandatory:**
- ✅ Users want "complete report" → 1 function does everything
- ✅ Ideal for executive dashboards
- ✅ Facilitates sales ("everything in one report")
- ✅ Much better UX (no need to know individual functions)
**When to mention in SKILL.md:**
```markdown
## Comprehensive Analysis (All-in-One)
To get a complete report combining ALL metrics:
Use the `comprehensive_{domain}_report()` function.
This function:
- Fetches ALL available metrics
- Combines into single report
- Generates automatic summary
- Detects important alerts
- Degrades gracefully (if 1 metric fails, others work)
Usage example:
"Generate complete report for {entity}"
"Complete dashboard for {entity}"
"All metrics for {entity}"
```
**Impact:**
- ✅ 10x better UX (1 query = everything)
- ✅ More useful skills for end users
- ✅ Facilitates commercial adoption
**2.5 Specify methodologies**
For quantitative analyses, define:
- Mathematical formulas
- Statistical validations
- Interpretations
- Edge cases
**See** `references/phase2-design.md` for detailed methodologies.
## PHASE 3: Architecture
**Objective**: STRUCTURE the agent optimally
### Process
**3.1 Define folder structure**
Based on analyses and API:
```
agent-name/
├── SKILL.md
├── scripts/
│ ├── [fetch/parse/analyze separate or together?]
│ └── utils/
│ └── [cache? rate limiter? validators?]
├── references/
│ └── [API docs? methodologies? troubleshooting?]
└── assets/
└── [configs? metadata?]
```
**Decisions**:
- Separate scripts (modular) vs monolithic?
- Which utilities needed?
- Which references useful?
- Which configs/assets?
**3.2 Define responsibilities**
For each script, specify:
- File name
- Function/purpose
- Input and output
- Specific responsibilities
- ~Expected number of lines
**3.3 Plan references**
Which reference files to create?
- API guide (how to use API)
- Analysis methods (methodologies)
- Troubleshooting (common errors)
- Domain knowledge (domain context)
**3.4 Performance strategy**
- Cache: What to cache? TTL?
- Rate limiting: How to control?
- Optimizations: Parallelization? Lazy loading?
**See** `references/phase3-architecture.md` for structuring patterns.
## PHASE 4: Automatic Detection
**Objective**: DETERMINE keywords for automatic activation
### Process
**4.1 List domain entities**
- Organizations/data sources
- Main metrics
- Geography (countries, regions, states)
- Temporality (years, periods)
**4.2 List typical actions**
- Query: "what", "how much", "show"
- Compare: "compare", "vs", "versus"
- Rank: "top", "best", "ranking"
- Analyze: "trend", "growth", "analyze"
- Forecast: "predict", "project", "forecast"
**4.3 List question variations**
For each analysis type, how might the user ask?
**4.4 Define negative scope**
Important! What should NOT activate the skill?
**4.5 Create precise description**
With all keywords identified, create ~200 word description that:
- Mentions domain
- Lists main keywords
- Gives examples
- Defines negative scope
**See** `references/phase4-detection.md` for complete guide.
### 🎯 3-Layer Activation System (v3.0)
**Important**: As of Agent-Skill-Creator v3.0, we now use a **3-Layer Activation System** to achieve 95%+ activation reliability.
#### Why 3 Layers?
Previous skills that relied only on description achieved ~70% activation reliability. The 3-layer system dramatically improves this to 95%+ by combining:
1. **Layer 1: Keywords** - Exact phrase matching (high precision)
2. **Layer 2: Patterns** - Regex flexible matching (coverage for variations)
3. **Layer 3: Description + NLU** - Claude's understanding (fallback for edge cases)
#### Quick Implementation Guide
**Layer 1: Keywords (10-15 phrases)**
```json
"activation": {
"keywords": [
"create an agent for",
"automate workflow",
"technical analysis for",
"RSI indicator",
// 10-15 total complete phrases
]
}
```
**Requirements:**
- ✅ Complete phrases (2+ words)
- ✅ Action verb + entity
- ✅ Domain-specific terms
- ❌ No single words
- ❌ No overly generic phrases
**Layer 2: Patterns (5-7 regex)**
```json
"patterns": [
"(?i)(create|build)\\s+(an?\\s+)?agent\\s+for",
"(?i)(automate|automation)\\s+(workflow|process)",
"(?i)(analyze|analysis)\\s+.*\\s+(stock|data)",
// 5-7 total patterns
]
```
**Requirements:**
- ✅ Start with `(?i)` for case-insensitivity
- ✅ Include action verbs + entities
- ✅ Allow flexible word order
- ✅ Specific enough to avoid false positives
- ✅ Flexible enough to capture variations
**Layer 3: Enhanced Description (300-500 chars, 60+ keywords)**
```
Comprehensive [domain] tool. [Primary capability] including [specific-feature-1],
[specific-feature-2], and [specific-feature-3]. Generates [output-type] based on
[method]. Compares [entity-type] for [analysis-type]. Monitors [target] and tracks
[metric]. Perfect for [user-persona] needing [use-case-1], [use-case-2], and
[use-case-3] using [methodology].
```
**Requirements:**
- ✅ 60+ unique keywords
- ✅ All Layer 1 keywords included naturally
- ✅ Domain-specific terminology
- ✅ Use cases clearly stated
- ✅ Natural language flow
#### Usage Sections
Add to marketplace.json:
```json
"usage": {
"when_to_use": [
"User explicitly asks to [capability-1]",
"User mentions [indicator-name] or [domain-term]",
"User describes [use-case-scenario]",
// 5+ use cases
],
"when_not_to_use": [
"User asks for [out-of-scope-1]",
"User wants [different-skill-capability]",
// 3+ counter-cases
]
}
```
#### Test Queries
Add to marketplace.json:
```json
"test_queries": [
"Query testing keyword-1",
"Query testing pattern-2",
"Query testing description understanding",
"Natural language variation",
// 10+ total queries covering all layers
]
```
#### Complete Example
See `references/examples/stock-analyzer-cskill/` for a complete working example demonstrating:
- All 3 layers properly configured
- 98% activation reliability
- Complete test suite
- Documentation with activation examples
#### Quality Checklist
Before completing Phase 4, verify:
- [ ] 10-15 complete keyword phrases defined
- [ ] 5-7 regex patterns with verbs + entities
- [ ] 300-500 char description with 60+ keywords
- [ ] 5+ when_to_use cases documented
- [ ] 3+ when_not_to_use cases documented
- [ ] 10+ test_queries covering all layers
- [ ] Tested activation with sample queries
- [ ] Expected success rate: 95%+
#### Additional Resources
- **Complete Guide**: `references/phase4-detection.md`
- **Pattern Library**: `references/activation-patterns-guide.md` (30+ reusable patterns)
- **Testing Guide**: `references/activation-testing-guide.md` (5-phase testing)
- **Quality Checklist**: `references/activation-quality-checklist.md`
- **Templates**: `references/templates/marketplace-robust-template.json`
- **Example**: `references/examples/stock-analyzer-cskill/`
---
## PHASE 5: Complete Implementation
**Objective**: IMPLEMENT everything with REAL code
### ⚠️ MANDATORY QUALITY STANDARDS
Before starting implementation, read `references/quality-standards.md`.
**NEVER DO**:
- ❌ `# TODO: implement`
- ❌ `pass` in functions
- ❌ "See external documentation"
- ❌ Configs with "YOUR_KEY_HERE" without instructions
- ❌ Empty references or just links
**ALWAYS DO**:
- ✅ Complete and functional code
- ✅ Detailed docstrings
- ✅ Robust error handling
- ✅ Type hints
- ✅ Validations
- ✅ Real content in references
- ✅ Configs with real values
### 🚨 STEP 0: BEFORE EVERYTHING - Marketplace.json (MANDATORY)
**STOP! READ THIS BEFORE CONTINUING!**
🛑 **CRITICAL BLOCKER**: You CANNOT create ANY other file until completing this step.
**Why marketplace.json is step 0:**
- ❌ Without this file, the skill CANNOT be installed via `/plugin marketplace add`
- ❌ All the work creating the agent will be USELESS without it
- ❌ This is the most common error when creating agents - DO NOT make this mistake!
#### Step 0.1: Create basic structure
```bash
mkdir -p agent-name/.claude-plugin
```
#### Step 0.2: Create marketplace.json IMMEDIATELY
Create `.claude-plugin/marketplace.json` with this content:
```json
{
"name": "agent-name",
"owner": {
"name": "Agent Creator",
"email": "noreply@example.com"
},
"metadata": {
"description": "Brief agent description",
"version": "1.0.0",
"created": "2025-10-17"
},
"plugins": [
{
"name": "agent-plugin",
"description": "THIS DESCRIPTION MUST BE IDENTICAL to the description in SKILL.md frontmatter that you'll create in the next step",
"source": "./",
"strict": false,
"skills": ["./"]
}
]
}
```
**⚠️ CRITICAL FIELDS:**
- `name`: Agent name (same as directory name)
- `plugins[0].description`: **MUST BE EXACTLY EQUAL** to SKILL.md frontmatter description
- `plugins[0].skills`: `["./"]` points to SKILL.md in root
- `plugins[0].source`: `"./"` points to agent root
#### Step 0.3: VALIDATE IMMEDIATELY (before continuing!)
**Execute NOW these validation commands:**
```bash
# 1. Validate JSON syntax
python3 -c "import json; print('✅ Valid JSON'); json.load(open('agent-name/.claude-plugin/marketplace.json'))"
# 2. Verify file exists
ls -la agent-name/.claude-plugin/marketplace.json
# If any command fails: STOP and fix before continuing!
```
**✅ CHECKLIST - You MUST complete ALL before proceeding:**
- [ ] ✅ File `.claude-plugin/marketplace.json` created
- [ ] ✅ JSON is syntactically valid (validated with python)
- [ ] ✅ Field `name` is correct
- [ ] ✅ Field `plugins[0].description` ready to receive SKILL.md description
- [ ] ✅ Field `plugins[0].skills` = `["./"]`
- [ ] ✅ Field `plugins[0].source` = `"./"`
**🛑 ONLY PROCEED AFTER VALIDATING ALL ITEMS ABOVE!**
---
### Implementation Order (AFTER marketplace.json validated)
Now that marketplace.json is created and validated, proceed:
**1. Create rest of directory structure**
```bash
mkdir -p agent-name/{scripts/utils,references,assets,data/{raw,processed,cache,analysis}}
```
**2. Create SKILL.md**
Mandatory structure:
- Frontmatter (name, description)
- When to use
- How it works (overview)
- Data source (detailed API)
- Workflows (step-by-step by question type)
- Available scripts (each explained)
- Available analyses (each explained)
- Error handling (all expected errors)
- Mandatory validations
- Performance and cache
- Keywords for detection
- Usage examples (5+ complete)
**Size**: 5000-7000 words
**⚠️ AFTER creating SKILL.md: SYNCHRONIZE description with marketplace.json!**
**CRITICAL**: Now that SKILL.md is created with its frontmatter, you MUST:
```bash
# Edit marketplace.json to update description
# Copy EXACTLY the description from SKILL.md frontmatter
# Paste in .claude-plugin/marketplace.json → plugins[0].description
```
**Verify synchronization:**
- SKILL.md frontmatter description = marketplace.json plugins[0].description
- Must be IDENTICAL (word for word!)
- Without this, skill won't activate automatically
**3. Implement Python scripts**
**Order** (MANDATORY):
1. **Utils first** (including helpers.py + validators/ - CRITICAL!)
- `utils/helpers.py` (🔴 MANDATORY - already specified previously)
- `utils/cache_manager.py`
- `utils/rate_limiter.py`
- `utils/validators/` (🔴 MANDATORY - see Step 3.5 below)
2. **Fetch** (API client - 1 method per API metric)
3. **Parse** (🔴 MODULAR: 1 parser per data type! - see Step 3.2 below)
4. **Analyze** (analyses - include comprehensive_report already specified!)
**Each script (in general)**:
- Shebang: `#!/usr/bin/env python3`
- Complete module docstring
- Organized imports
- Classes/functions with docstrings
- Type hints
- Error handling
- Logging
- Main function with argparse
- if __name__ == "__main__"
---
### Step 3.2: Modular Parser Architecture (🆕 Enhancement #5 - MANDATORY!)
**⚠️ COMMON PROBLEM:** v1.0 had 1 generic parser. When adding new data types, architecture broke.
**Solution:** **1 specific parser per API data type!**
**Rule:** If API returns N data types (identified in Phase 1.6) → create N specific parsers
**Mandatory structure:**
```
scripts/
├── parse_{type1}.py # Ex: parse_conditions.py
├── parse_{type2}.py # Ex: parse_progress.py
├── parse_{type3}.py # Ex: parse_yield.py
├── parse_{type4}.py # Ex: parse_production.py
└── parse_{type5}.py # Ex: parse_area.py
```
**Template for each parser:**
```python
#!/usr/bin/env python3
"""
Parser for {type} data from {API_name}.
Handles {type}-specific transformations and validations.
"""
import pandas as pd
from typing import List, Dict, Any, Optional
import logging
logger = logging.getLogger(__name__)
def parse_{type}_response(data: List[Dict]) -> pd.DataFrame:
"""
Parse API response for {type} data.
Args:
data: Raw API response (list of dicts)
Returns:
DataFrame with standardized schema:
- entity: str
- year: int
- {type}_value: float
- unit: str
- {type}_specific_fields: various
Raises:
ValueError: If data is invalid
ParseError: If parsing fails
Example:
>>> data = [{'entity': 'CORN', 'year': 2025, 'value': '15,300,000'}]
>>> df = parse_{type}_response(data)
>>> df.shape
(1, 5)
"""
if not data:
raise ValueError("Data cannot be empty")
# Convert to DataFrame
df = pd.DataFrame(data)
# {Type}-specific transformations
df = _clean_{type}_values(df)
df = _extract_{type}_metadata(df)
df = _standardize_{type}_schema(df)
# Validate
_validate_{type}_schema(df)
return df
def _clean_{type}_values(df: pd.DataFrame) -> pd.DataFrame:
"""Clean {type}-specific values (remove formatting, convert types)."""
# Example: Remove commas from numbers
if 'value' in df.columns:
df['value'] = df['value'].astype(str).str.replace(',', '')
df['value'] = pd.to_numeric(df['value'], errors='coerce')
# {Type}-specific cleaning
# ...
return df
def _extract_{type}_metadata(df: pd.DataFrame) -> pd.DataFrame:
"""Extract {type}-specific metadata fields."""
# Example for progress data: extract % from "75% PLANTED"
# Example for condition data: extract rating from "GOOD (60%)"
# Customize per data type!
return df
def _standardize_{type}_schema(df: pd.DataFrame) -> pd.DataFrame:
"""
Standardize column names and schema for {type} data.
Output schema:
- entity: str
- year: int
- {type}_value: float (main metric)
- unit: str
- additional_{type}_fields: various
"""
# Rename columns to standard names
column_mapping = {
'api_entity_field': 'entity',
'api_year_field': 'year',
'api_value_field': '{type}_value',
# Add more as needed
}
df = df.rename(columns=column_mapping)
# Ensure types
df['year'] = df['year'].astype(int)
df['{type}_value'] = pd.to_numeric(df['{type}_value'], errors='coerce')
return df
def _validate_{type}_schema(df: pd.DataFrame) -> None:
"""Validate {type} DataFrame schema."""
required_columns = ['entity', 'year', '{type}_value']
missing = set(required_columns) - set(df.columns)
if missing:
raise ValueError(f"Missing required columns: {missing}")
# Type validations
if not pd.api.types.is_integer_dtype(df['year']):
raise TypeError("'year' must be integer type")
if not pd.api.types.is_numeric_dtype(df['{type}_value']):
raise TypeError("'{type}_value' must be numeric type")
def aggregate_{type}(df: pd.DataFrame, by: str) -> pd.DataFrame:
"""
Aggregate {type} data by specified level.
Args:
df: Parsed {type} DataFrame
by: Aggregation level ('national', 'state', 'region')
Returns:
Aggregated DataFrame
Example:
>>> agg = aggregate_{type}(df, by='state')
"""
# Aggregation logic specific to {type}
if by == 'national':
return df.groupby(['year']).agg({
'{type}_value': 'sum',
# Add more as needed
}).reset_index()
elif by == 'state':
return df.groupby(['year', 'state']).agg({
'{type}_value': 'sum',
}).reset_index()
# Add more levels...
def format_{type}_report(df: pd.DataFrame) -> str:
"""
Format {type} data as human-readable report.
Args:
df: Parsed {type} DataFrame
Returns:
Formatted string report
Example:
>>> report = format_{type}_report(df)
>>> print(report)
"{Type} Report: ..."
"""
lines = [f"## {Type} Report\n"]
# Format based on {type} data
# Customize per type!
return "\n".join(lines)
def main():
"""Test parser with sample data."""
# Sample data for testing
sample_data = [
{
'entity': 'CORN',
'year': 2025,
'value': '15,300,000',
# Add {type}-specific fields
}
]
print("Testing parse_{type}_response()...")
df = parse_{type}_response(sample_data)
print(f"✓ Parsed {len(df)} records")
print(f"✓ Columns: {list(df.columns)}")
print(f"\n{df.head()}")
print("\nTesting aggregate_{type}()...")
agg = aggregate_{type}(df, by='national')
print(f"✓ Aggregated: {agg}")
print("\nTesting format_{type}_report()...")
report = format_{type}_report(df)
print(report)
if __name__ == "__main__":
main()
```
**Why create modular parsers:**
- ✅ Each data type has peculiarities (progress has %, yield has bu/acre, etc)
- ✅ Scalable architecture (easy to add new types)
- ✅ Isolated tests (each parser tested independently)
- ✅ Simple maintenance (bug in 1 type doesn't affect others)
- ✅ Organized code (clear responsibilities)
**Impact:** Professional and scalable architecture from v1.0!
---
### Step 3.5: Validation System (🆕 Enhancement #10 - MANDATORY!)
**⚠️ COMMON PROBLEM:** v1.0 without data validation. User doesn't know if data is reliable.
**Solution:** Complete validation system in `utils/validators/`
**Mandatory structure:**
```
scripts/utils/validators/
├── __init__.py
├── parameter_validator.py # Validate function parameters
├── data_validator.py # Validate API responses
├── temporal_validator.py # Validate temporal consistency
└── completeness_validator.py # Validate data completeness
```
**Template 1: parameter_validator.py**
```python
#!/usr/bin/env python3
"""
Parameter validators for {skill-name}.
Validates user inputs before making API calls.
"""
from typing import Any, List, Optional
from datetime import datetime
class ValidationError(Exception):
"""Raised when validation fails."""
pass
def validate_entity(entity: str, valid_entities: Optional[List[str]] = None) -> str:
"""
Validate entity parameter.
Args:
entity: Entity name (e.g., "CORN", "SOYBEANS")
valid_entities: List of valid entities (None to skip check)
Returns:
str: Validated and normalized entity name
Raises:
ValidationError: If entity is invalid
Example:
>>> validate_entity("corn")
"CORN" # Normalized to uppercase
"""
if not entity:
raise ValidationError("Entity cannot be empty")
if not isinstance(entity, str):
raise ValidationError(f"Entity must be string, got {type(entity)}")
# Normalize
entity = entity.strip().upper()
# Check if valid (if list provided)
if valid_entities and entity not in valid_entities:
suggestions = [e for e in valid_entities if entity[:3] in e]
raise ValidationError(
f"Invalid entity: {entity}\n"
f"Valid options: {', '.join(valid_entities[:10])}\n"
f"Did you mean: {', '.join(suggestions[:3])}?"
)
return entity
def validate_year(
year: Optional[int],
min_year: int = 1900,
allow_future: bool = False
) -> int:
"""
Validate year parameter.
Args:
year: Year to validate (None returns current year)
min_year: Minimum valid year
allow_future: Whether future years are allowed
Returns:
int: Validated year
Raises:
ValidationError: If year is invalid
Example:
>>> validate_year(2025)
2025
>>> validate_year(None)
2025 # Current year
"""
current_year = datetime.now().year
if year is None:
return current_year
if not isinstance(year, int):
raise ValidationError(f"Year must be integer, got {type(year)}")
if year < min_year:
raise ValidationError(
f"Year {year} is too old (minimum: {min_year})"
)
if not allow_future and year > current_year:
raise ValidationError(
f"Year {year} is in the future (current: {current_year})"
)
return year
def validate_state(state: str, country: str = "US") -> str:
"""Validate state/region parameter."""
# Country-specific validation
# ...
return state.upper()
# Add more validators for domain-specific parameters...
```
**Template 2: data_validator.py**
```python
#!/usr/bin/env python3
"""
Data validators for {skill-name}.
Validates API responses and analysis outputs.
"""
import pandas as pd
from typing import Dict, List, Any
from dataclasses import dataclass
from enum import Enum
class ValidationLevel(Enum):
"""Severity levels for validation results."""
CRITICAL = "critical" # Must fix
WARNING = "warning" # Should review
INFO = "info" # FYI
@dataclass
class ValidationResult:
"""Single validation check result."""
check_name: str
level: ValidationLevel
passed: bool
message: str
details: Optional[Dict] = None
class ValidationReport:
"""Collection of validation results."""
def __init__(self):
self.results: List[ValidationResult] = []
def add(self, result: ValidationResult):
"""Add validation result."""
self.results.append(result)
def has_critical_issues(self) -> bool:
"""Check if any critical issues found."""
return any(
r.level == ValidationLevel.CRITICAL and not r.passed
for r in self.results
)
def all_passed(self) -> bool:
"""Check if all validations passed."""
return all(r.passed for r in self.results)
def get_warnings(self) -> List[str]:
"""Get all warning messages."""
return [
r.message for r in self.results
if r.level == ValidationLevel.WARNING and not r.passed
]
def get_summary(self) -> str:
"""Get summary of validation results."""
total = len(self.results)
passed = sum(1 for r in self.results if r.passed)
critical = sum(
1 for r in self.results
if r.level == ValidationLevel.CRITICAL and not r.passed
)
return (
f"Validation: {passed}/{total} passed "
f"({critical} critical issues)"
)
class DataValidator:
"""Validates API responses and DataFrames."""
def validate_response(self, data: Any) -> ValidationReport:
"""
Validate raw API response.
Args:
data: Raw API response
Returns:
ValidationReport with results
"""
report = ValidationReport()
# Check 1: Not empty
report.add(ValidationResult(
check_name="not_empty",
level=ValidationLevel.CRITICAL,
passed=bool(data),
message="Data is empty" if not data else "Data present"
))
# Check 2: Correct type
expected_type = (list, dict)
is_correct_type = isinstance(data, expected_type)
report.add(ValidationResult(
check_name="correct_type",
level=ValidationLevel.CRITICAL,
passed=is_correct_type,
message=f"Expected {expected_type}, got {type(data)}"
))
# Check 3: Has expected structure
if isinstance(data, dict):
has_data_key = 'data' in data
report.add(ValidationResult(
check_name="has_data_key",
level=ValidationLevel.WARNING,
passed=has_data_key,
message="Response has 'data' key" if has_data_key else "No 'data' key"
))
return report
def validate_dataframe(self, df: pd.DataFrame, data_type: str) -> ValidationReport:
"""
Validate parsed DataFrame.
Args:
df: Parsed DataFrame
data_type: Type of data (for type-specific checks)
Returns:
ValidationReport
"""
report = ValidationReport()
# Check 1: Not empty
report.add(ValidationResult(
check_name="not_empty",
level=ValidationLevel.CRITICAL,
passed=len(df) > 0,
message=f"DataFrame has {len(df)} rows"
))
# Check 2: Required columns
required = ['entity', 'year'] # Customize per type
missing = set(required) - set(df.columns)
report.add(ValidationResult(
check_name="required_columns",
level=ValidationLevel.CRITICAL,
passed=len(missing) == 0,
message=f"Missing columns: {missing}" if missing else "All required columns present"
))
# Check 3: No excessive NaN values
if len(df) > 0:
nan_pct = (df.isna().sum() / len(df) * 100).max()
report.add(ValidationResult(
check_name="nan_threshold",
level=ValidationLevel.WARNING,
passed=nan_pct < 30,
message=f"Max NaN: {nan_pct:.1f}% ({'OK' if nan_pct < 30 else 'HIGH'})"
))
# Check 4: Data types correct
if 'year' in df.columns:
is_int = pd.api.types.is_integer_dtype(df['year'])
report.add(ValidationResult(
check_name="year_type",
level=ValidationLevel.CRITICAL,
passed=is_int,
message="'year' is integer" if is_int else "'year' is not integer"
))
return report
def validate_{type}_output(result: Dict) -> ValidationReport:
"""
Validate analysis output for {type}.
Args:
result: Analysis result dict
Returns:
ValidationReport
"""
report = ValidationReport()
# Check required keys
required_keys = ['year', 'year_info', 'data']
for key in required_keys:
report.add(ValidationResult(
check_name=f"has_{key}",
level=ValidationLevel.CRITICAL,
passed=key in result,
message=f"'{key}' present" if key in result else f"Missing '{key}'"
))
# Check data quality
if 'data' in result and result['data']:
report.add(ValidationResult(
check_name="data_not_empty",
level=ValidationLevel.CRITICAL,
passed=True,
message="Data is present"
))
return report
# Main for testing
if __name__ == "__main__":
print("Testing validators...")
# Test entity validator
print("\n1. Testing validate_entity():")
try:
entity = validate_entity("corn", ["CORN", "SOYBEANS"])
print(f" ✓ Valid: {entity}")
except ValidationError as e:
print(f" ✗ Error: {e}")
# Test year validator
print("\n2. Testing validate_year():")
year = validate_year(2025)
print(f" ✓ Valid: {year}")
# Test DataValidator
print("\n3. Testing DataValidator:")
validator = DataValidator()
sample_data = [{'entity': 'CORN', 'year': 2025}]
report = validator.validate_response(sample_data)
print(f" {report.get_summary()}")
```
**Template 3: temporal_validator.py**
```python
#!/usr/bin/env python3
"""
Temporal validators for {skill-name}.
Checks temporal consistency and data age.
"""
import pandas as pd
from datetime import datetime, timedelta
from typing import List
from .data_validator import ValidationResult, ValidationReport, ValidationLevel
def validate_temporal_consistency(df: pd.DataFrame) -> ValidationReport:
"""
Check temporal consistency in data.
Validations:
- No future dates
- Years in valid range
- No suspicious gaps in time series
- Data age is acceptable
Args:
df: DataFrame with 'year' column
Returns:
ValidationReport
"""
report = ValidationReport()
current_year = datetime.now().year
if 'year' not in df.columns:
report.add(ValidationResult(
check_name="has_year_column",
level=ValidationLevel.CRITICAL,
passed=False,
message="Missing 'year' column"
))
return report
# Check 1: No future years
max_year = df['year'].max()
report.add(ValidationResult(
check_name="no_future_years",
level=ValidationLevel.CRITICAL,
passed=max_year <= current_year,
message=f"Max year: {max_year} ({'valid' if max_year <= current_year else 'FUTURE!'})"
))
# Check 2: Years in reasonable range
min_year = df['year'].min()
is_reasonable = min_year >= 1900
report.add(ValidationResult(
check_name="reasonable_year_range",
level=ValidationLevel.WARNING,
passed=is_reasonable,
message=f"Year range: {min_year}-{max_year}"
))
# Check 3: Data age (is data recent enough?)
data_age_years = current_year - max_year
is_recent = data_age_years <= 2
report.add(ValidationResult(
check_name="data_freshness",
level=ValidationLevel.WARNING,
passed=is_recent,
message=f"Data age: {data_age_years} years ({'recent' if is_recent else 'STALE'})"
))
# Check 4: No suspicious gaps in time series
if len(df['year'].unique()) > 2:
years_sorted = sorted(df['year'].unique())
gaps = [
years_sorted[i+1] - years_sorted[i]
for i in range(len(years_sorted)-1)
]
max_gap = max(gaps) if gaps else 0
has_large_gap = max_gap > 2
report.add(ValidationResult(
check_name="no_large_gaps",
level=ValidationLevel.WARNING,
passed=not has_large_gap,
message=f"Max gap: {max_gap} years" + (" (suspicious)" if has_large_gap else "")
))
return report
def validate_week_number(week: int, year: int) -> ValidationResult:
"""Validate week number is in valid range for year."""
# Most data types use weeks 1-53
is_valid = 1 <= week <= 53
return ValidationResult(
check_name="valid_week",
level=ValidationLevel.CRITICAL,
passed=is_valid,
message=f"Week {week} ({'valid' if is_valid else 'INVALID: must be 1-53'})"
)
# Add more temporal validators as needed...
```
**Template 4: completeness_validator.py**
```python
#!/usr/bin/env python3
"""
Completeness validators for {skill-name}.
Checks data completeness and coverage.
"""
import pandas as pd
from typing import List, Set
from .data_validator import ValidationResult, ValidationReport, ValidationLevel
def validate_completeness(
df: pd.DataFrame,
expected_entities: Optional[List[str]] = None,
expected_years: Optional[List[int]] = None
) -> ValidationReport:
"""
Validate data completeness.
Args:
df: DataFrame to validate
expected_entities: Expected entities (None to skip)
expected_years: Expected years (None to skip)
Returns:
ValidationReport
"""
report = ValidationReport()
# Check 1: All expected entities present
if expected_entities:
actual_entities = set(df['entity'].unique())
expected_set = set(expected_entities)
missing = expected_set - actual_entities
report.add(ValidationResult(
check_name="all_entities_present",
level=ValidationLevel.WARNING,
passed=len(missing) == 0,
message=f"Missing entities: {missing}" if missing else "All entities present",
details={'missing': list(missing)}
))
# Check 2: All expected years present
if expected_years:
actual_years = set(df['year'].unique())
expected_set = set(expected_years)
missing = expected_set - actual_years
report.add(ValidationResult(
check_name="all_years_present",
level=ValidationLevel.WARNING,
passed=len(missing) == 0,
message=f"Missing years: {missing}" if missing else "All years present"
))
# Check 3: No excessive nulls in critical columns
critical_columns = ['entity', 'year'] # Customize
for col in critical_columns:
if col in df.columns:
null_count = df[col].isna().sum()
report.add(ValidationResult(
check_name=f"{col}_no_nulls",
level=ValidationLevel.CRITICAL,
passed=null_count == 0,
message=f"'{col}' has {null_count} nulls"
))
# Check 4: Coverage percentage
if expected_entities and expected_years:
expected_total = len(expected_entities) * len(expected_years)
actual_total = len(df)
coverage_pct = (actual_total / expected_total) * 100 if expected_total > 0 else 0
report.add(ValidationResult(
check_name="coverage_percentage",
level=ValidationLevel.INFO,
passed=coverage_pct >= 80,
message=f"Coverage: {coverage_pct:.1f}% ({actual_total}/{expected_total})"
))
return report
```
**Integration in analysis functions:**
```python
def {analysis_function}(entity: str, year: Optional[int] = None, ...) -> Dict:
"""Analysis function with validation."""
from utils.validators.parameter_validator import validate_entity, validate_year
from utils.validators.data_validator import DataValidator
from utils.validators.temporal_validator import validate_temporal_consistency
# VALIDATE INPUTS (before doing anything!)
entity = validate_entity(entity, valid_entities=[...])
year = validate_year(year)
# Fetch data
data = fetch_{metric}(entity, year)
# VALIDATE API RESPONSE
validator = DataValidator()
response_validation = validator.validate_response(data)
if response_validation.has_critical_issues():
raise DataQualityError(
f"API response validation failed: {response_validation.get_summary()}"
)
# Parse
df = parse_{type}(data)
# VALIDATE PARSED DATA
df_validation = validator.validate_dataframe(df, '{type}')
temporal_validation = validate_temporal_consistency(df)
if df_validation.has_critical_issues():
raise DataQualityError(
f"Data validation failed: {df_validation.get_summary()}"
)
# Analyze
results = analyze(df)
# Return with validation info
return {
'data': results,
'year': year,
'year_info': format_year_message(year, year_requested),
'validation': {
'passed': df_validation.all_passed(),
'warnings': df_validation.get_warnings(),
'report': df_validation.get_summary()
}
}
```
**Impact:**
- ✅ Reliable data (validated at multiple layers)
- ✅ Transparency (user sees validation report)
- ✅ Clear error messages (not just "generic error")
- ✅ Problem detection (gaps, nulls, inconsistencies)
---
**4. Write references**
For each reference file:
- 1000-2000 words
- Useful content (examples, methodologies, guides)
- Well structured (headings, lists, code blocks)
- Well-formatted markdown
**5. Create assets**
- Syntactically valid JSONs
- Real values with comments
- Logical structure
**6. Write README.md**
- Step-by-step installation
- Required configuration
- Usage examples
- Troubleshooting
**7. Create DECISIONS.md**
Document all decisions made:
- Which API chosen and why
- Which analyses defined and justification
- Structure chosen and rationale
- Trade-offs considered
**8. Create VERSION and CHANGELOG.md** (🆕 Enhancement #7 - Versioning)
**8.1 Create VERSION file:**
```
1.0.0
```
**8.2 Create CHANGELOG.md:**
```markdown
# Changelog
All notable changes to {skill-name} will be documented here.
Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
Versioning follows [Semantic Versioning](https://semver.org/).
## [1.0.0] - {current_date}
### Added
**Core Functionality:**
- {function1}: {Description of what it does}
- {function2}: {Description of what it does}
- {function3}: {Description of what it does}
...
**Data Sources:**
- {API_name}: {Coverage description}
- Authentication: {auth_method}
- Rate limit: {limit}
**Analysis Capabilities:**
- {analysis1}: {Description and methodology}
- {analysis2}: {Description and methodology}
...
**Utilities:**
- Cache system with {TTL} TTL
- Rate limiting: {limit} per {period}
- Error handling with automatic retries
- Data validation and quality checks
### Data Coverage
**Metrics implemented:**
- {metric1}: {Coverage details}
- {metric2}: {Coverage details}
...
**Geographic coverage:** {geo_coverage}
**Temporal coverage:** {temporal_coverage}
### Known Limitations
- {limitation1}
- {limitation2}
...
### Planned for v2.0
- {planned_feature1}
- {planned_feature2}
...
## [Unreleased]
### Planned
- Add support for {feature}
- Improve performance for {scenario}
- Expand coverage to {new_area}
```
**8.3 Update marketplace.json with version:**
Edit `.claude-plugin/marketplace.json` to include:
```json
{
"metadata": {
"description": "...",
"version": "1.0.0",
"created": "{current_date}",
"updated": "{current_date}"
}
}
```
**8.4 Create .bumpversion.cfg (optional):**
If you want version automation:
```ini
[bumpversion]
current_version = 1.0.0
commit = False
tag = False
[bumpversion:file:VERSION]
[bumpversion:file:.claude-plugin/marketplace.json]
search = "version": "{current_version}"
replace = "version": "{new_version}"
[bumpversion:file:CHANGELOG.md]
search = ## [Unreleased]
replace = ## [Unreleased]
## [{new_version}] - {now:%Y-%m-%d}
```
**Impact:**
- ✅ Change traceability
- ✅ Professionalism
- ✅ Facilitates future updates
- ✅ Users know what changed between versions
**9. Create INSTALLATION.md** (Didactic Tutorial)
[Content of INSTALLATION.md as previously specified]
### Practical Implementation
**Create agent in subdirectory**:
```bash
# Agent name based on domain/objective
agent_name="nass-usda-agriculture" # example
# Create structure
mkdir -p $agent_name/{scripts/utils,references,assets,data}
# Implement each file
# [Claude creates each file with Write tool]
```
**At the end, inform user**:
```
✅ Agent created in ./{agent_name}/
📁 Structure:
- .claude-plugin/marketplace.json ✅ (installation + version)
- SKILL.md (6,200 words)
- scripts/ (2,500+ lines of code)
├─ utils/helpers.py ✅ (temporal context)
├─ utils/validators/ ✅ (4 validators, ~800 lines)
├─ parse_{type}*.py ✅ (1 per data type, modular)
└─ comprehensive_{domain}_report() ✅
- tests/ (25+ tests, ~800 lines) ✅
├─ test_integration.py (end-to-end)
├─ test_parse.py (all parsers)
├─ test_helpers.py (temporal)
└─ test_validation.py (validators)
- references/ (5,000 words)
- assets/ (2 configs)
- README.md (1,000+ words with Testing section)
- INSTALLATION.md (1,500 words) ✅
- DECISIONS.md (justifications)
- VERSION (1.0.0) ✅
- CHANGELOG.md (release notes) ✅
🚀 To install:
/plugin marketplace add ./{agent_name}
💡 Usage examples:
"[example 1]"
"[example 2]"
```
**See** `references/phase5-implementation.md` for complete implementation guide.
## Complete Flow: Step-by-Step
### User Input
User describes workflow/objective:
```
"Every day I download US crop data from USDA,
compare current year vs previous, create state ranking
by production, and generate report. Takes 2 hours.
Automate this."
```
### Autonomous Execution
**Claude executes internally** (doesn't need to show everything):
**PHASE 1**: Discovery (~5-10 min)
```
[WebSearch: "USDA API free agriculture data"]
[WebFetch: NASS API docs]
[Compare: NASS vs ERS vs FAO]
→ DECISION: NASS QuickStats API
Justification: Free, data since 1866, all crops, state-level
```
**PHASE 2**: Design (~5 min)
```
[Analyze: "compare years", "state ranking", "generate report"]
→ DEFINE analyses:
1. YoY comparison (compare years)
2. State ranking (state ranking)
3. Trend analysis (if user asks for trends)
4. Report generator (generate report)
```
**PHASE 3**: Architecture (~5 min)
```
→ STRUCTURE:
scripts/
- fetch_nass.py (API requests)
- parse_nass.py (parsing)
- analyze_nass.py (YoY, ranking, trends)
- generate_report.py (report)
utils/
- cache_manager.py
- rate_limiter.py
references/
- nass-api-guide.md
- analysis-methods.md
- report-templates.md
assets/
- config.json
- metadata.json
```
**PHASE 4**: Detection (~2 min)
```
→ KEYWORDS:
Entities: USDA, NASS, agriculture, crops
Commodities: corn, soybeans, wheat
Metrics: production, area, yield
Actions: compare, ranking, trend
Geography: US, states, Iowa, Illinois
→ DESCRIPTION: "This skill should be used when user
asks about US agriculture, production, area,
crop yield..."
```
**PHASE 5**: Implementation (~45 min)
```
[Write: SKILL.md] ✅ 6,000 words
[Write: fetch_nass.py] ✅ 280 lines
[Write: parse_nass.py] ✅ 180 lines
[Write: analyze_nass.py] ✅ 520 lines
[Write: generate_report.py] ✅ 200 lines
[Write: utils/cache_manager.py] ✅ 120 lines
[Write: utils/rate_limiter.py] ✅ 110 lines
[Write: references/nass-api-guide.md] ✅ 1,500 words
[Write: references/analysis-methods.md] ✅ 2,000 words
[Write: references/report-templates.md] ✅ 1,000 words
[Write: assets/config.json] ✅
[Write: assets/metadata.json] ✅
[Write: README.md] ✅ 800 words
[Write: DECISIONS.md] ✅ 600 words
```
### User Output
```
✅ Agent created: ./usda-agriculture-agent/
📊 Technical Decisions:
- API: USDA NASS QuickStats (free, data since 1866)
- Analyses: YoY, Ranking, Trends, Report Generation
- Structure: 4 main scripts + 2 utils
- Cache: Historical permanent, current 7 days
📁 Files Created:
- SKILL.md: 6,000 words
- Python code: 2,500+ lines
├─ Modular parsers (1 per type)
├─ Validation system (800 lines)
├─ Temporal helpers
└─ comprehensive_report()
- Tests: 25+ tests (800 lines)
- References: 4,500 words
- Configs: 2 files
- README: Complete (with Testing)
- INSTALLATION.md: Didactic tutorial
- VERSION: 1.0.0
- CHANGELOG.md: Complete release notes
🎯 Estimated Savings:
- Before: 2 hours/day
- After: 3 minutes/day
- Savings: 98.5% (117h/month → 1.5h/month)
🚀 To install and use:
# 1. Get API key (free):
Visit: https://quickstats.nass.usda.gov/api#registration
# 2. Configure:
export NASS_API_KEY="your_key_here"
# 3. Install skill:
/plugin marketplace add ./usda-agriculture-agent
# 4. Use (examples):
"US corn production in 2023"
"Compare soybeans this year vs last year"
"Ranking of wheat producing states"
"Generate current crop report"
```
## Detailed References
For details of each phase, load references:
- `references/phase1-discovery.md`: API research and decision
- `references/phase2-design.md`: Analysis definition
- `references/phase3-architecture.md`: Project structuring
- `references/phase4-detection.md`: Keywords and automatic activation
- `references/phase5-implementation.md`: Code implementation
- `references/quality-standards.md`: Mandatory standards
- `references/examples.md`: Complete examples of created agents
## Meta-Skill Usage Examples
### Example 1: Simple Workflow
```
👤 "Automate: download weather data, calculate averages,
generate chart. I do this every week, takes 1h."
🤖 [Activates agent-creator]
[Phase 1]: Research → NOAA API
[Phase 2]: Defines → Download, Aggregation, Visualization
[Phase 3]: Structure → 3 scripts + 2 utils
[Phase 4]: Keywords → weather, climate, temperature, NOAA
[Phase 5]: Implements everything
✅ Agent created: ./weather-analysis-agent/
[Installation instructions]
```
### Example 2: Complex Workflow
```
👤 "I need an agent for stock financial analysis:
fetch prices, calculate technical indicators (RSI, MACD),
compare with benchmarks, generate alerts. Daily, 3h."
🤖 [Activates agent-creator]
[Phase 1]: Research → Alpha Vantage API (or Yahoo Finance)
[Phase 2]: Defines → Price fetching, Technical indicators,
Benchmark comparison, Alert system
[Phase 3]: Structure → 5 scripts + 4 utils
[Phase 4]: Keywords → stock, RSI, MACD, technical analysis
[Phase 5]: Implements
✅ Agent created: ./stock-technical-analysis-agent/
```
### Example 3: Just Vague Description
```
👤 "Create an agent for Brazilian agriculture"
🤖 [Activates agent-creator]
"Got it! I'll create an agent for Brazilian agriculture.
A few quick questions:
- Focus on which crops? (soy, corn, coffee, all?)
- Desired analyses? (production, prices, exports?)
- Preferred source? (CONAB, IBGE, both?)
Or I can decide based on most common use cases
(grain production via CONAB). Prefer I decide?"
👤 "You decide, focus on grain production."
🤖 [Phase 1]: CONAB Grain Survey
[Phase 2]: YoY, Ranking, Regional, Trends
[Phase 3-5]: Creates everything
✅ Agent created: ./conab-agriculture-agent/
```
---
## PHASE 6: Test Suite Generation (🆕 Enhancement #4 - MANDATORY!)
**Objective**: Generate comprehensive test suite that validates ALL functions
**⚠️ COMMON PROBLEM:** v1.0 without tests. Difficult to validate code works, impossible to do regression testing.
**Solution:** Automatically generate 25+ tests covering all layers!
### Test Structure
```
tests/
├── __init__.py
├── test_fetch.py # Test API fetch functions
├── test_parse.py # Test each parser
├── test_analyze.py # Test analysis functions
├── test_integration.py # End-to-end tests
├── test_validation.py # Test validators
├── test_helpers.py # Test temporal helpers
└── conftest.py # Shared fixtures (pytest)
```
### Template 1: test_integration.py (MAIN!)
```python
#!/usr/bin/env python3
"""
Integration tests for {skill-name}.
Tests complete workflows from query to result.
"""
import sys
from pathlib import Path
# Add scripts to path
sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts'))
from analyze_{domain} import (
{function1},
{function2},
{function3},
comprehensive_{domain}_report
)
def test_{function1}_basic():
"""Test {function1} with auto-year detection."""
print(f"\n✓ Testing {function1}()...")
try:
# Test auto-year detection (year=None)
result = {function1}('{example_entity}')
# Validations
assert 'year' in result, "Missing 'year' in result"
assert 'year_info' in result, "Missing 'year_info'"
assert 'data' in result, "Missing 'data'"
assert result['year'] >= 2024, f"Year too old: {result['year']}"
print(f" ✓ Auto-year working: {result['year']}")
print(f" ✓ Year info: {result['year_info']}")
print(f" ✓ Data present: {len(result.get('data', {}))} fields")
return True
except Exception as e:
print(f" ✗ FAILED: {e}")
import traceback
traceback.print_exc()
return False
def test_{function1}_specific_year():
"""Test {function1} with specific year."""
print(f"\n✓ Testing {function1}(year=2024)...")
try:
result = {function1}('{example_entity}', year=2024)
assert result['year'] == 2024, "Requested year not used"
assert result['year_requested'] == 2024, "year_requested not tracked"
print(f" ✓ Specific year working: {result['year']}")
return True
except Exception as e:
print(f" ✗ FAILED: {e}")
return False
def test_{function2}_comparison():
"""Test {function2} (comparison function)."""
print(f"\n✓ Testing {function2}()...")
try:
result = {function2}('{example_entity}', year1=2024, year2=2023)
# Validations specific to comparison
assert 'change_percent' in result, "Missing 'change_percent'"
assert isinstance(result['change_percent'], (int, float)), "change_percent not numeric"
print(f" ✓ Comparison working: {result.get('change_percent')}% change")
return True
except Exception as e:
print(f" ✗ FAILED: {e}")
return False
def test_comprehensive_report():
"""Test comprehensive report (all-in-one function)."""
print(f"\n✓ Testing comprehensive_{domain}_report()...")
try:
result = comprehensive_{domain}_report('{example_entity}')
# Validations
assert 'metrics' in result, "Missing 'metrics'"
assert 'summary' in result, "Missing 'summary'"
assert 'alerts' in result, "Missing 'alerts'"
assert isinstance(result['metrics'], dict), "'metrics' must be dict"
metrics_count = len(result['metrics'])
print(f" ✓ Comprehensive report working")
print(f" ✓ Metrics combined: {metrics_count}")
print(f" ✓ Summary: {result['summary'][:100]}...")
print(f" ✓ Alerts: {len(result['alerts'])}")
return True
except Exception as e:
print(f" ✗ FAILED: {e}")
return False
def test_validation_integration():
"""Test that validation is integrated in functions."""
print(f"\n✓ Testing validation integration...")
try:
result = {function1}('{example_entity}')
# Check validation info is present
assert 'validation' in result, "Missing 'validation' info"
assert 'passed' in result['validation'], "Missing validation.passed"
assert 'report' in result['validation'], "Missing validation.report"
print(f" ✓ Validation present: {result['validation']['report']}")
return True
except Exception as e:
print(f" ✗ FAILED: {e}")
return False
def main():
"""Run all integration tests."""
print("=" * 70)
print("INTEGRATION TESTS - {skill-name}")
print("=" * 70)
tests = [
("Auto-year detection", test_{function1}_basic),
("Specific year", test_{function1}_specific_year),
("Comparison function", test_{function2}_comparison),
("Comprehensive report", test_comprehensive_report),
("Validation integration", test_validation_integration),
]
results = []
for test_name, test_func in tests:
passed = test_func()
results.append((test_name, passed))
# Summary
print("\n" + "=" * 70)
print("SUMMARY")
print("=" * 70)
for test_name, passed in results:
status = "✅ PASS" if passed else "❌ FAIL"
print(f"{status}: {test_name}")
passed_count = sum(1 for _, p in results if p)
total_count = len(results)
print(f"\nResults: {passed_count}/{total_count} passed")
return passed_count == total_count
if __name__ == "__main__":
success = main()
sys.exit(0 if success else 1)
```
### Template 2: test_parse.py
```python
#!/usr/bin/env python3
"""Tests for parsers."""
import sys
from pathlib import Path
import pandas as pd
sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts'))
from parse_{type1} import parse_{type1}_response
from parse_{type2} import parse_{type2}_response
# Import all parsers...
def test_parse_{type1}():
"""Test {type1} parser."""
print("\n✓ Testing parse_{type1}_response()...")
sample_data = [
{'{field1}': 'VALUE1', '{field2}': 2025, '{field3}': '1,234,567'}
]
try:
df = parse_{type1}_response(sample_data)
# Validations
assert isinstance(df, pd.DataFrame), "Must return DataFrame"
assert len(df) == 1, f"Expected 1 row, got {len(df)}"
assert 'entity' in df.columns, "Missing 'entity' column"
assert 'year' in df.columns, "Missing 'year' column"
print(f" ✓ Parsed: {len(df)} records")
print(f" ✓ Columns: {list(df.columns)}")
return True
except Exception as e:
print(f" ✗ FAILED: {e}")
return False
# Repeat for all parsers...
def main():
"""Run parser tests."""
tests = [
test_parse_{type1},
test_parse_{type2},
# Add all...
]
passed = sum(1 for test in tests if test())
print(f"\nResults: {passed}/{len(tests)} passed")
return passed == len(tests)
if __name__ == "__main__":
sys.exit(0 if main() else 1)
```
### Template 3: test_helpers.py
```python
#!/usr/bin/env python3
"""Tests for temporal helpers."""
import sys
from pathlib import Path
from datetime import datetime
sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts'))
from utils.helpers import (
get_current_{domain}_year,
get_{domain}_year_with_fallback,
should_try_previous_year,
format_year_message
)
def test_get_current_year():
"""Test current year detection."""
year = get_current_{domain}_year()
current = datetime.now().year
assert year == current, f"Expected {current}, got {year}"
print(f"✓ Current year: {year}")
return True
def test_year_with_fallback():
"""Test year fallback logic."""
primary, fallback = get_{domain}_year_with_fallback(2024)
assert primary == 2024, "Primary should be 2024"
assert fallback == 2023, "Fallback should be 2023"
print(f"✓ Fallback: {primary} → {fallback}")
return True
def test_format_year_message():
"""Test year message formatting."""
msg = format_year_message(2024, 2025)
assert '2024' in msg, "Must mention year used"
assert '2025' in msg, "Must mention year requested"
print(f"✓ Message: {msg}")
return True
def main():
"""Run helper tests."""
tests = [
test_get_current_year,
test_year_with_fallback,
test_format_year_message
]
passed = sum(1 for test in tests if test())
print(f"\nResults: {passed}/{len(tests)} passed")
return passed == len(tests)
if __name__ == "__main__":
sys.exit(0 if main() else 1)
```
### Minimum Test Coverage
**For skill to be considered complete, needs:**
- [ ] test_integration.py with ≥5 end-to-end tests
- [ ] test_parse.py with 1 test per parser
- [ ] test_analyze.py with 1 test per analysis function
- [ ] test_helpers.py with ≥3 tests
- [ ] test_validation.py with ≥5 tests
- [ ] **Total:** ≥25 tests
- [ ] **Coverage:** ≥80% of code
- [ ] **All tests PASS**
### How to test
Include in README.md:
```markdown
## Testing
### Run All Tests
```bash
cd {skill-name}
python3 tests/test_integration.py
```
### Run Specific Tests
```bash
python3 tests/test_parse.py
python3 tests/test_helpers.py
python3 tests/test_validation.py
```
### Expected Output
```
======================================================================
INTEGRATION TESTS - {skill-name}
======================================================================
✓ Testing {function1}()...
✓ Auto-year working: 2025
✓ Data present: 8 fields
✓ Testing {function2}()...
✓ Comparison working: +12.3% change
...
======================================================================
SUMMARY
======================================================================
✅ PASS: Auto-year detection
✅ PASS: Specific year
✅ PASS: Comparison function
✅ PASS: Comprehensive report
✅ PASS: Validation integration
Results: 5/5 passed
```
```
### Test Suite Benefits
- ✅ Reliability: Tested and working code
- ✅ Regression testing: Detects breaks when modifying
- ✅ Executable documentation: Tests show how to use
- ✅ CI/CD ready: Can run automatically
- ✅ Professionalism: Production-quality skills
**Impact:** Generated skills are tested and reliable from v1.0!
---
## Agent Creation Workflow: Checklist
When creating an agent, follow this checklist RIGOROUSLY in order:
---
### 🚨 STEP 0: MANDATORY - FIRST STEP
**Execute BEFORE anything else:**
- [ ] 🚨 Create `.claude-plugin/marketplace.json`
- [ ] 🚨 Validate JSON syntax with python
- [ ] 🚨 Verify mandatory fields filled
- [ ] 🚨 Confirm: "Marketplace.json created and validated - can proceed"
**🛑 DO NOT PROCEED without completing ALL items above!**
---
### ✅ Phase 1-4: Planning
- [ ] Domain identified
- [ ] API researched and decided (with justification)
- [ ] **API completeness analysis** (Phase 1.6 - coverage ≥50%)
- [ ] Analyses defined (4-6 main + comprehensive_report)
- [ ] Structure planned (modular parsers, validators/)
- [ ] Keywords determined (≥60 unique)
---
### ✅ Phase 5: Implementation
- [ ] .claude-plugin/marketplace.json created FIRST
- [ ] marketplace.json validated (syntax + fields)
- [ ] SKILL.md created with correct frontmatter
- [ ] **CRITICAL:** SKILL.md description copied to marketplace.json → plugins[0].description (IDENTICAL!)
- [ ] Validate synchronization: SKILL.md description === marketplace.json
- [ ] **MANDATORY:** utils/helpers.py created (temporal context)
- [ ] **MANDATORY:** utils/validators/ created (4 validators)
- [ ] **MANDATORY:** Modular parsers (1 per data type)
- [ ] **MANDATORY:** comprehensive_{domain}_report() implemented
- [ ] DECISIONS.md documenting choices
- [ ] VERSION file created (e.g., 1.0.0)
- [ ] CHANGELOG.md created with complete v1.0.0 entry
- [ ] marketplace.json with version field
- [ ] Implement functional code (no TODOs)
- [ ] Write complete docstrings
- [ ] Add error handling
- [ ] Write references with useful content
- [ ] Create real configs
- [ ] Write complete README
- [ ] INSTALLATION.md with complete tutorial
---
### ✅ Phase 6: Test Suite
- [ ] tests/ directory created
- [ ] test_integration.py with ≥5 end-to-end tests
- [ ] test_parse.py with 1 test per parser
- [ ] test_analyze.py with 1 test per analysis function
- [ ] test_helpers.py with ≥3 tests
- [ ] test_validation.py with ≥5 tests
- [ ] **Total:** ≥25 tests implemented
- [ ] **ALL tests PASS** (execute and validate!)
- [ ] "Testing" section added to README.md
---
### ✅ Final Validation
- [ ] Validate marketplace.json again (syntax + synchronized description)
- [ ] Validate other JSONs (configs, assets)
- [ ] Verify imports work
- [ ] Check no placeholder/TODO
- [ ] Test main logic manually
- [ ] Verify README has all instructions
- [ ] Calculate estimated ROI (time before vs after)
---
### 🚀 MANDATORY TEST - DO NOT SKIP THIS STEP!
**Execute this command MANDATORY before delivering:**
```bash
cd /path/to/skills
/plugin marketplace add ./agent-name
```
**Verifications:**
- [ ] ✅ Command executed without errors
- [ ] ✅ Skill appears in installed plugins list
- [ ] ✅ Claude recognizes the skill (do test question)
**🛑 If test fails:**
1. Verify marketplace.json exists
2. Verify JSON is valid
3. Verify description is synchronized
4. Fix and test again
**Only deliver to user AFTER installation test passes!**
---
### ✅ Deliver to User
- [ ] Show created structure
- [ ] Summarize main decisions
- [ ] List files and sizes
- [ ] Give installation instructions (command tested above)
- [ ] Give 3-5 usage examples
- [ ] Inform estimated ROI
- [ ] **Confirm: "Skill tested and installed successfully"**
## User Communication
### During Creation
**Show high-level progress**:
```
🔍 Phase 1: Researching APIs...
✓ 5 options found
✓ Decided: NASS API (free, complete data)
🎨 Phase 2: Defining analyses...
✓ 15 typical questions identified
✓ 5 main analyses defined
🏗️ Phase 3: Structuring project...
✓ 3 scripts + 2 utils planned
🎯 Phase 4: Defining detection...
✓ 50+ keywords identified
⚙️ Phase 5: Implementing code...
[Progress while creating files]
✓ SKILL.md (6,200 words)
✓ fetch_nass.py (280 lines)
✓ parse_nass.py (180 lines)
[...]
```
**Don't show**: Technical details during creation (code blocks, etc). Just progress.
### After Completion
**Executive summary**:
```
✅ AGENT CREATED SUCCESSFULLY!
📂 Location: ./usda-agriculture-agent/
📊 Main Decisions:
- API: USDA NASS QuickStats
- Analyses: YoY, Ranking, Trends, Reports
- Implementation: 1,410 lines Python + 4,500 words docs
💰 Estimated ROI:
- Time before: 2h/day
- Time after: 3min/day
- Savings: 117h/month
🎓 See DECISIONS.md for complete justifications.
🚀 NEXT STEPS:
1. Get API key (free):
https://quickstats.nass.usda.gov/api#registration
2. Configure:
export NASS_API_KEY="your_key"
3. Install:
/plugin marketplace add ./usda-agriculture-agent
4. Test:
"US corn production in 2023"
"Compare soybeans this year vs last year"
See README.md for complete instructions.
```
## Keywords for This Meta-Skill Detection
This meta-skill (agent-creator) is activated when user mentions:
**Create/Develop**:
- "Create an agent"
- "Develop agent"
- "Create skill"
- "Develop skill"
- "Build agent"
**Automate**:
- "Automate this workflow"
- "Automate this process"
- "Automate this task"
- "Need to automate"
- "Turn into agent"
**Repetitive Workflow**:
- "Every day I do"
- "Repeatedly need to"
- "Manual process"
- "Workflow that takes Xh"
- "Task I repeat"
**Agent for Domain**:
- "Agent for [domain]"
- "Custom skill for [domain]"
- "Specialize Claude in [domain]"
## ⚠️ Troubleshooting: Common Marketplace.json Errors
### Error: "Failed to install plugin"
**Most common cause:** marketplace.json doesn't exist or is poorly formatted
**Diagnosis:**
```bash
# 1. Verify file exists
ls -la agent-name/.claude-plugin/marketplace.json
# 2. Validate JSON
python3 -c "import json; json.load(open('agent-name/.claude-plugin/marketplace.json'))"
# 3. View content
cat agent-name/.claude-plugin/marketplace.json
```
**Solutions:**
1. If file doesn't exist: Go back to STEP 0 and create
2. If invalid JSON: Fix syntax errors
3. If missing fields: Compare with STEP 0 template
### Error: "Skill not activating"
**Cause:** marketplace.json description ≠ SKILL.md description
**Diagnosis:**
```bash
# Compare descriptions
grep "description:" agent-name/SKILL.md
grep "\"description\":" agent-name/.claude-plugin/marketplace.json
```
**Solution:**
1. Copy EXACT description from SKILL.md frontmatter
2. Paste in marketplace.json → plugins[0].description
3. Ensure they are IDENTICAL (word for word)
4. Save and test installation again
### Error: "Invalid plugin structure"
**Cause:** Mandatory marketplace.json fields incorrect
**Verify:**
- ✅ `plugins[0].skills` = `["./"]` (not `["SKILL.md"]` or other value)
- ✅ `plugins[0].source` = `"./"` (not empty or other value)
- ✅ `name` in JSON root matches directory name
**Solution:**
Edit marketplace.json and fix fields above according to STEP 0 template.
## 🧠 Final Step: Store Episode for Learning
**⚠️ CRITICAL**: After successful agent creation, store the episode in AgentDB for future learning.
### Automatic Episode Storage
```python
# Store this successful creation for future learning
from integrations.agentdb_bridge import get_agentdb_bridge
from integrations.agentdb_real_integration import Episode
try:
bridge = get_real_agentdb_bridge()
# Create episode from this creation
episode = Episode(
session_id=f"agent-creation-{datetime.now().strftime('%Y%m%d-%H%M%S')}",
task=user_input, # Original user request
input=f"Domain: {domain}, API: {selected_api}, Structure: {architecture}",
output=f"Created: {agent_name}/ with {len(scripts)} scripts",
critique=f"Success: {'✅ High quality' if all_tests_passed else '⚠️ Needs refinement'}",
reward=0.9 if all_tests_passed else 0.7,
success=all_tests_passed,
latency_ms=creation_time_seconds * 1000,
tokens_used=estimated_tokens,
tags=[domain, selected_api, architecture_type],
metadata={
"agent_name": agent_name,
"domain": domain,
"api": selected_api,
"complexity": complexity,
"files_created": len(all_files),
"validation_passed": all_tests_passed
}
)
# Store episode for learning
episode_id = bridge.store_episode(episode)
print(f"🧠 Episode stored for learning: #{episode_id}")
# If successful, create skill
if all_tests_passed and bridge.is_available:
skill_name = f"{domain}_agent_template"
skill = Skill(
name=skill_name,
description=f"Proven template for {domain} agents",
code=f"API: {selected_api}, Structure: {architecture}",
success_rate=1.0,
uses=1,
avg_reward=0.9,
metadata={"domain": domain, "api": selected_api}
)
skill_id = bridge.create_skill(skill)
print(f"🎯 Skill created: #{skill_id}")
except Exception as e:
# AgentDB failure should not break agent creation
print("🔄 AgentDB learning unavailable - agent creation completed successfully")
pass
```
### Learning Progress Indicators
**Provide subtle feedback to user about learning progress:**
```python
# Check learning milestones
if episode_id:
from integrations.learning_feedback import analyze_agent_execution
feedback = analyze_agent_execution(
agent_name=agent_name,
user_input=user_input,
execution_time=creation_time_seconds,
success=all_tests_passed,
result_quality=0.9 if all_tests_passed else 0.7
)
if feedback:
print(feedback) # Subtle milestone feedback
```
**Example user feedback:**
- First creation: "🎉 First agent created successfully!"
- After 10 creations: "⚡ Agent creation optimized based on 10 successful patterns"
- After 30 days: "🌟 I've learned your preferences - shall I optimize this agent?"
### Invisible Learning Complete
**What happens behind the scenes:**
- ✅ Episode stored with full creation context
- ✅ Success patterns learned for future use
- ✅ Skills consolidated from successful templates
- ✅ Causal relationships established (API → success rate)
- ✅ User sees only: "Agent created successfully!"
**Next user gets benefits:**
- Faster creation (learned optimal patterns)
- Better API selection (historical success rates)
- Proven architectures (domain-specific success)
- Personalized suggestions (learned preferences)
---
## Limitations and Warnings
### When NOT to use
❌ Don't use this skill for:
- Editing existing skills (use directly)
- Debugging skills (use directly)
- Questions about skills (answer directly)
### Warnings
⚠️ **Creation time**:
- Simple agents: ~30-60 min
- Complex agents: ~60-120 min
- It's normal to take time (creating everything from scratch)
⚠️ **Review needed**:
- Created agent is functional but may need adjustments
- Test examples in README
- Iterate if necessary
⚠️ **API keys**:
- User needs to obtain API key
- Instructions in created agent's README
Reference in New Issue View Git Blame Copy Permalink