agent-skill-creator/README.md

Agent Creator - Meta-Skill for Claude Code

Meta-skill that teaches Claude Code to create complete agents with Claude Skills in a fully autonomous way!

You describe a repetitive workflow → Claude creates a complete production-ready agent in 60-90 minutes.

---

🎯 What It Is and What It Does

Problem It Solves

Creating a Claude Code agent manually is:

• ⏰ Time-consuming: 20-30 hours of work
• 🧠 Complex: Requires knowledge of APIs, Python, architecture
• 🔍 Labor-intensive: Research APIs, define analyses, structure, code, document

Solution: Agent-Creator

You do:

"Automate this workflow: every day I download crop data,
compare current year vs previous, takes 2 hours."

Claude Code does:

1. 🔍 Research available APIs → Decide the best one
2. 🎨 Define useful analyses → Prioritize by value
3. 🏗️ Structure project → Optimal architecture
4. 💻 Implement Python code → Functional, no TODOs
5. 📝 Write documentation → 12,000+ words
6. ⚙️ Create configs → Real values
7. 📦 Deliver agent → Production-ready in subdirectory

Result: Complete agent in ~90 minutes!

---

🚀 Quick Installation

Prerequisites

• Claude Code CLI installed
• Python 3.8+ (for agents that will be created)

Step 1: Install in Claude Code

In the Claude Code terminal, run:

/plugin marketplace add FrancyJGLisboa/agent-skill-creator

Step 2: Verify Installation

/plugin list

You should see:

✓ agent-creator

Done! 🎉

The meta-skill is installed and ready to use.

---

💡 How to Use (Tutorial Guide)

Basic Usage - Describe Your Workflow

In Claude Code, simply describe what you do repeatedly:

👤 You type:
"Automate this workflow: every day I download US crop data,
compare current year vs previous, rank states. Takes 2 hours."

🤖 Claude Code:

[Detects keyword: "automate"]
[Activates skill: agent-creator]
[Loads 5-phase protocol]

🔍 Phase 1: Researching US agriculture APIs...
   ✓ 5 options found
   ✓ Decided: USDA NASS QuickStats API
     Reason: Free, data since 1866, complete coverage

🎨 Phase 2: Defining analyses...
   ✓ 15 typical questions identified
   ✓ 5 main analyses: YoY, Ranking, Trends, Reports

🏗️ Phase 3: Structuring project...
   ✓ 3 scripts + 3 utils planned

🎯 Phase 4: Defining automatic detection...
   ✓ 50+ keywords identified

⚙️ Phase 5: Implementing code...
   ✓ SKILL.md (6,200 words)
   ✓ fetch_nass.py (280 lines)
   ✓ parse_nass.py (180 lines)
   ✓ analyze_nass.py (520 lines)
   ✓ utils/ (350 lines)
   ✓ references/ (5,000 words)
   ✓ .claude-plugin/marketplace.json ✅
   ✓ README.md (800 words)

✅ AGENT CREATED: ./usda-agriculture-agent/

🚀 To install:
/plugin marketplace add ./usda-agriculture-agent

What You Get

A complete directory:

./usda-agriculture-agent/
├── .claude-plugin/
│   └── marketplace.json         ← For Claude Code installation
├── SKILL.md                     ← Complete orchestration (6,000 words)
├── scripts/
│   ├── fetch_nass.py           ← API client (280 lines)
│   ├── parse_nass.py           ← Parsing & validation (180 lines)
│   ├── analyze_nass.py         ← Analyses (520 lines)
│   └── utils/
│       ├── cache_manager.py    ← Smart cache
│       ├── rate_limiter.py     ← Rate limiting
│       └── validators.py       ← Validations
├── references/
│   ├── api-guide.md            ← How to use the API
│   ├── analysis-methods.md     ← Detailed methodologies
│   └── troubleshooting.md      ← Problem solving
├── assets/
│   ├── config.json             ← Real configurations
│   └── metadata.json           ← Metadata
├── DECISIONS.md                 ← Decision justifications
└── README.md                    ← Usage instructions

Total: ~2,000 lines of code + ~12,000 words of documentation

---

🔄 How It Works Internally (5 Phases)

PHASE 1: Discovery (API Research)

What it does:

• Research available public APIs for the domain
• Uses WebSearch and WebFetch to find options
• Compares APIs by: coverage, cost, rate limits, quality
• DECIDES autonomously which to use

