version: "1.0.1" name: giphy-gif description: Search and send contextual GIFs from Giphy in Discord conversations. Use when the user wants to react with a GIF, express emotions with a GIF, or when you determine a GIF would enhance the conversation (celebrations, reactions, emotions, humor). Triggers on requests like "send a GIF", "show me a GIF", or when context suggests a GIF reaction would be appropriate.

Giphy GIF Search

This skill enables searching for and sending contextually appropriate GIFs from Giphy's library in Discord conversations.

Setup

Before using this skill, you need a Giphy API key:

1. Go to Giphy Developers Dashboard
2. Sign up or log in
3. Create a new app (select "API" not "SDK")
4. Copy your API key
5. Add to OpenClaw config or set environment variable: export GIPHY_API_KEY="your-api-key-here"

OpenClaw Config (Recommended)

Add to ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "giphy-gif": {
        "apiKey": "your-api-key-here"
      }
    }
  }
}

Usage

Search and Send a GIF

Use this one-liner to search and get a Giphy URL:

# Basic search
exec("QUERY='excited'; API_KEY=$(jq -r '.skills.entries.\"giphy-gif\".apiKey // env.GIPHY_API_KEY' ~/.openclaw/openclaw.json 2>/dev/null || echo \"$GIPHY_API_KEY\"); curl -s \"https://api.giphy.com/v1/gifs/search?api_key=${API_KEY}&q=$(printf '%s' \"$QUERY\" | jq -sRr @uri)&limit=1&rating=g\" | jq -r '.data[0].url // empty'")

Practical Example

# 1. Define your search query
query="happy dance"
 
# 2. Get GIF URL using the helper function below
gif_url=$(exec("QUERY='$query'; API_KEY=$(jq -r '.skills.entries.\"giphy-gif\".apiKey // env.GIPHY_API_KEY' ~/.openclaw/openclaw.json 2>/dev/null || echo \"$GIPHY_API_KEY\"); curl -s \"https://api.giphy.com/v1/gifs/search?api_key=${API_KEY}&q=$(printf '%s' \"$QUERY\" | jq -sRr @uri)&limit=1&rating=g\" | jq -r '.data[0].url // empty'"))
 
# 3. Send to Discord
message(action="send", message=gif_url)

Simplified Helper Command

For easier use, create this helper in your commands:

# Function to search GIF (copy this pattern)
search_gif() {
  local query="$1"
  local api_key
  
  # Try OpenClaw config first, then env var
  api_key=$(jq -r '.skills.entries."giphy-gif".apiKey // empty' ~/.openclaw/openclaw.json 2>/dev/null)
  [[ -z "$api_key" ]] && api_key="$GIPHY_API_KEY"
  
  if [[ -z "$api_key" ]]; then
    echo "Error: GIPHY_API_KEY not configured" >&2
    return 1
  fi
  
  # URL encode and search
  local encoded_query=$(printf '%s' "$query" | jq -sRr @uri)
  curl -s "https://api.giphy.com/v1/gifs/search?api_key=${api_key}&q=${encoded_query}&limit=1&rating=g&lang=en" | jq -r '.data[0].url // empty'
}
 
# Usage:
# gif_url=$(search_gif "excited")
# message(action="send", message="$gif_url")

Discord Auto-Embed

When you send a Giphy URL to Discord, it will automatically embed as an animated GIF. No additional steps needed.

When to Use

Send GIFs in these situations:

• User requests: "send me a GIF", "show me something funny"
• Celebrations: achievements, good news, milestones
• Reactions: surprise, shock, agreement, disagreement
• Emotions: happy, sad, excited, confused, thinking
• Humor: to lighten the mood or add comedic timing
• Emphasis: to reinforce a point with visual impact

Context-Aware Sending

Be thoughtful about when to send GIFs to maintain natural conversation flow:

• Direct requests: Always send when explicitly asked
• GIF exchange initiated by user: If the user sends a GIF, match naturally 1-2 times, then resume normal chat
• Standalone reactions: Only for significant moments (big celebrations, major news, strong emotional beats)
• Normal conversation: Default to text responses; GIFs should be occasional spice, not the main dish
• Topic shift: If conversation moves to serious/informational topics, return to text-only mode

Goal: Make GIF usage feel natural and contextual, not automatic or overwhelming.

Best Practices

1. Match the context: Choose search terms that match the conversation tone
2. Keep it appropriate: The script uses 'g' rating (safe for work) by default
3. Don't overuse: GIFs are most effective when used sparingly
4. Search terms matter: Use specific, descriptive terms for better results

• Good: "celebration dance", "facepalm reaction", "mind blown"
• Poor: "thing", "stuff", "it"

1. Read the room: If the conversation becomes more serious or informational, stick to text

Common Search Terms

• Reactions: thumbs up, facepalm, eye roll, shocked, confused
• Emotions: excited, happy, sad, angry, love, crying
• Actions: dance, clap, wave, thinking, working
• Celebrations: party, celebrate, success, winner
• Humor: funny, lol, wtf, awkward, fail

Technical Details

• API: Giphy v1
• Rate limits:
• Beta keys: 100 requests per hour
• Production keys: Higher limits available
• Response format: Giphy page URLs (Discord auto-embeds)
• Dependencies: bash, curl, jq (standard on Linux/macOS/WSL)
• Default rating: 'g' (safe for work)
• API key priority: OpenClaw config → Environment variable

API Key Tiers

• Beta Key (Free): 100 requests/hour, good for personal use
• Production Key: Higher limits, requires approval for specific use cases

Get started with a free beta key at developers.giphy.com.

Troubleshooting

"Unauthorized" error:

• Check API key is set correctly in ~/.openclaw/openclaw.json or $GIPHY_API_KEY
• Verify key is valid at Giphy dashboard

No GIF returned:

• Try a different search term
• Check API rate limits (100/hour for beta keys)

jq not found:

• Install jq: sudo apt install jq (Linux) or brew install jq (macOS)