Claude Skills’in İç Yapısı: Claude’u Genişleten Özel Modüller

Claude Geliştirici Platformu (API)

Claude skills, Claude API aracılığıyla da erişilebilir. Bu bölümde, Claude API’siyle Claude uygulama arayüzünü nasıl taklit edebileceğimizi inceleyeceğiz.

Adım 1: Önkoşullar

Önce tüm çalışma zamanı bağımlılıklarını yükleyin:

• Anthropic, Claude Messages API için

• pandas ve openpyxl, Excel’den zaman çizelgelerini okumak için

• reportlab, yerelde yedek bir PDF fatura üretmek için 

!pip -q install anthropic pandas openpyxl reportlab

Artık tüm bağımlılıklar kurulu.  Sırada API anahtarımızı yapılandırmak var.

Adım 2: API anahtarınızı yapılandırın

Messages API’yi çağırmadan önce kimlik doğrulaması yapmamız gerekir. Bu adım, API anahtarıyla tek, yeniden kullanılabilir bir anthropic.Client oluşturur. 

import os, json, sys, re
import anthropic
from datetime import datetime, timedelta
API_KEY = "YOUR_ANTHROPIC_API_KEY"
client = anthropic.Client(api_key=API_KEY)

Anthropic Console’a giriş yapın ve Ayarlar altındaki API keys sekmesini bulun. Create Key’e tıklayın ve Anthropic API anahtarınızı kopyalayın.

Kaynak: Anthropic API

Not: Kişisel kullanım için özel bir not defteri kullanıyorsanız API Anahtarınızı ekleyin. Aksi takdirde, anahtarınızın not defteri veya günlüklerde ifşa olmaması için güvenli bir ortam değişkeni kullanın.

Yukarıdaki kod, Anthropic SDK istemcisini başlatır ve ortamı ayarlar. İstemci nesnesi, sonraki tüm Messages API çağrıları için yeniden kullanılır.

Adım 3: Verilerin ön işlenmesi

Bu adımda, timesheet.xlsx sayfamızı Skill’in tüketebileceği temiz ve öngörülebilir bir JSON nesnesine dönüştüreceğiz. Bu, aşağı akış mantığını basit tutar ve kırılgan istem ayrıştırmadan kaçınır.

def load_invoice_from_timesheet(excel_path):
    import pandas as pd
    df = pd.read_excel(excel_path)
    df.columns = df.columns.str.strip()  
    invoice_period = "2025-10"
    if 'Date' in df.columns:
        first_date = str(df['Date'].iloc[0])
        date_match = re.search(r'(\d{2})\s+(\w+)\s+(\d{4})', first_date)
        if date_match:
            month_name = date_match.group(2)
            year = date_match.group(3)
            month_num = datetime.strptime(month_name[:3], '%b').month
            invoice_period = f"{year}-{month_num:02d}"   
    article_col = next((col for col in df.columns if 'article' in col.lower() and 'name' in col.lower()), None)
    amount_col = next((col for col in df.columns if 'amount' in col.lower()), None)
    topic_col = next((col for col in df.columns if 'topic' in col.lower()), None)
    line_items = []
    timesheet_articles = []
    
    for idx, row in df.iterrows():
        if pd.isna(row.get(article_col)) or row.get(article_col) == '':
            continue    
        article_name = str(row[article_col]).strip()
        amount = row.get(amount_col, 0) 
        if isinstance(amount, str):
            amount = float(amount.replace('$', '').replace(',', '').strip())
        line_items.append({
            "title": article_name,
            "rate_type": "flat",
            "qty": 1,
            "rate": float(amount)
        })  
        timesheet_articles.append({
            "title": article_name,
            "topic": str(row.get(topic_col, 'N/A')) if topic_col else 'N/A'
        })
    return {
        "client_name": "Client",
        "billing_contact": "billing@example.com",
        "invoice_period": invoice_period,
        "currency": "USD",
        "payment_terms": "Net-30",
        "line_items": line_items,
        "discount_pct": 0.0,
        "tax_pct": 0.0,
        "timesheet": timesheet_articles
    }

load_invoice_from_timesheet işlevi, yüklenen bir Excel dosyasını normalleştirilmiş bir fatura JSON yüküne dönüştürür.

• Excel’i pandas ile okur ve sütun başlıklarını normalize eder.

• Daha sonra kod, bir regex ve ay ayrıştırması kullanarak ilk Date satırından (varsa) invoice_period’ü çıkarır.

• Son olarak, büyük/küçük harfe duyarsız şekilde makale başlığı, tutar ve konu için sütun adlarını tespit eder.

• Bu iki yapı üretir:

• line_items: Faturalama hesaplamaları için kullanılır (burada makale başına sabit ücret).

• timesheet: İsteğe bağlı bir ek için düz bir {title, topic} listesi.

• Regex (\d{2})\s+(\w+)\s+(\d{4}), 01 Oct 2025 gibi biçimleri bekler; sayfanız başka bir biçim kullanıyorsa bunu uyarlayın.