Example (Agriculture):

WebSearch: "US agriculture API free historical data"
WebSearch: "USDA API documentation"
WebFetch: https://quickstats.nass.usda.gov/api

→ DECISION: USDA NASS QuickStats API
  Justification: Free, data since 1866, all crops

---

PHASE 2: Design (Analysis Definition)

What it does:

• Brainstorm 10-15 typical user questions
• Group by analysis type
• DEFINES 4-6 priority analyses
• Specifies methodologies (formulas, interpretations)

Example:

Typical questions:
- "Corn production in 2023?"
- "Compare soybeans 2024 vs 2023"
- "Top 10 producing states"

→ ANALYSES DEFINED:
  1. YoY Comparison (year vs year)
  2. State Ranking (top producers)
  3. Trend Analysis (trends)
  4. Report Generation (reports)

---

PHASE 3: Architecture (Structuring)

What it does:

• Defines folder and file structure
• Specifies responsibilities of each script
• Plans cache strategy and performance

Example:

→ STRUCTURE:
  scripts/
    - fetch_nass.py (API requests)
    - parse_nass.py (parsing)
    - analyze_nass.py (analyses)
    utils/
      - cache_manager.py
      - rate_limiter.py

---

PHASE 4: Detection (Automatic Activation)

What it does:

• Lists domain keywords
• Determines when skill should activate
• Creates optimized description

Example:

→ KEYWORDS:
  Entities: USDA, NASS, agriculture
  Commodities: corn, soybeans, wheat
  Metrics: production, area, yield
  Actions: compare, ranking, trend

---

PHASE 5: Implementation (Complete Code)

What it does:

• Creates marketplace.json (REQUIRED!)
• Implements functional Python code
• Writes SKILL.md (5000+ words)
• Creates references with useful content
• Generates real configs

Commands executed internally:

mkdir -p agent-name/{scripts/utils,references,assets,.claude-plugin}
# Write: .claude-plugin/marketplace.json
# Write: SKILL.md
# Write: scripts/fetch_*.py
# Write: scripts/parse_*.py
# Write: scripts/analyze_*.py
# Write: utils/cache_manager.py
# Write: references/*.md
# Write: assets/*.json
# Write: README.md

---

📖 Practical Usage Examples

Example 1: Agriculture (USDA)

👤 Input in Claude Code:

"Automate: every day I download US crop data,
compare current year vs previous, rank states.
Takes 2 hours."

🤖 Claude executes (autonomously):

Phase 1: Research → USDA NASS API
Phase 2: Define → YoY, Ranking, Trends
Phase 3: Structure → 3 scripts + 2 utils
Phase 4: Keywords → USDA, corn, soybeans, production
Phase 5: Implement → 1,410 lines of code

✅ Agent created: ./usda-agriculture-agent/

💻 How to install the created agent:

# In Claude Code
/plugin marketplace add ./usda-agriculture-agent

🎯 How to use:

"US corn production in 2023"
"Compare soybeans this year vs last year"
"Top 10 wheat producing states"

---

Example 2: Finance (Stocks)

👤 Input:

"Need agent for stock analysis:
fetch prices, calculate RSI and MACD,
compare with benchmarks. Daily, 3h."

🤖 Claude creates:

Phase 1: Alpha Vantage API (or Yahoo Finance)
Phase 2: Price fetching, RSI, MACD, Benchmarking
Phase 3-5: Implement everything

✅ Created: ./stock-technical-analysis-agent/

💻 Install:

/plugin marketplace add ./stock-technical-analysis-agent

---

Example 3: Climate Anomalies - Dominic Royé Style (Real Case from Today!)

👤 Input:

"Create automated workflow for climate anomaly analysis following Dominic Royé methodology.
Same procedure, always, for anywhere in the world, finding updated raw data,
processing exactly as in the tutorial, and generating the same chart (same colors,
same quadrants, same logic)."

🤖 Claude executed (5 autonomous phases):

🔍 PHASE 1: Climate API Research
   Researched: Meteostat, Open-Meteo, ERA5, NOAA, Weather.gov
   Compared: Coverage, cost, historical data, quality
   ✓ DECIDED: Multi-API Strategy
     • Primary: Meteostat (observational data)
     • Fallback: Open-Meteo (ERA5 reanalysis, global coverage)
     • Automatic failover for maximum reliability

