Home
Adventure 3 - Teach Your AI New Skills with APIs
Welcome to the coolest coding adventure yet! Today, you'll learn how to give your AI superpowers by teaching it to fetch weather, tell jokes, and explore the internet. No magic required—just some clever tricks called APIs!
openclaw agent --local --agent main --session-id fresh-001 --message "tell me the current working directory"

Adventure 1

Mystery Challenge
The Big Question
How does your weather app know it's going to rain tomorrow? How does a translator instantly convert languages? How does OpenClaw get smarter without you rewriting all its code?
The answer: APIs - the secret ingredient that connects everything on the internet!

🤔 Think about it: What's one app you use that seems to "magically" know information from somewhere else?

Adventure 1

What Exactly IS an API?
The Restaurant Analogy
Imagine you're at a restaurant. You don't need to:
  • Go into the kitchen
  • Know how to cook the food
  • Understand secret recipes
You just look at the menu, order what you want, and wait for it to arrive at your table.
APIs Work the Same Way!
An API is like a menu for computers. Your program doesn't need to know how another service works - it just needs to know what to ask for and how to ask.
The API brings back exactly what you ordered!

Adventure 1

The Three Main Players
You (The Customer)
Your program or app that needs information
API (The Menu)
The list of available requests and how to make them
Server (The Kitchen)
The computer that processes your request and sends back data
When you make an API request, you're essentially saying: "Hey server, can you please give me this specific information?" The server processes your request and sends back the data you asked for.

Adventure 1

Let's Try Some Real APIs!
Time to see APIs in action! Open your browser and visit these fun, free APIs. Watch what happens when you "order from the menu."
🌤️ Weather API
https://wttr.in/Beijing
Try changing "Beijing" to your city!
😄 Dad Joke API
https://icanhazdadjoke.com/
Refresh for a new joke each time
📍 IP Info API
https://ipinfo.io/json
See your internet location data

Adventure 1

Understanding HTTP GET Requests
When you type a URL in your browser, you're actually sending a GET request. It's the most common type of API request, and it simply means "please GET me this information."
Think of it like raising your hand and asking a question - you're requesting information, and the server responds with an answer.

Adventure 1

The Secret Language: JSON
JSON = JavaScript Object Notation
APIs speak a special language called JSON. It looks a bit weird at first, but once you understand it, you'll see it everywhere on the internet!
JSON organizes information in a structured way using curly braces {}, square brackets [], and key-value pairs. Think of it like a very organized filing cabinet where everything has a specific place.

Adventure 1

JSON: The Russian Nesting Doll Analogy
How JSON Works
Imagine Russian nesting dolls:
  • Outer box = The big curly braces {}
  • Smaller boxes inside = More {} containing related data
  • The treasure inside = The actual information you want
Each "box" has a label (called a key) and contains something (called a value).
{
  "weather": {
    "temperature": "22°C",
    "condition": "sunny",
    "wind": {
      "speed": "10 km/h"
    }
  }
}

Adventure 1

Hands-On Activity #1
Explore Weather JSON Data
Let's get our hands dirty with real JSON! Open your terminal and type this command:
curl https://wttr.in/Beijing?format=j1
You'll see a bunch of nested data. Your mission: Find these three pieces of information in the JSON output.
1
Current Temperature
Look for something like "temp_C" or "temperature"
2
Weather Description
Find words like "sunny", "cloudy", or "rainy"
3
Wind Speed
Search for "wind" or "windspeed" values

⏱️ Time: 5-7 minutes. Work with a partner if you get stuck!

Adventure 1

Reading JSON Like a Detective
Start with the outer braces
Find the biggest {} that contains everything
Look for familiar words
Keys usually describe what the value is: "temperature", "wind", etc.
Follow the path
Trace from outer boxes to inner boxes until you find your data
Grab the value
The information after the colon : is what you want!

Adventure 1

Quick Check
Questions: Test Your Understanding
Question 1: If APIs are like restaurant menus, what would happen if you ordered something that's not on the menu?
Question 2: Why do you think computers use JSON instead of just regular sentences?
Question 3: Can you think of three use cases that probably use APIs to get information?
Discuss these with your neighbor for 3 minutes, then we'll share ideas as a class!

Adventure 1

