Skills & Tools

<workspace>/skills/
└── your-skill-name/
    ├── SKILL.md              # Core workflow (~500 lines max)
    ├── references/           # Loaded on-demand
    │   ├── api-docs.md
    │   └── examples.md
    └── scripts/              # Optional executables
        └── helper.sh

---
name: your-skill-name
description: One line on what it does and when to use it.
metadata:
  openclaw:
    requires:
      bins:
        - curl
      env:
        - YOUR_API_KEY
    primaryEnv: YOUR_API_KEY
---

Run the helper at {baseDir}/scripts/helper.sh ...

I need help creating or optimizing an AgentSkill.

Skill name:
[your-skill-name]

Purpose:
What the skill does and when it should activate.

Triggers:
What kinds of tasks or questions should activate this skill.

Tools needed:
Any tools, commands, or APIs the skill will use.

Reference docs:
Docs or specs that should live in references/ for on-demand loading.

Existing skill (if applicable):
Path to the current SKILL.md if this is a refactor.

Please:
- Create or optimize the skill following AgentSkills best practices
- Keep the core workflow in SKILL.md and move details into references/
- Keep SKILL.md under ~500 lines
- Declare required binaries and env vars under metadata.openclaw.requires
- Confirm it shows as eligible with `openclaw skills check`
- Show the final file structure and contents

I need help creating an AgentSkill.

Skill name:
weather-checker

Purpose:
Check current weather and forecasts using wttr.in (no API key required).

Triggers:
Questions about weather, temperature, forecast.

Tools needed:
curl to fetch from wttr.in, parsing text output.

Reference docs:
wttr.in documentation should live in references/wttr-in-docs.md

Please:
- Create the skill following AgentSkills best practices
- Keep the core workflow in SKILL.md under ~500 lines
- Move API details into references/
- Show the final file structure and contents

I need help optimizing an AgentSkill.

Existing skill:
~/.openclaw/workspace/skills/my-bloated-skill/SKILL.md

Purpose:
The skill works but SKILL.md is 1,800 lines and burns too many tokens.

Please:
- Refactor following AgentSkills best practices
- Keep core workflow in SKILL.md under ~500 lines
- Move details into references/ for on-demand loading
- Confirm it still loads with `openclaw skills check`
- Show what changed

openclaw status --usage    # every provider with usage auth
openclaw models status     # auth profiles + usage windows

cp check-quotas.sh ~/.local/bin/check-quotas
chmod +x ~/.local/bin/check-quotas

# Verify ~/.local/bin is in your PATH
echo $PATH | grep -q "$HOME/.local/bin" || \
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

mkdir -p ~/.config/check-quotas
cat > ~/.config/check-quotas/env <<'EOF'
export OPENROUTER_API_KEY="your-api-key-here"
export SYNTHETIC_API_KEY="your-api-key-here"
export ANTHROPIC_API_KEY="your-api-key-here"
EOF

# Readable by you only
chmod 700 ~/.config/check-quotas
chmod 600 ~/.config/check-quotas/env

#!/bin/bash
# Check API quotas for various providers
# Returns JSON with quota status
#
# Usage: check-quotas
#
# Keys come from the environment, or from an env file:
#   CHECK_QUOTAS_ENV     - env file to source (default: ~/.config/check-quotas/env)
#   CLAUDE_KEYCHAIN_ITEM - macOS Keychain item name for Claude Code credentials

set -euo pipefail

ENV_FILE="${CHECK_QUOTAS_ENV:-$HOME/.config/check-quotas/env}"
[ -f "$ENV_FILE" ] && source "$ENV_FILE"
CLAUDE_KEYCHAIN="${CLAUDE_KEYCHAIN_ITEM:-Claude Code-credentials}"

# Check Claude Code subscription usage (macOS Keychain, unofficial endpoint)
check_claude_code() {
    if ! command -v security &> /dev/null; then
        echo "null"
        return
    fi

    local token=$(security find-generic-password \
        -s "$CLAUDE_KEYCHAIN" -w 2>/dev/null | \
        jq -r '.claudeAiOauth.accessToken' 2>/dev/null || echo "")

    if [ -z "$token" ] || [ "$token" = "null" ]; then
        echo "null"
        return
    fi

    curl -s https://api.anthropic.com/api/oauth/usage \
        -H "Accept: application/json" \
        -H "Content-Type: application/json" \
        -H "User-Agent: claude-code/2.0.32" \
        -H "Authorization: Bearer $token" \
        -H "anthropic-beta: oauth-2025-04-20" 2>/dev/null || echo "null"
}

# Check Synthetic quota
check_synthetic() {
    local api_key="${SYNTHETIC_API_KEY:-}"
    if [ -z "$api_key" ]; then echo "null"; return; fi

    curl -s https://api.synthetic.new/v2/quotas \
        -H "Authorization: Bearer $api_key" 2>/dev/null || echo "null"
}

# Check OpenRouter key usage and limit
check_openrouter() {
    local api_key="${OPENROUTER_API_KEY:-}"
    if [ -z "$api_key" ]; then echo "null"; return; fi

    curl -s https://openrouter.ai/api/v1/key \
        -H "Authorization: Bearer $api_key" 2>/dev/null || echo "null"
}

# Check the Anthropic API key is valid (no quota endpoint; costs no tokens)
check_anthropic() {
    local api_key="${ANTHROPIC_API_KEY:-}"
    if [ -z "$api_key" ]; then echo "null"; return; fi

    curl -s https://api.anthropic.com/v1/models \
        -H "x-api-key: $api_key" \
        -H "anthropic-version: 2023-06-01" \
        2>/dev/null | \
        jq -r 'if .error then "error" else "valid" end' || echo "null"
}

# Build combined JSON output
claude_quota=$(check_claude_code)
synthetic_quota=$(check_synthetic)
openrouter_quota=$(check_openrouter)
anthropic_quota=$(check_anthropic)

jq -n \
    --argjson claude "$claude_quota" \
    --argjson synthetic "$synthetic_quota" \
    --argjson openrouter "$openrouter_quota" \
    --arg anthropic "$anthropic_quota" \
    '{
        claude_code: $claude,
        synthetic: $synthetic,
        openrouter: $openrouter,
        anthropic_api: $anthropic,
        checked_at: (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
    }'

{
  "claude_code": { ... },
  "synthetic": { ... },
  "openrouter": { "data": { "usage": 45.23, "limit": 100, ... } },
  "anthropic_api": "valid",
  "checked_at": "2026-10-15T09:28:00Z"
}

# Is the OpenRouter key over 90% of its limit? (null limit = unlimited)
check-quotas | jq '.openrouter.data | .limit != null and (.usage / .limit) > 0.9'

# Raw Synthetic quota response
check-quotas | jq '.synthetic'

# Pretty print for humans
check-quotas | jq .

# Before spawning an expensive agent, check quotas
if check-quotas | jq -e '.openrouter.data | .limit != null and (.usage / .limit) > 0.9' > /dev/null; then
    echo "OpenRouter quota high, using fallback"
fi

check_yourprovider() {
    local api_key="${YOURPROVIDER_API_KEY:-}"
    if [ -z "$api_key" ]; then
        echo "null"
        return
    fi

    curl -s https://api.yourprovider.com/quota \
        -H "Authorization: Bearer $api_key" 2>/dev/null || echo "null"
}