• Eksik sütun/değerler boş satırları atlayarak ele alınır; gerekirse kodu hızlı şekilde hata verecek biçimde genişletebilirsiniz.

Girdimiz artık hazır. Sırada, işlenmiş zaman çizelgesini düzenlenebilir bir faturaya dönüştürmek için API aracılığıyla Claude Skill’ini çağırmak var.

Adım 4: Yardımcı işlevler

Bu bölümde, bir Skill çalıştırması sırasında Claude’un talep ettiği araç yürütmeyi simüle eden iki yardımcı işlev tanımlıyoruz. 

def execute_bash_tool(command):
    try:
        dangerous = ['rm -rf /', 'sudo', 'chmod', 'mkfs', '> /dev/']
        if any(d in command for d in dangerous):
            return f"Error: Command blocked for safety: {command}"
        result = subprocess.run(
            command, 
            shell=True, 
            capture_output=True, 
            text=True, 
            timeout=30,
            cwd=tempfile.gettempdir()
        )    
        output = result.stdout if result.stdout else result.stderr
        return output if output else "Command executed successfully"
    except subprocess.TimeoutExpired:
        return "Error: Command timed out"
    except Exception as e:
        return f"Error executing command: {str(e)}"
def execute_text_editor_tool(params):
    try:
        command = params.get('command')
        path = params.get('path')   
        if command == 'create':
            file_text = params.get('file_text', '')
            os.makedirs(os.path.dirname(path) if os.path.dirname(path) else '.', exist_ok=True)
            with open(path, 'w') as f:
                f.write(file_text)
            return f"File created: {path}"
        elif command == 'view':
            if os.path.exists(path):
                with open(path, 'r') as f:
                    content = f.read()
                return content[:1000] 
            return f"Error: File not found: {path}"   
        elif command == 'str_replace':
            if os.path.exists(path):
                with open(path, 'r') as f:
                    content = f.read()
                old_str = params.get('old_str', '')
                new_str = params.get('new_str', '')
                content = content.replace(old_str, new_str)
                with open(path, 'w') as f:
                    f.write(content)
                return f"File updated: {path}"
            return f"Error: File not found: {path}"    
        return f"Unknown command: {command}"
    except Exception as e:
        return f"Error: {str(e)}"

execute_bash_tool işlevi, Skill odaklı eylemler için güvenli bir bash aracını simüle eder. Önce bir güvenlik kapısı olarak rm -rf /, sudo, chmod, mkfs vb. tehlikeli kalıpları engeller ve komutu, OS’in geçici dizininde, 30 saniyelik zorunlu zaman aşımıyla subprocess.run() ile çalıştırır.

execute_text_editor_tool işlevi, Skills tarafından kullanılan asgari bir metin düzenleme arayüzü sağlar. Üç komutu destekler: create ( file_text ile yeni bir dosya yazmak), view (bir dosyanın en fazla 1.000 karakterini döndürmek) ve str_replace (new_str ile yerinde değiştirme). Ayrıca create için üst klasörleri otomatik oluşturur, view ve str_replace için dosya varlığını kontrol eder ve güncellemeleri diske yazar.

Bu yardımcılar, yerel olarak korumalı raylarla bir araç kullanım döngüsünü tamamlamanızı sağlar. Artık Skill, sisteminizi riske atmadan fatura oluşturma sırasında dosya düzenlemeleri veya kabuk eylemleri talep edebilir.

Adım 5: Skill’i API üzerinden çağırın 

Bu adım, Claude Messages API üzerinden uçtan uca fatura oluşturmayı yürütür. Yapılandırılmış bir istek gönderir, araç kullanımını etkinleştirir, Claude’un talep ettiği araç çağrılarını yinelemeli olarak yürütür ve sonunda çalışma ve geçici dizinlerden oluşturulan PDF dosyalarını toplar.

