claudient 0.1.0

package/skills/ai-engineering/claude-api.md

@@ -0,0 +1,248 @@
+# Claude API Skill
+
+## When to activate
+- Writing code that calls the Anthropic Claude API (Python or TypeScript SDK)
+- Implementing prompt caching, streaming, or batch processing
+- Designing multi-turn conversation management
+- Selecting the right Claude model (Haiku, Sonnet, Opus) for a task
+- Adding tool use / function calling to a Claude integration
+- Optimizing for cost or latency in a production Claude app
+
+## When NOT to use
+- OpenAI or other provider APIs — different SDK, different patterns
+- Generic LLM advice unrelated to the Anthropic API
+- Projects already using LangChain or LlamaIndex abstractions — address the abstraction layer instead
+
+## Instructions
+
+### Model selection guide
+| Model | Use when | Avoid when |
+|-------|----------|------------|
+| `claude-haiku-4-5-20251001` | Classification, extraction, routing, simple Q&A, high-volume low-cost | Complex reasoning, multi-step code generation |
+| `claude-sonnet-4-6` | General-purpose: code, analysis, writing, agentic workflows | Token-constrained budgets at massive scale |
+| `claude-opus-4-7` | Expert-level reasoning, nuanced judgment, complex long-form | Most tasks — usually Sonnet is sufficient |
+
+### Basic message call (Python)
+```python
+import anthropic
+
+client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env
+
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    system="You are a helpful assistant specialized in Python.",
+    messages=[
+        {"role": "user", "content": "Explain Python's GIL in 3 sentences."}
+    ]
+)
+print(message.content[0].text)
+```
+
+### Prompt caching (critical for cost)
+Prompt caching can reduce costs by up to 90% for repeated context. Cache stable content (system prompts, large documents, few-shot examples).
+
+```python
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    system=[
+        {
+            "type": "text",
+            "text": "You are a code review assistant. Here are our coding standards: ...",
+            "cache_control": {"type": "ephemeral"}  # Cache this block
+        }
+    ],
+    messages=[
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "text",
+                    "text": large_document,
+                    "cache_control": {"type": "ephemeral"}  # Also cache the document
+                },
+                {
+                    "type": "text",
+                    "text": "Summarize the key points."
+                }
+            ]
+        }
+    ]
+)
+# Check cache usage in response
+print(message.usage.cache_read_input_tokens)   # tokens read from cache
+print(message.usage.cache_creation_input_tokens)  # tokens written to cache
+```
+
+Cache rules:
+- Minimum cacheable block: 1024 tokens (Sonnet/Opus), 2048 tokens (Haiku)
+- Cache TTL: 5 minutes
+- Only the last `cache_control` block in a message array matters — cache points are cumulative
+
+### Streaming
+```python
+with client.messages.stream(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": prompt}]
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="", flush=True)
+
+# Or with events:
+with client.messages.stream(...) as stream:
+    for event in stream:
+        if event.type == "content_block_delta":
+            print(event.delta.text, end="")
+        elif event.type == "message_stop":
+            print()  # newline when done
+```
+
+### Tool use
+```python
+tools = [
+    {
+        "name": "get_weather",
+        "description": "Get current weather for a city",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "city": {"type": "string", "description": "City name"},
+                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
+            },
+            "required": ["city"]
+        }
+    }
+]
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    tools=tools,
+    messages=[{"role": "user", "content": "What's the weather in Paris?"}]
+)
+
+# Check if Claude wants to use a tool
+if response.stop_reason == "tool_use":
+    tool_use = next(b for b in response.content if b.type == "tool_use")
+    tool_result = call_tool(tool_use.name, tool_use.input)
+
+    # Continue conversation with tool result
+    follow_up = client.messages.create(
+        model="claude-sonnet-4-6",
+        max_tokens=1024,
+        tools=tools,
+        messages=[
+            {"role": "user", "content": "What's the weather in Paris?"},
+            {"role": "assistant", "content": response.content},
+            {
+                "role": "user",
+                "content": [{
+                    "type": "tool_result",
+                    "tool_use_id": tool_use.id,
+                    "content": json.dumps(tool_result)
+                }]
+            }
+        ]
+    )
+```
+
+### Multi-turn conversation
+```python
+class Conversation:
+    def __init__(self, system: str, model: str = "claude-sonnet-4-6"):
+        self.client = anthropic.Anthropic()
+        self.model = model
+        self.system = system
+        self.messages: list[dict] = []
+
+    def chat(self, user_message: str, max_tokens: int = 1024) -> str:
+        self.messages.append({"role": "user", "content": user_message})
+        response = self.client.messages.create(
+            model=self.model,
+            max_tokens=max_tokens,
+            system=self.system,
+            messages=self.messages,
+        )
+        assistant_message = response.content[0].text
+        self.messages.append({"role": "assistant", "content": assistant_message})
+        return assistant_message
+```
+
+### Batch processing
+```python
+from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
+from anthropic.types.messages.batch_create_params import Request
+
+requests = [
+    Request(
+        custom_id=f"review-{i}",
+        params=MessageCreateParamsNonStreaming(
+            model="claude-haiku-4-5-20251001",
+            max_tokens=256,
+            messages=[{"role": "user", "content": f"Classify: {review}"}],
+        )
+    )
+    for i, review in enumerate(reviews)
+]
+
+batch = client.messages.batches.create(requests=requests)
+print(f"Batch ID: {batch.id}")
+
+# Poll for results (or use webhooks)
+import time
+while True:
+    batch = client.messages.batches.retrieve(batch.id)
+    if batch.processing_status == "ended":
+        break
+    time.sleep(60)
+
+for result in client.messages.batches.results(batch.id):
+    print(result.custom_id, result.result.message.content[0].text)
+```
+
+### Error handling and retries
+```python
+from anthropic import APIStatusError, APITimeoutError, RateLimitError
+
+def call_with_retry(client, **kwargs, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            return client.messages.create(**kwargs)
+        except RateLimitError:
+            wait = 2 ** attempt
+            time.sleep(wait)
+        except APITimeoutError:
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(1)
+        except APIStatusError as e:
+            if e.status_code >= 500 and attempt < max_retries - 1:
+                time.sleep(2 ** attempt)
+            else:
+                raise
+```
+
+### Cost optimization checklist
+- Use Haiku for classification, routing, and simple extraction tasks
+- Enable prompt caching for any system prompt > 1024 tokens
+- Use batch API for offline/async workloads — 50% cost reduction
+- Set `max_tokens` to the minimum needed — you pay for output tokens generated
+- Cache large documents in the user message, not just the system prompt
+- Monitor `cache_read_input_tokens` vs `input_tokens` ratio — target >80% for stable contexts
+
+## Example
+
+**User:** Build a Python class that classifies customer support tickets into categories using Claude, with prompt caching for the category list and streaming for the explanation.
+
+**Expected output:**
+- `TicketClassifier` class with `ANTHROPIC_API_KEY` from env
+- System prompt with all categories cached via `cache_control: ephemeral`
+- `classify(ticket_text)` → returns `{category: str, confidence: str}` parsed from structured output
+- `classify_and_explain(ticket_text)` → streams the explanation to stdout
+- Uses `claude-haiku-4-5-20251001` for classification (cost-efficient), `claude-sonnet-4-6` for explanation
+
+---
+
+> **Work with us:** Claudient is backed by [Uitbreiden](https://uitbreiden.com/) — we build AI products and B2B solutions with developer communities. [uitbreiden.com](https://uitbreiden.com/)

package/skills/ai-engineering/de/agent-construction.md

@@ -0,0 +1,287 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../agent-construction.md).
+
+# Agent Construction Skill
+
+## Wann aktivieren
+- Ein Multi-Agent-System mit Claude entwerfen (Orchestrator + Subagenten)
+- Einen Claude-gestützten Agenten bauen, der Tools über mehrere Turns verwendet
+- Speicher für einen langlebigen Agenten entwerfen (In-Kontext vs. extern)
+- Agentenfehler, Wiederholungen und Abbruchbedingungen behandeln
+- Agenten-Handoffs zwischen spezialisierten Subagenten implementieren
+
+## Wann NICHT verwenden
+- Einzelne Claude API-Aufrufe — der Claude API Skill reicht aus
+- Einfache Chatbots ohne Tool Use oder autonome Entscheidungsfindung
+- LangChain/LlamaIndex-Abstraktionen — die Abstraktionsebene direkt ansprechen
+
+## Anweisungen
+
+### Agenten-Architekturmuster
+
+**Einzelner Agent mit Tools** — eine Claude-Instanz, mehrere Tools, Schleife bis Aufgabe erledigt:
+```
+User → Agent → [Tool A] → [Tool B] → Agent → User
+```
+
+**Orchestrator + Subagenten** — ein Elternteil spawnt spezialisierte Kinder:
+```
+User → Orchestrator → [ResearchAgent] → [WriterAgent] → Orchestrator → User
+```
+
+**Pipeline** — Agenten geben Ergebnisse der Reihe nach weiter:
+```
+User → Agent1(classify) → Agent2(extract) → Agent3(generate) → User
+```
+
+Die einfachste Architektur wählen, die das Problem löst. Einzelner Agent mit Tools löst die meisten Fälle.
+
+### Tool-Design
+```python
+# Tool-Definitionen für Multi-Turn-Agenten-Schleife
+tools = [
+    {
+        "name": "search_web",
+        "description": "Search the web for current information. Use when you need facts not in your training data.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query"}
+            },
+            "required": ["query"]
+        }
+    },
+    {
+        "name": "read_file",
+        "description": "Read contents of a file by path.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Absolute file path"}
+            },
+            "required": ["path"]
+        }
+    },
+    {
+        "name": "write_file",
+        "description": "Write content to a file. Creates the file if it doesn't exist.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "content": {"type": "string"}
+            },
+            "required": ["path", "content"]
+        }
+    }
+]
+```
+
+Tool-Design-Regeln:
+- Die Beschreibung muss Claude mitteilen, WANN es verwendet werden soll, nicht nur was es tut
+- `input_schema` minimal halten — nur erforderliche Felder, kein optionaler Lärm
+- Strukturierte Daten zurückgeben (JSON), keine Prosa, damit Claude sie zuverlässig verwenden kann
+- Ein Tool pro Aktion — Lesen+Schreiben nicht in ein Tool bündeln
+
+### Agenten-Schleife
+```python
+import anthropic
+import json
+
+client = anthropic.Anthropic()
+
+def run_agent(task: str, max_iterations: int = 20) -> str:
+    messages = [{"role": "user", "content": task}]
+    
+    for iteration in range(max_iterations):
+        response = client.messages.create(
+            model="claude-sonnet-4-6",
+            max_tokens=4096,
+            system=AGENT_SYSTEM_PROMPT,
+            tools=tools,
+            messages=messages,
+        )
+        
+        # Antwort des Assistenten anhängen
+        messages.append({"role": "assistant", "content": response.content})
+        
+        if response.stop_reason == "end_turn":
+            # Finale Textantwort extrahieren
+            return next(b.text for b in response.content if hasattr(b, "text"))
+        
+        if response.stop_reason == "tool_use":
+            # Alle Tool-Aufrufe in dieser Antwort ausführen
+            tool_results = []
+            for block in response.content:
+                if block.type == "tool_use":
+                    result = execute_tool(block.name, block.input)
+                    tool_results.append({
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": json.dumps(result) if not isinstance(result, str) else result
+                    })
+            
+            messages.append({"role": "user", "content": tool_results})
+        else:
+            # Unerwarteter Stopp-Grund
+            break
+    
+    raise RuntimeError(f"Agent exceeded {max_iterations} iterations without completing")
+
+
+def execute_tool(name: str, inputs: dict) -> any:
+    match name:
+        case "search_web":
+            return search(inputs["query"])
+        case "read_file":
+            return Path(inputs["path"]).read_text()
+        case "write_file":
+            Path(inputs["path"]).write_text(inputs["content"])
+            return {"success": True, "path": inputs["path"]}
+        case _:
+            return {"error": f"Unknown tool: {name}"}
+```
+
+### System-Prompt für Agenten
+```
+AGENT_SYSTEM_PROMPT = """You are an autonomous agent completing tasks step by step.
+
+Approach:
+1. Analyze the task before acting
+2. Use the minimum tools necessary
+3. Check your work before declaring done
+4. If a tool returns an error, diagnose and retry once — if it fails again, report the error
+
+Stopping conditions — declare "DONE: <result>" when:
+- The task is fully complete
+- You've hit an unrecoverable error after retrying
+- You've been asked to do something harmful or impossible
+
+Never loop more than 3 times on the same tool call with the same inputs.
+"""
+```
+
+### Speichermuster
+
+**In-Kontext-Speicher** (Nachrichten-Array) — für einzelne Sitzung, kleinen State:
+```python
+# Zusammenfassen wenn Kontext zu groß wird
+if count_tokens(messages) > 150_000:
+    summary = summarize_messages(messages[:-5])  # letzte 5 Turns behalten
+    messages = [
+        {"role": "user", "content": f"[Previous context summary]\n{summary}"},
+        {"role": "assistant", "content": "Understood. Continuing from where we left off."},
+        *messages[-5:]
+    ]
+```
+
+**Externer Speicher** (für Multi-Session-Agenten):
+```python
+# Einfacher dateibasierter Speicher
+class AgentMemory:
+    def __init__(self, path: str):
+        self.path = Path(path)
+        self.data = json.loads(self.path.read_text()) if self.path.exists() else {}
+
+    def remember(self, key: str, value: any):
+        self.data[key] = {"value": value, "timestamp": datetime.utcnow().isoformat()}
+        self.path.write_text(json.dumps(self.data, indent=2))
+
+    def recall(self, key: str) -> any:
+        entry = self.data.get(key)
+        return entry["value"] if entry else None
+
+    def as_context(self) -> str:
+        if not self.data:
+            return ""
+        lines = [f"- {k}: {v['value']}" for k, v in self.data.items()]
+        return "Known context:\n" + "\n".join(lines)
+```
+
+### Orchestrator-Muster
+```python
+def orchestrate(task: str) -> str:
+    # Schritt 1: Planungs-Agent zerlegt die Aufgabe
+    plan = run_subagent(
+        model="claude-sonnet-4-6",
+        system="You are a planner. Decompose tasks into numbered steps.",
+        task=f"Decompose this task into steps: {task}",
+        tools=[]  # Keine Tools für die Planung benötigt
+    )
+
+    # Schritt 2: Jeden Schritt mit spezialisierten Agenten ausführen
+    results = []
+    for step in parse_steps(plan):
+        agent_type = classify_step(step)  # "research" | "code" | "write"
+        result = run_subagent(
+            model=agent_model(agent_type),
+            system=agent_system_prompt(agent_type),
+            task=step,
+            tools=agent_tools(agent_type),
+            context="\n".join(results)  # Kontext aus vorherigen Schritten mitgeben
+        )
+        results.append(f"Step result: {result}")
+
+    # Schritt 3: Synthese-Agent kombiniert Ergebnisse
+    return run_subagent(
+        model="claude-sonnet-4-6",
+        system="You are a synthesizer. Combine step results into a final answer.",
+        task=f"Original task: {task}\n\nStep results:\n" + "\n".join(results),
+        tools=[]
+    )
+```
+
+### Fehlerbehandlung und Abbruchbedingungen
+```python
+class AgentError(Exception):
+    pass
+
+class MaxIterationsError(AgentError):
+    pass
+
+class ToolFailureError(AgentError):
+    pass
+
+def execute_tool_safe(name: str, inputs: dict, consecutive_failures: dict) -> dict:
+    try:
+        result = execute_tool(name, inputs)
+        consecutive_failures[name] = 0
+        return {"success": True, "result": result}
+    except Exception as e:
+        consecutive_failures[name] = consecutive_failures.get(name, 0) + 1
+        if consecutive_failures[name] >= 3:
+            raise ToolFailureError(f"Tool {name} failed 3 consecutive times: {e}")
+        return {"success": False, "error": str(e), "retry": True}
+```
+
+### Handoff-Muster
+```python
+# Eltern-Agent übergibt Kontext explizit — Subagenten haben keinen Session-Speicher
+def handoff_to_specialist(context: dict, task: str, specialist: str) -> str:
+    handoff_prompt = f"""
+Context from orchestrator:
+{json.dumps(context, indent=2)}
+
+Your task:
+{task}
+"""
+    return run_subagent(
+        system=SPECIALIST_PROMPTS[specialist],
+        task=handoff_prompt,
+        tools=SPECIALIST_TOOLS[specialist]
+    )
+```
+
+## Beispiel
+
+**Benutzer:** Einen Recherche-Agenten bauen, der ein Thema annimmt, das Web nach 3 Quellen durchsucht, jede URL liest und eine 500-Wörter-Zusammenfassung mit Zitaten in eine Datei schreibt.
+
+**Erwartete Ausgabe:**
+- `tools`-Liste: `search_web`, `fetch_url`, `write_file`
+- System-Prompt: weist Agenten an, zu suchen → 3 URLs abrufen → synthetisieren → Datei schreiben, bevor fertig erklärt wird
+- `run_agent(task)`-Schleife mit `max_iterations=15`
+- Fehlerbehandlung: wenn `fetch_url` scheitert, nächstes Suchergebnis versuchen
+- Finale Ausgabe: Pfad zur geschriebenen Zusammenfassungsdatei
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. [uitbreiden.com](https://uitbreiden.com/)