🎨 PHASE 2: Analysis Design
   Based on Dominic Royé methodology:
   ✓ DEFINED: Climate Anomaly Scatter Plot
     • Axis X: Precipitation anomaly (%)
     • Axis Y: Temperature anomaly (°C)
     • 4 colored quadrants (wet-warm, dry-warm, wet-cold, dry-cold)
     • Seasonal analysis (DJF, MAM, JJA, SON)
     • Climate normal baseline (1991-2020 or 1981-2010)
     • Labeled extreme years with auto-repulsion

🏗️ PHASE 3: Architecture
   ✓ STRUCTURED (modular design):
     scripts/
       - climate_anomalies.py (580 lines) - Integrated pipeline
       - fetch_climate.py (480 lines) - Multi-API client
       - parse_climate.py (370 lines) - Seasonal aggregation
       - plot_anomalies.py (350 lines) - Dominic Royé visualization
     utils/
       - api_factory.py (210 lines) - Factory pattern
       - cache_manager.py (260 lines) - Smart cache (TTL by year)
       - validators.py (200 lines) - Blocking validations
       - context_validators.py (311 lines) - Context warnings
   ✓ Cache: Historical permanent, previous year 30d, current 24h
   ✓ Validations: 16 types (8 blocking + 8 contextual)

🎯 PHASE 4: Automatic Detection
   ✓ KEYWORDS: Dominic Royé, climate anomalies, quadrants,
               DJF MAM JJA SON, temperature precipitation,
               wet-warm dry-warm wet-cold dry-cold
   ✓ DESCRIPTION: Optimized for multi-language detection

⚙️ PHASE 5: Complete Implementation
   ✓ .claude-plugin/marketplace.json (validated)
   ✓ SKILL.md (7,000 words)
   ✓ Python scripts (2,761 lines)
   ✓ References (8,000 words)
     - roye-methodology.md
     - meteostat-guide.md
     - open-meteo-guide.md
     - troubleshooting.md
   ✓ Exact colors: #F7A699, #C23B33, #2C6CB0, #D4E3F3
   ✓ Labeled points = HOLLOW circles (confirmed by reference image)
   ✓ README.md + CORRECTIONS.md + EXAMPLES.md

✅ AGENT CREATED: ./climate-anomalies-roye/

📊 Statistics:

• Code: 2,761 lines of Python (10 scripts)
• Documentation: 20,000+ words (12 files)
• Files: 24 main files
• Time: ~90 minutes of autonomous creation
• Corrections: 3 critical fixes applied (v1.0.1)

🎨 Visual Output: Generates scatter plots identical to Dominic Royé's methodology:

• Temperature anomaly vs Precipitation anomaly
• 4 colored quadrants (exact hex colors)
• Labeled extreme years (hollow circles)
• High quality: 11×8 inches, 130 DPI

💻 Installation of created agent:

# In terminal
cd climate-anomalies-roye
pip install -r requirements.txt

# In Claude Code
/plugin marketplace add ./climate-anomalies-roye

🎯 Using the created agent:

👤 "Climate anomalies for Buenos Aires, summer season DJF"
🤖 [Skill activates automatically]
   [Fetches data: Meteostat or Open-Meteo]
   [Processes: seasonal aggregation, anomaly calculation]
   [Validates: PHASE 2.5 - comprehensive context report]
   [Generates: PNG chart in Dominic Royé style]
   [Returns: Chart + interpretation with context]

👤 "Anomalies for Paris, winter DJF, baseline 1981-2010"
🤖 [Complete analysis with custom normal period]
   [Chart shows extreme years labeled]

Output files generated:
   • data/raw/location_daily.csv (raw data, for audit)
   • data/processed/location_season_normal.csv (climatology + anomalies)
   • data/out/location_season_normal.png (Dominic Royé chart) ✨

🛡️ Quality Guarantees:

• ✅ Multi-API with automatic fallback
• ✅ 16 validation layers (blocking + contextual)
• ✅ Users NEVER receive data without adequate context
• ✅ Automatic detection of climate change trends
• ✅ 100% reproducible (same inputs → same outputs)
• ✅ Auditable (raw data saved for verification)

---

🔄 How It Works: The 5 Autonomous Phases

PHASE 1: DISCOVERY (API Research)

Objective: DECIDE which API to use

Process:

1. Identifies domain (agriculture? finance? climate?)
2. Research available public APIs
3. Compares options (coverage, cost, quality)
4. DECIDES with justification
5. Documents decision