The Big Reveal: Key Concepts
APIs Connect Everything
They let different programs talk to each other and share information
APIs Keep Things Safe
You get data without accessing the actual database or kitchen
JSON Makes It Standard
Everyone speaks the same data language, making sharing easy
GET Requests Are Simple
Just ask for what you want with a URL, and the server responds

Adventure 1

Now for the Cool Part: Teaching OpenClaw!
You've learned what APIs are and how they work. Now comes the exciting part - we're going to teach your AI assistant OpenClaw how to use APIs!
Just like you learned new skills by following instructions, we'll give OpenClaw a "skill manual" that teaches it how to fetch weather information.

Adventure 1

What is SKILL.md?
Think About Training a New Employee
When someone new joins a team, you give them a handbook or training manual, right?
SKILL.md is OpenClaw's training manual!
A SKILL.md file tells your AI:
  • When to use this skill (trigger words)
  • What steps to follow
  • How to process the information
  • How to respond to the user
It's written in simple language that both humans and AI can understand!

Adventure 1

Creating Your First Skill: Weather Forecaster
01
Create a folder for the skill
Navigate to the skills directory and make a new weather folder
02
Create the SKILL.md file
This file will contain all the instructions for the weather skill
03
Write the instructions
Tell OpenClaw exactly what to do, step by step
04
Test your new skill
Restart OpenClaw and try asking about the weather!

Adventure 1

Step 1 & 2: Set Up the Folder
Open your terminal and type these commands carefully:
which openclaw
cd ~/.openclaw/workspace
mkdir weather
vim weather/SKILL.md
This creates a new folder called "weather" inside your skills directory, then opens a text editor where you'll write the skill instructions.

💡 Tip: If you're not comfortable with vim, you can use nano or any text editor you prefer!

Adventure 1

Step 3: Write the Weather Skill
Copy this content into your SKILL.md file. Each section tells OpenClaw something important!
# Weather Query Skill

## Trigger Words
User mentions "weather", "temperature", "rain", "forecast"

## Steps
1. Get the city name from the user's question
2. Call: curl https://wttr.in/{city}?format=j1
3. Parse the JSON response
4. Tell the user in a friendly way

## Example
User: "What's the weather in Tokyo?"
Response: "It's currently 18°C in Tokyo with partly cloudy skies!"
Save the file and exit the editor. ( :wq \r)

Adventure 1

Hands-On Activity #2
Test Your Weather Skill!
Time to see if your training worked! Run these commands to restart OpenClaw and test your new skill:
openclaw gateway restart
openclaw agents
openclaw agent --agent main --message "tell me a joke in english"
openclaw agent --agent main --message "y=x^2+3x+6, x=3,y=?"
openclaw agent --agent main --message "weather in las vegas"

openclaw configure --section web
Brave API Key: BSAdZ3Xo8AjGyuUqIlUmrCd3GU_eA6t
Does it work? Celebrate! You just taught AI a new skill! 🎉
Getting errors? Don't worry! Check the debugging section coming up next.

Adventure 1

Common Mistakes & How to Fix Them
❌ Mistake: Wrong folder location
Fix: Make sure you're in ~/clawd/skills/ directory. Use pwd to check your location.
❌ Mistake: Typo in the API URL
Fix: Copy and paste URLs exactly. One wrong character breaks everything!
❌ Mistake: Forgot to restart OpenClaw
Fix: After creating or editing a skill, always run openclaw restart.
❌ Mistake: Trigger words don't match
Fix: Use the exact trigger words from SKILL.md when testing.

Adventure 1

More Debugging Tips
Check your syntax
Make sure all curly braces {} and brackets [] are closed. JSON is picky!
Test the API separately
Before adding it to SKILL.md, test the API URL in your browser to make sure it works.
Read error messages carefully
Error messages often tell you exactly what's wrong. Look for line numbers or specific words.
Compare with working examples
Look at the weather skill that works, and compare it line-by-line with your new skill.

Adventure 1

Brainstorm Session
What Other Skills Could OpenClaw Learn?
Now that you know how to teach OpenClaw new skills, the possibilities are endless! Let's brainstorm together.
📚 Knowledge APIs
  • Wikipedia summaries
  • Translation services
  • Dictionary definitions
  • Historical facts
🎮 Entertainment APIs
  • NASA astronomy photos
  • Random cat pictures
  • Inspirational quotes
  • Movie information
🔧 Useful APIs
  • Currency exchange rates
  • News headlines
  • Stock prices
  • Time zone converter

