OpenClaw v2026.2 için geçerlidir | Bu makale temel Markdown ve komut satırına aşina olduğunuzu varsayar; özel beceri oluşturmak istiyorsunuz.

TL;DR: Skill oluşturmak için yalnızca bir SKILL.md dosyası gereklidir. Temel alanlar: name, version, triggers (tetikleyiciler), tools (araç listesi). ~/.openclaw/workspace/skills/<name>/SKILL.md konumuna yerleştirin. Tetikleyiciler çakışmayı önlemek için spesifik olmalıdır. ClawHub’a yayınlama: openclaw skill publish <name>. Güvenlik taraması ve izin kontrolü içerir.

Geliştirme Ortamı Hazırlığı

Ön Gereksinimler

Beceri Dizini Oluşturma

# Beceri dizini oluştur
mkdir -p ~/.openclaw/workspace/skills/weather-api

# Dizine gir
cd ~/.openclaw/workspace/skills/weather-api

# Temel dosyaları oluştur
touch SKILL.md
touch README.md
touch config.json.example

Dizin Yapısı

weather-api/
├── SKILL.md              # Beceri tanımı (zorunlu)
├── README.md             # Açıklama dokümantasyonu (önerilen)
├── config.json.example   # Yapılandırma örneği (isteğe bağlı)
├── src/                  # Kaynak kod (isteğe bağlı)
│   └── index.js
└── package.json          # Bağımlılık bildirimi (isteğe bağlı)

SKILL.md Yapısı Detayları

Temel Yapı

---
# Frontmatter: meta veriler
name: skill-name
version: 1.0.0
author: your-name
description: Brief description
triggers:
  - trigger-1
  - trigger-2
dependencies: []
tools: []
---

# Skill Başlığı

Detaylı açıklama...

## Özellikler
## Kurulum
## Kullanım Örnekleri
## Yapılandırma
## Notlar

Frontmatter Alanları

Tetikleyici Tasarımı

Tetikleyiciler Agent’ın beceriyi tanımasının anahtarıdır:

triggers:
  - weather
  - hava
  - forecast
  - tahmin
  - temperature
  - sıcaklık
  - rain
  - yağmur
  - umbrella
  - şemsiye

Tasarım İlkeleri:

Uygulama: Hava Durumu Sorgulama Becerisi Geliştirme

Gereksinim Analizi

Geliştireceğimiz hava durumu sorgulama becerisi şunları içerecek:

1. Güncel hava durumunu sorgulama
2. Gelecek günlerin tahminini sorgulama
3. Türkçe ve İngilizce şehir adı desteği
4. Giyim önerisi sağlama

Tam SKILL.md

---
name: weather-api
version: 1.0.0
author: your-name
description: OpenWeatherMap API'den hava durumu bilgisi sorgusu
triggers:
  - weather
  - hava
  - forecast
  - tahmin
  - temperature
  - sıcaklık
  - rain
  - yağmur
  - umbrella
  - şemsiye
dependencies: []
tools:
  - weather_current
  - weather_forecast
---

# Weather API Skill

Dünya genelinde herhangi bir şehir için hava durumu bilgisi sorgusu. Pratik önerilerle güncel hava durumu ve tahminler sağlar.

## Özellikler

- **Güncel Hava Durumu**: Gerçek zamanlı hava koşullarını alın
- **Tahmin**: 5 günlük hava durumu tahmini
- **Çok dilli**: Birden fazla dilde şehir adı desteği
- **Akıllı Öneriler**: Giyim ve aktivite önerileri

## Kurulum

### 1. API Anahtarı Alın