def generate_invoice_with_claude(invoice): 
    user_text = f"""Generate a professional PDF invoice with the following data:
Client: {invoice['client_name']}
Period: {invoice['invoice_period']}
Currency: {invoice['currency']}
Payment Terms: {invoice['payment_terms']}
Line Items:
{json.dumps(invoice['line_items'], indent=2)}
Timesheet Articles:
{json.dumps(invoice['timesheet'], indent=2)}
Please create a professional PDF invoice with:
1. Invoice header with invoice number (INV-{invoice['invoice_period'].replace('-', '')}-001)
2. Client billing information
3. Line items table with amounts
4. Subtotal and total calculations
5. Timesheet section showing all articles and topics
Save the PDF as: invoice_{invoice['client_name'].lower()}_{invoice['invoice_period']}.pdf
""" 
    tools = [
        {"type": "bash_20250124", "name": "bash"},
        {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}
    ]
    messages = [{"role": "user", "content": user_text}]
    iteration = 0
    max_iterations = 15   
    while iteration < max_iterations:
        iteration += 1
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=8192,
            tools=tools,
            messages=messages
        )   
        messages.append({"role": "assistant", "content": response.content}) 
        if response.stop_reason == "end_turn":
            break     
        if response.stop_reason == "tool_use":
            tool_results = []    
            for block in response.content:
                if block.type == "tool_use":
                    tool_name = block.name
                    tool_input = block.input
                    if tool_name == "bash":
                        result = execute_bash_tool(tool_input.get('command', ''))
                    elif tool_name == "str_replace_based_edit_tool":
                        result = execute_text_editor_tool(tool_input)
                    else:
                        result = f"Unknown tool: {tool_name}" 
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })
            messages.append({"role": "user", "content": tool_results})
        else:
            break
    pdf_files = []
    for file in os.listdir('.'):
        if file.endswith('.pdf') and 'invoice' in file.lower():
            pdf_files.append(file)
    for file in os.listdir(tempfile.gettempdir()):
        if file.endswith('.pdf') and 'invoice' in file.lower():
            temp_path = os.path.join(tempfile.gettempdir(), file)
            import shutil
            dest_path = os.path.join('.', file)
            shutil.copy2(temp_path, dest_path)
            pdf_files.append(file)   
    return pdf_files
def main():
    if len(sys.argv) < 2:
        print("Usage: python app.py <timesheet.xlsx>")
        sys.exit(1)    
    excel_file = sys.argv[1]  
    if not os.path.exists(excel_file):
        print(f"Error: File not found: {excel_file}")
        sys.exit(1)    
    try:
        invoice = load_invoice_from_timesheet(excel_file)
        pdf_files = generate_invoice_with_claude(invoice)    
        if pdf_files:
            for pdf in pdf_files:
                print(f"Invoice generated: {os.path.abspath(pdf)}")
        else:
            print("Error: No PDF file was generated.")     
    except Exception as e:
        print(f"Error: {e}")
        import traceback
        traceback.print_exc()
        sys.exit(1)
if __name__ == "__main__":
    main()

generate_invoice_with_claude işlevi, normalleştirilmiş faturayı Claude API’sine gönderir ve Skill yürütmesini uçtan uca sürer. Kodun yaptıkları şunlardır:

• user_text içinde, müşteri, dönem, para birimi, koşullar, kalemler ve zaman çizelgesi girdilerini; ayrıca başlık, tablolar, toplamlar ve dosya adı gibi açık çıktı gereksinimlerini barındıran net bir metin oluşturur.

• Ardından bir bash_number ve text_editor_number tanımlayarak araç yürütmeyi etkinleştirir; isteği gönderen, stop_reason’ı inceleyen ve tool_use istendiğinde yerel yardımcıları çağırıp alışverişe devam etmek için tool_result bloklarını döndüren araç farkındalığı olan bir mesaj döngüsü kullanır.

• Son olarak, end_turn olduğunda ya da döngü sınırına ulaşıldığında durur; ardından çalışma dizinini ve OS’in geçici dizinini invoice*.pdf ile eşleşen dosyalar için tarar. Geçici yapıtları proje klasörüne kopyalar ve bulunan PDF’lerin listesini döndürür.

• main işlevi basit bir CLI komutu sağlar: python app.py <timesheet.xlsx>; girdi yolunu doğrular, ardından ardışığı çalıştırır: yükü oluşturmak için load_invoice_from_timesheet(...) ve Skill’i çağırıp PDF’leri toplamak için generate_invoice_with_claude(...).

Bunlar yerindeyken, API çağrısı müşteri-ready bir PDF üretmelidir. Dosya görünmüyorsa, tool_result günlüklerini ve Skill yapılandırmasını gözden geçirip küçük bir test sayfasıyla yeniden deneyin.

Sonuç

Artık Claude Skills tarafından desteklenen çalışan bir Otomatik Fatura Oluşturucuya sahipsiniz ve API, ham e-tabloları müşteri-ready faturalara dönüştürebiliyor. Bu demo, Skills’in en iyi yaptığı şeyi sergiliyor: taşınabilir kurulum, otomatik etkinleştirme, deterministik kod yürütme ve her dizide istemleri yeniden oluşturmadan uygulama ve API genelinde tutarlı sonuçlar. Claude Skills, bağlamlar arasında tutarlı çıktılar döndürür; bu, yeniden kullanılabilir alan bilgisi ve kod desteklidir. Skills kod çalıştırabilse de güvenliği yine de siz sağlamalısınız: yalnızca güvenilir Skill’leri etkinleştirin, kurum düzeyinde kontroller kullanın ve dağıtımdan önce güncellemeleri gözden geçirin.

Daha ileri gitmek için Anthropic’in Skills dokümantasyonunu ve sürümleme ile yükseltmeler için Console’u keşfedin; ardından uçtan uca iş akışları oluşturmak üzere birden fazla Skill’i bir araya getirmeye başlayın.