Adventure 1

Pair Share Activity
Design Your Dream API Skill
1
Step 1: Choose an API (3 min)
With your partner, pick one interesting API from the brainstorm list or find your own free API online.
2
Step 2: Plan the skill (5 min)
Sketch out the SKILL.md structure: What trigger words? What steps? How should OpenClaw respond?
3
Step 3: Share with class (2 min per pair)
Present your idea to the class. What problem does your skill solve? Why would it be useful?

Adventure 1

Finding Free APIs
Want to explore more APIs? Here are some great resources to find free, no-signup-required APIs:
🔗 public-apis.io
Huge directory of free APIs organized by category
🔗 rapidapi.com/hub
Marketplace with thousands of APIs, many with free tiers
🔗 github.com/public-apis
Curated list of public APIs on GitHub

💡 Tip: Look for APIs marked as "No Auth" - these don't require signup or API keys!

Adventure 1

Key Takeaways: What We've Learned
APIs Connect the Internet
They let different programs share information safely and efficiently
JSON Is the Common Language
Structured data format that both humans and computers can read
GET Requests Fetch Data
The simplest way to ask an API for information
SKILL.md Teaches AI
Written instructions that give your AI new capabilities

Adventure 1

Your Achievement Unlocked!
100%
Weather Forecaster
Mastered fetching and displaying weather data
100%
Joke Master
Gave your AI a sense of humor with the jokes API
100%
API Caller
Understood how to connect to external services

Adventure 1

Real-World Applications
The skills you learned today are used by professional developers every single day! Here's how APIs power the modern internet:
Mobile Apps
Your phone apps use dozens of APIs - maps, payments, social media, weather, and more all connect through APIs.
E-Commerce
When you buy something online, the store uses payment APIs (like PayPal or Stripe) to process your transaction safely.
Social Media
Sharing between platforms, embedding tweets, or logging in with Google - all powered by APIs.

Adventure 1

Best Practices for Working with APIs
Always read the documentation
Every API has instructions. Read them carefully before you start coding!
Test in small steps
Don't write everything at once. Test the API call first, then add complexity.
Handle errors gracefully
APIs can fail or return unexpected data. Always plan for what happens when things go wrong.
Respect rate limits
Many APIs limit how many requests you can make. Don't spam them!
Keep API keys secret
If an API requires a key, never share it publicly or commit it to GitHub.

Adventure 1

Quick Quiz Time!
Test Your Knowledge: 5 Questions
Let's see how much you remember! Answer these questions on your own first, then we'll review together.

✏️ Write your answers on paper or in a doc. We'll check them in a minute!

Adventure 1

Quiz Questions
1
What does API stand for?
A) Advanced Programming Interface
B) Application Programming Interface
C) Automated Process Integration
D) Application Process Interface
2
What does JSON stand for?
A) JavaScript Object Notation
B) Java Standard Object Notation
C) JavaScript Online Network
D) Just Simple Object Names
3
What is a GET request used for?
A) Sending data to a server
B) Deleting data
C) Retrieving data from a server
D) Updating existing data

Adventure 1

Quiz Questions (Continued)
1
What file do we use to teach OpenClaw new skills?
A) SKILLS.txt
B) SKILL.md
C) openclaw.config
D) api_instructions.json
2
In the restaurant analogy, what does the API represent?
A) The kitchen
B) The customer
C) The menu
D) The food
Done? Let's check the answers together!

Adventure 1

Reflection Time
Exit Ticket: What Did You Learn Today?
Before you leave, take 5 minutes to reflect on today's adventure. Answer these questions thoughtfully:
🌟 One thing that surprised you
What was unexpected or particularly interesting about APIs?
💪 One thing you're proud of
What skill or accomplishment today made you feel good?
❓ One question you still have
What would you like to understand better or explore more?
🚀 One way you'll use this
How might you apply APIs in a future project or idea?

Adventure 1

Next Adventure Preview: Mobile AI!
Coming Soon: Adventure 4
Think learning APIs was cool? Wait until you see what's next!
📱 Mobile Development
Learn how to put your AI on your phone and take it anywhere
🎤 Voice Control
Talk to OpenClaw hands-free with voice commands
🔔 Push Notifications
Get alerts and updates from your AI in real-time
Great work today, future developers! You've leveled up your AI skills and are ready for even bigger challenges. See you next time! 🚀

Adventure 1