1. [OpenWeatherMap](https://openweathermap.org/api) adresini ziyaret edin
2. Ücretsiz hesap oluşturun
3. API anahtarı oluşturun

### 2. Beceriyi Yapılandırın

Ortam değişkenini ayarlayın:

\`\`\`bash
export OPENWEATHER_API_KEY="your-api-key-here"
\`\`\`

Veya OpenClaw yapılandırmanıza ekleyin:

\`\`\`json
{
  "skills": {
    "weather-api": {
      "apiKey": "your-api-key-here",
      "units": "metric",
      "lang": "zh_cn"
    }
  }
}
\`\`\`

## Kullanım Örnekleri

### Güncel Hava Durumu

Kullanıcı: "北京今天天气怎么样"
Kullanıcı: "What's the weather in Tokyo"
Kullanıcı: "Check weather for Shanghai"

Eylem:
1. Kullanıcı mesajından şehir adını ayrıştırın
2. city parametresiyle weather_current aracını çağırın
3. Hava durumu bilgisini biçimlendirin ve döndürün

### Hava Durumu Tahmini

Kullanıcı: "明天会下雨吗"
Kullanıcı: "3天天气预报 for New York"
Kullanıcı: "周末天气怎么样"

Eylem:
1. Kullanıcı mesajından şehir adı ve gün sayısını ayrıştırın
2. weather_forecast aracını çağırın
3. Tahmin verisini okunabilir özet halinde biçimlendirin

### Akıllı Öneriler

Kullanıcı: "今天需要带伞吗"
Kullanıcı: "穿什么衣服合适"
Kullanıcı: "适合户外运动吗"

Eylem:
1. Güncel hava durumunu alın
2. Koşulları analiz edin (yağmur, sıcaklık, UV)
3. Pratik öneriler sağlayın

## Araçlar

### weather_current

Bir şehir için güncel hava durumunu alır.

**Parametreler:**
- `city` (string, zorunlu): Şehir adı, herhangi bir dilde olabilir
- `units` (string, isteğe bağlı): "metric", "imperial" veya "kelvin". Varsayılan: "metric"
- `lang` (string, isteğe bağlı): Dil kodu. Varsayılan: "zh_cn"

**Döndürür:**
\`\`\`json
{
  "city": "Beijing",
  "country": "CN",
  "temperature": 25,
  "feels_like": 27,
  "humidity": 65,
  "wind_speed": 12,
  "condition": "Partly cloudy",
  "icon": "02d",
  "suggestion": "Light jacket recommended, no rain expected"
}
\`\`\`

### weather_forecast

5 güne kadar hava durumu tahmini alır.

**Parametreler:**
- `city` (string, zorunlu): Şehir adı
- `days` (number, isteğe bağlı): Gün sayısı (1-5). Varsayılan: 3
- `units` (string, isteğe bağlı): Sıcaklık birimleri

**Döndürür:**
\`\`\`json
{
  "city": "Beijing",
  "forecast": [
    {
      "date": "2026-02-27",
      "temp_high": 28,
      "temp_low": 18,
      "condition": "Sunny",
      "rain_chance": 0
    },
    ...
  ]
}
\`\`\`

## Yapılandırma Seçenekleri

| Seçenek | Tip | Varsayılan | Açıklama |
|---------|-----|------------|----------|
| `apiKey` | string | - | OpenWeatherMap API anahtarı |
| `units` | string | "metric" | Sıcaklık birimleri |
| `lang` | string | "zh_cn" | Açıklamalar için dil |
| `cache_ttl` | number | 600 | Önbellek süresi (saniye) |

## Hata İşleme

Beceri yaygın hataları işler:

- **Şehir bulunamadı**: Benzer şehir adları önerir
- **API anahtarı geçersiz**: Kullanıcıyı yapılandırmayı kontrol etmeye yönlendirir
- **Oran limiti**: İsteği kuyruğa alır ve yeniden dener
- **Ağ hatası**: Mevcutsa önbelleğe alınmış veriye geri döner

## Notlar

- Ücretsiz katman günde 1000 isteğe izin verir
- Şehir adları Çince destekler: "北京", "上海", "广州"
- Sonuçlar varsayılan olarak 10 dakika önbelleğe alınır
- Daha sık güncellemeler için ücretli katmana geçmeyi düşünün

Araç Uygulaması (İsteğe Bağlı)

Beceriniz belirli işlemler gerçekleştirmeyi gerektiriyorsa, araç uygulaması ekleyebilirsiniz.

Basit Yöntem: Yerleşik Araçları Kullanma

OpenClaw web_search ve read araçlarını yerleşik olarak içerir, SKILL.md’de doğrudan nasıl kullanılacağını açıklayabilirsiniz:

## Implementation Notes

Hava durumu verisi almak için:

1. Hava durumu API'si bulmak için `web_search` aracını kullanın
2. JSON yanıtı almak için `read` aracını kullanın
3. Veriyi ayrıştırın ve biçimlendirin

Örnek arama sorgusu: "weather API Beijing current temperature"

Gelişmiş Yöntem: Özel Araç Betiği

src/index.js oluşturun:

// src/index.js
const axios = require('axios');

const OPENWEATHER_BASE_URL = 'https://api.openweathermap.org/data/2.5';

async function weather_current({ city, units = 'metric', lang = 'zh_cn' }, config) {
  const apiKey = config.apiKey || process.env.OPENWEATHER_API_KEY;
  
  if (!apiKey) {
    throw new Error('OpenWeatherMap API key not configured');
  }

  try {
    const response = await axios.get(`${OPENWEATHER_BASE_URL}/weather`, {
      params: {
        q: city,
        appid: apiKey,
        units,
        lang
      }
    });

    const data = response.data;
    
    // Koşullara göre öneri oluştur
    let suggestion = '';
    if (data.rain || data.weather[0].main === 'Rain') {
      suggestion = 'Bring an umbrella, rain expected';
    } else if (data.main.temp < 15) {
      suggestion = 'Wear warm clothing, temperature is low';
    } else if (data.main.temp > 30) {
      suggestion = 'Stay hydrated, high temperature';
    } else {
      suggestion = 'Pleasant weather, enjoy your day';
    }

    return {
      city: data.name,
      country: data.sys.country,
      temperature: data.main.temp,
      feels_like: data.main.feels_like,
      humidity: data.main.humidity,
      wind_speed: data.wind.speed,
      condition: data.weather[0].description,
      icon: data.weather[0].icon,
      suggestion
    };
  } catch (error) {
    if (error.response?.status === 404) {
      throw new Error(`City "${city}" not found. Please check the spelling.`);
    }
    throw error;
  }
}

async function weather_forecast({ city, days = 3, units = 'metric' }, config) {
  const apiKey = config.apiKey || process.env.OPENWEATHER_API_KEY;
  
  if (!apiKey) {
    throw new Error('OpenWeatherMap API key not configured');
  }

  try {
    const response = await axios.get(`${OPENWEATHER_BASE_URL}/forecast`, {
      params: {
        q: city,
        appid: apiKey,
        units,
        cnt: days * 8 // Günde 8 tahmin (her 3 saatte bir)
      }
    });

    const data = response.data;
    
    // Güne göre grupla ve günlük özet al
    const dailyForecasts = {};
    data.list.forEach(item => {
      const date = item.dt_txt.split(' ')[0];
      if (!dailyForecasts[date]) {
        dailyForecasts[date] = {
          temp_high: item.main.temp_max,
          temp_low: item.main.temp_min,
          conditions: [item.weather[0].main],
          rain_chance: item.pop * 100
        };
      } else {
        dailyForecasts[date].temp_high = Math.max(dailyForecasts[date].temp_high, item.main.temp_max);
        dailyForecasts[date].temp_low = Math.min(dailyForecasts[date].temp_low, item.main.temp_min);
        if (!dailyForecasts[date].conditions.includes(item.weather[0].main)) {
          dailyForecasts[date].conditions.push(item.weather[0].main);
        }
        dailyForecasts[date].rain_chance = Math.max(dailyForecasts[date].rain_chance, item.pop * 100);
      }
    });

    return {
      city: data.city.name,
      forecast: Object.entries(dailyForecasts)
        .slice(0, days)
        .map(([date, info]) => ({
          date,
          temp_high: Math.round(info.temp_high),
          temp_low: Math.round(info.temp_low),
          condition: info.conditions.join('/'),
          rain_chance: Math.round(info.rain_chance)
        }))
    };
  } catch (error) {
    if (error.response?.status === 404) {
      throw new Error(`City "${city}" not found. Please check the spelling.`);
    }
    throw error;
  }
}

module.exports = {
  weather_current,
  weather_forecast
};

package.json

{
  "name": "weather-api",
  "version": "1.0.0",
  "description": "Weather API skill for OpenClaw",
  "main": "src/index.js",
  "dependencies": {
    "axios": "^1.6.0"
  },
  "openclaw": {
    "skill": "weather-api",
    "tools": ["weather_current", "weather_forecast"]
  }
}

Beceriyi Test Etme

Yerel Test

# SKILL.md sözdizimini doğrula
openclaw skill validate weather-api

# Örnek çıktı:
# ✅ Frontmatter geçerli
# ✅ Tetikleyiciler tanımlı
# ✅ Açıklama mevcut
# ✅ Araçlar dokümante edilmiş

# Beceriyi yükle
openclaw skill load weather-api

# Beceriyi test et
openclaw agent --message "北京今天天气怎么样"

# Hava durumu bilgisi görmelisiniz

Hata Ayıklama Modu

# Hata ayıklama günlüğünü etkinleştir
openclaw gateway --verbose --filter skill:weather-api

# Beceri yükleme günlüklerini görüntüle
openclaw logs --skill weather-api

Test Senaryoları

Beceriyi Yayınlama

Yayına Hazırlık

1. Dokümantasyonu tamamlayın: README.md’nin eksiksiz olduğundan emin olun
2. Örnek ekleyin: Kullanım örnekleri sağlayın
3. Kapsamlı test: Çeşitli sınır durumlarını kapsayın
4. Hassas bilgileri temizleyin: API Key vb. kaldırın

GitHub’a Yayınlama

# Git'i başlat
git init
git add .
git commit -m "Initial release of weather-api skill"

# GitHub'a gönder
git remote add origin https://github.com/your-username/weather-api.git
git push -u origin main

# Yayın etiketi oluştur
git tag v1.0.0
git push origin v1.0.0

ClawHub’a Gönderme

# ClawHub'a yayınla
openclaw skill publish weather-api

# Örnek çıktı:
# Validating skill...
# ✅ Validation passed
# Publishing to ClawHub...
# ✅ Published successfully!
# 
# Your skill is now available at:
# https://clawhub.com/skills/weather-api

README.md Şablonu

# Weather API Skill for OpenClaw

OpenWeatherMap API'den hava durumu bilgisi sorgusu.

## Özellikler

- Güncel hava durumu koşulları
- 5 günlük hava durumu tahmini
- Çok dilli şehir desteği
- Akıllı giyim önerileri

## Kurulum

\`\`\`bash
openclaw skill install weather-api
\`\`\`

## Yapılandırma

OpenWeatherMap API anahtarınızı ayarlayın:

\`\`\`bash
export OPENWEATHER_API_KEY="your-api-key"
\`\`\`

Veya OpenClaw yapılandırmasında:

\`\`\`json
{
  "skills": {
    "weather-api": {
      "apiKey": "your-api-key"
    }
  }
}
\`\`\`

## Kullanım

Sadece hava durumu hakkında sorun:

- "北京今天天气怎么样"
- "What's the weather in Tokyo"
- "明天会下雨吗"
- "今天需要带伞吗"

## Gereksinimler

- OpenWeatherMap API anahtarı (ücretsiz katman: günde 1000 istek)
- İnternet bağlantısı

## Lisans

MIT

Gelişmiş Teknikler

Koşullu Tetikleme

Bağlama göre tetiklenip tetiklenmeyeceğine karar verin:

## Advanced Triggers

Bu beceri şu durumlarda tetiklenir:
1. Kullanıcı hava durumuyla ilgili anahtar kelimelerden bahsettiğinde
2. Kullanıcı sıcaklık veya koşullar hakkında sorduğunda
3. Kullanıcı açık hava aktivitesi önerilerine ihtiyaç duyduğunda

Şu durumlarda tetiklenmez:
- Hava durumu mecazi olarak bahsedildiğinde ("I'm under the weather")
- Kullanıcı CPU sıcaklığı veya diğer teknik metrikler hakkında sorduğunda

Bağlam Hafızası

SKILL.md’ye bağlam işleme ekleyin:

## Context Handling

Kullanıcı bir hava durumu sorgusundan sonra "What about tomorrow?" diye sorduğunda:
1. Önceki bağlamda şehir adını kontrol edin
2. Tahmin sorgusu için aynı şehri kullanın

Kullanıcı başka bir şehir sorguladıktan sonra "And in Shanghai?" diye sorduğunda:
1. Yeni şehir adını ayrıştırın
2. Her iki şehrin hava durumunu karşılaştırın

Zincirleme Beceriler

Diğer becerilerle işbirliği:

## Skill Integration

Bu beceri şunlarla iyi çalışır:
- **calendar**: Havaya göre etkinlik öner
- **travel**: Seyahat destinasyonları için hava durumu sağla
- **clothing**: Sıcaklığa göre kıyafet öner

Örnek iş akışı:
Kullanıcı: "Planning a trip to Tokyo next week"
1. Travel skill: Destinasyon ve tarihleri ayrıştır
2. Weather skill: Tokyo tahminini al
3. Calendar skill: Mevcut etkinlikleri kontrol et
4. Birleşik yanıt: Havayla birlikte seyahat özeti

Hata Kurtarma

Hataları zarif şekilde işleyin:

## Error Recovery

API başarısız olduğunda:
1. Son veriler için önbelleği kontrol edin
2. Kullanıcıyı sorun hakkında bilgilendirin
3. Alternatifler sunun:
   - "I couldn't get live weather data. Want me to try again?"
   - "The weather service is temporarily unavailable. Would you like a general forecast?"

Şehir bulunamadığında:
1. Benzer şehir adları önerin
2. Açıklama isteyin
3. Mevcutsa konum bilgisini kullanın

En İyi Uygulamalar

Dokümantasyon Standartları

Güvenlik Hususları

## Security Notes

- SKILL.md'de API anahtarlarını asla sabit kodlamayın
- Ortam değişkenleri veya yapılandırma dosyaları kullanın
- Kullanıcı girdisini doğrulayın ve temizleyin
- API çağrılarını oran sınırına tabi tutun
- Hassas veri açığa çıkarmadan hataları günlüğe kaydedin

Performans Optimizasyonu

## Performance Tips

- API yanıtlarını önbelleğe alın (varsayılan 10 dakika)
- Birden fazla istek için asenkron işlemler kullanın
- Toplu işlemeyle araç çağrılarını en aza indirin
- Mevcutsa sıkıştırılmış yanıtlar kullanın

Özet

Skills geliştirmenin özü:

• SKILL.md ruhtur: Net tanım, doğru açıklama, yeterli örnek
• Tetikleyiciler anahtardır: Mantıklı tasarım, çakışmayı önleme, senaryo kapsama
• Araçlar yetenektir: Eksiksiz uygulama, hata işleme, performans optimizasyonu
• Dokümantasyon köprüdür: Kullanıcıların becerinizi anlamasına ve kullanmasına yardımcı olur

Bu bölümdeki öğrenimle Skills geliştirmenin temellerine hakim oldunuz ve OpenClaw için özel beceriler oluşturmaya başlayabilirsiniz.

Bu Bölümün Özeti:

• SKILL.md yapısını ve alanlarını anladınız
• Tetikleyici tasarım ilkelerini öğrendiniz
• Araç uygulama yöntemlerine hakim oldunuz
• Test ve yayınlama sürecini öğrendiniz
• Gelişmiş teknikleri ve en iyi uygulamaları incelediniz

Güncelleme Kayıtları:

• 2026-02-26: İlk sürüm yayınlandı, OpenClaw v2026.2 tabanlı

Seri Navigasyonu:

• ← Önceki: Skills Beceri Sistemi Detayları
• → Sonraki: Agent Kişilik Özelleştirmesi: AGENTS.md ve SOUL.md