Autonomy: Claude decides without asking the user!

Example of internal commands:

# Claude executes internally:
WebSearch: "US agriculture API free historical data"
WebFetch: https://quickstats.nass.usda.gov/api
# Compares: NASS vs ERS vs FAO
# → DECISION: NASS (best option)

---

PHASE 2: DESIGN (Analysis Definition)

Objective: DEFINE which analyses to implement

Process:

1. Brainstorm typical questions (10-15)
2. Group by type (comparisons, rankings, trends)
3. DEFINES 4-6 priority analyses
4. Specifies methodologies (mathematical formulas)

Autonomy: Claude prioritizes by value and frequency of use!

---

PHASE 3: ARCHITECTURE (Structuring)

Objective: STRUCTURE the project optimally

Process:

1. Defines folder structure
2. Specifies scripts and responsibilities
3. Plans cache strategy
4. Defines validations

Autonomy: Claude chooses optimal architecture based on complexity!

---

PHASE 4: DETECTION (Automatic Activation)

Objective: DETERMINE keywords for detection

Process:

1. Lists domain entities
2. Lists typical actions
3. Determines keywords
4. Creates optimized description (150-250 words)

Result: Skill activates automatically when user asks relevant question!

---

PHASE 5: IMPLEMENTATION (Complete Code)

Objective: IMPLEMENT everything with REAL code

Process:

1. mkdir -p agent-name/{scripts/utils,references,assets,.claude-plugin}
2. Write: .claude-plugin/marketplace.json  ← REQUIRED!
3. Write: SKILL.md (5000+ words)
4. Write: scripts/*.py (functional code)
5. Write: utils/*.py (cache, validators, etc)
6. Write: references/*.md (useful content)
7. Write: assets/*.json (real configs)
8. Write: README.md + DECISIONS.md

Quality Standards:

• ✅ Complete code (no TODO or pass)
• ✅ Detailed docstrings
• ✅ Robust error handling
• ✅ Type hints
• ✅ Comprehensive validations

Result: Production-ready agent!

---

📝 Step-by-Step Commands

1. Create an Agent

In Claude Code:

👤 "Create an agent for [objective]"

OR

👤 "Automate this workflow: [description]"

2. Wait for Creation

Claude executes the 5 phases autonomously (~60-90 min)

3. Install Created Agent

In terminal:

# Go to agent directory
cd ./created-agent-name/

# Install Python dependencies
pip install -r requirements.txt

# If API key needed (follow instructions in README)
export API_KEY_VAR="your_key_here"

In Claude Code:

# Install skill
/plugin marketplace add ./created-agent-name

# Verify installation
/plugin list

4. Use the Agent

In Claude Code:

👤 Ask questions related to the domain
🤖 Skill activates automatically and responds

---

🎯 ROI (Return on Investment)

Metric	Manual	With Agent-Creator	Savings
Time	20-30 hours	1.5 hours	15-20x
Required knowledge	APIs, Python, Architecture	None	100%
Code written	By you	By Claude	100%
Quality	Variable	Production-ready	High

But the best part: You do nothing, just describe the workflow! 🎉

---

📚 Complete Documentation

This repository includes detailed guides in Portuguese:

1. como-compartilhar-skills.md

   • How to publish your skills
   • GitHub, ZIP, Claude.ai
   • Best practices

2. guia-completo-claude-skills.md

   • Complete guide about Claude Skills
   • Technical specifications
   • Examples

3. como_instalar_agente_creator.md

   • Detailed installation instructions
   • Troubleshooting

4. meta-prompt-autonomo-criacao-agentes.md

   • Meta-prompt for agent creation
   • Universal annotated template
   • Quality checklist

5. scripts-vs-skills-guia-didatico.md

   • Didactic comparison Scripts vs Skills
   • When to use each approach

6. agent-creator/README.md

   • Meta-skill documentation
   • Technical details

---

💡 Use Cases

Agriculture

"Create agent for Brazilian crop analysis via CONAB"
→ Agent with TXT parsing, YoY analyses, regional rankings

Finance

"Automate daily stock analysis: prices, RSI, MACD"
→ Agent with technical indicators, alerts, comparisons

Climate

"Climate analysis of Sorriso-MT: temperature, rain, trends"
→ Agent with data since 1940, 6 types of analyses

Economy

"Agent for World Bank economic indicators"
→ Agent with GDP, inflation, country comparisons

Any domain with API or structured data!

---

🛠️ Useful Commands

Check Installed Skills

# In Claude Code
/plugin list

Install Agent-Creator

# In Claude Code
/plugin marketplace add FrancyJGLisboa/agent-skill-creator

Create an Agent

# In Claude Code (natural language)
"Create an agent for [objective]"
"Automate workflow of [description]"

Install Created Agent

# Terminal
cd ./created-agent/
pip install -r requirements.txt

# Claude Code
/plugin marketplace add ./created-agent

Use Agent

# In Claude Code (natural language)
Ask questions related to the agent's domain

---

⚙️ Technical Requirements

To Use Agent-Creator

• Claude Code CLI installed
• Internet connection (for API research)

For Created Agents

• Python 3.8+
• pip (to install dependencies)
• Specific dependencies (listed in requirements.txt of each agent)
• API key (if chosen API requires - instructions in agent's README)

---

🎓 Understanding the Output

Main Files Created

.claude-plugin/marketplace.json

• Configuration for Claude Code installation
• CRITICAL: Without it, skill cannot be installed

SKILL.md

• Complete skill orchestration
• Detailed workflows
• Analysis documentation
• ~5000-7000 words

scripts/

• Functional Python code
• Separated by responsibility (fetch, parse, analyze)
• Reusable utils (cache, validators)
• ~1500-2000 lines total

references/

• Technical guides (API docs, methodologies)
• Troubleshooting
• Domain knowledge
• ~5000 words

README.md

• Installation instructions
• Usage examples
• Troubleshooting

DECISIONS.md

• Justifications for all decisions
• Which API chosen and why
• Which analyses and why
• Trade-offs considered

---

⭐ Features

• ✅ Total Autonomy: Claude decides everything
• ✅ Production-Ready: Functional code, no TODOs
• ✅ Complete Documentation: 10,000+ words
• ✅ Smart Cache: TTL based on data type
• ✅ Robust Validations: Guaranteed data quality
• ✅ Error Handling: Retry, fallbacks, clear messages
• ✅ Marketplace.json: Guaranteed Claude Code installation

---

🚧 Limitations

DO NOT use for:

• ❌ Editing existing skills (edit directly)
• ❌ Debugging skills (debug directly)
• ❌ Asking questions about skills (ask directly)

USE ONLY for:

• ✅ Creating new agents from scratch
• ✅ Automating repetitive workflows

---

🤝 Contributing

Contributions are welcome!

1. Fork this repository
2. Create a branch (git checkout -b feature/improvement)
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

---

📄 License

Apache 2.0 (same license as Anthropic's official skills)

Free to use, modify, and distribute.

---

🙏 Credits

Inspired by:

• Anthropic Agent Skills Spec
• skill-creator skill

Differentiator: Total autonomy - Claude decides everything, not just executes instructions.

---

📊 Repository Statistics

Agent-Creator Meta-Skill:

• 8 main files
• ~5,000 words in SKILL.md
• 6 detailed references
• 5-phase autonomous protocol

Documentation:

• 5 complete guides in Portuguese
• ~150 KB of documentation
• Complete coverage of Claude Skills ecosystem

---

🌟 Examples of Agents Created with Agent-Creator

1. USDA Agriculture Agent

• API: USDA NASS
• Analyses: YoY, Ranking, Trends
• Output: 1,410 lines of code

2. Climate Analysis Sorriso-MT (created today!)

• API: Open-Meteo
• Analyses: 6 types (series, trends, anomalies, etc.)
• Output: 2,070 lines of code

All created autonomously by the meta-skill!

---

📞 Support

Issues: https://github.com/FrancyJGLisboa/agent-skill-creator/issues Discussions: https://github.com/FrancyJGLisboa/agent-skill-creator/discussions

---

🚀 Quick Start

# 1. Install agent-creator
/plugin marketplace add FrancyJGLisboa/agent-skill-creator

# 2. Create an agent (in Claude Code)
"Automate workflow for analyzing [your domain]"

# 3. Wait for creation (~60-90 min)

# 4. Install created agent
/plugin marketplace add ./created-agent

# 5. Use it!
"[Ask domain questions]"

---

Start automating today! Transform repetitive workflows into powerful agents! 🚀

---

Version: 1.0.0 Updated: October 2025 Author: Created with Claude Code Repository: https://github.com/FrancyJGLisboa/agent-skill-creator