diff --git a/shims/ant-claude-for-chrome-mcp/index.ts b/shims/ant-claude-for-chrome-mcp/index.ts index 8bd4f57..e7487a6 100644 --- a/shims/ant-claude-for-chrome-mcp/index.ts +++ b/shims/ant-claude-for-chrome-mcp/index.ts @@ -12,14 +12,102 @@ export type Logger = { export type ClaudeForChromeContext = { serverName?: string logger?: Logger + [key: string]: unknown } -export const BROWSER_TOOLS: Array<{ name: string }> = [] +export const BROWSER_TOOLS: Array<{ name: string; description: string }> = [ + { + name: 'navigate', + description: 'Navigate a browser tab to a URL.', + }, + { + name: 'read_page', + description: 'Capture high-level page state from the active tab.', + }, + { + name: 'get_page_text', + description: 'Read visible page text from the active tab.', + }, + { + name: 'find', + description: 'Find a pattern within page content.', + }, + { + name: 'form_input', + description: 'Fill or update form inputs in the page.', + }, + { + name: 'computer', + description: 'Perform browser-scoped mouse and keyboard actions.', + }, + { + name: 'javascript_tool', + description: 'Run page-scoped JavaScript in the browser tab.', + }, + { + name: 'tabs_context_mcp', + description: 'List or inspect browser tabs.', + }, + { + name: 'tabs_create_mcp', + description: 'Create a new browser tab.', + }, + { + name: 'resize_window', + description: 'Resize the browser window.', + }, + { + name: 'upload_image', + description: 'Upload an image into the current page flow.', + }, + { + name: 'read_console_messages', + description: 'Read browser console messages.', + }, + { + name: 'read_network_requests', + description: 'Read captured network requests.', + }, + { + name: 'shortcuts_list', + description: 'List extension/browser shortcuts.', + }, + { + name: 'shortcuts_execute', + description: 'Execute a configured extension/browser shortcut.', + }, + { + name: 'gif_creator', + description: 'Create or manage simple browser recordings.', + }, + { + name: 'update_plan', + description: 'Update an in-browser action plan.', + }, +] + +export function createClaudeForChromeMcpServer(context: ClaudeForChromeContext) { + let closed = false + const handlers = new Map() -export function createClaudeForChromeMcpServer(_context: ClaudeForChromeContext) { return { - async connect() {}, - setRequestHandler() {}, - async close() {}, + async connect() { + context.logger?.warn( + 'Claude in Chrome MCP is running with a restored compatibility shim; browser actions are not available in this workspace.', + ) + }, + setRequestHandler(schema: unknown, handler: unknown) { + handlers.set(schema, handler) + }, + async close() { + closed = true + handlers.clear() + context.logger?.info( + 'Claude in Chrome MCP shim closed.', + ) + }, + get isClosed() { + return closed + }, } } diff --git a/shims/ant-computer-use-mcp/index.ts b/shims/ant-computer-use-mcp/index.ts index fd13383..f7364eb 100644 --- a/shims/ant-computer-use-mcp/index.ts +++ b/shims/ant-computer-use-mcp/index.ts @@ -5,32 +5,10 @@ export const DEFAULT_GRANT_FLAGS = { export const API_RESIZE_PARAMS = {} -export function targetImageSize(width: number, height: number) { - return [width, height] as const -} - -export function buildComputerUseTools() { - return [] as Array<{ name: string }> -} - -export function createComputerUseMcpServer() { - return { - async connect() {}, - setRequestHandler() {}, - async close() {}, - } -} - -export function bindSessionContext() { - return async () => ({ - is_error: true, - content: [ - { - type: 'text', - text: 'Computer use is unavailable in the restored development build.', - }, - ], - }) +export type ToolDef = { + name: string + description: string + inputSchema?: Record } export type DisplayGeometry = Record @@ -48,12 +26,170 @@ export type ScreenshotDims = { originX?: number originY?: number } -export type CuPermissionRequest = Record -export type CuPermissionResponse = Record +export type CuPermissionRequest = { + apps?: Array<{ bundleId?: string; displayName?: string }> + flags?: Record + tccState?: { accessibility?: boolean; screenRecording?: boolean } +} +export type CuPermissionResponse = { + granted: Array<{ bundleId?: string; displayName?: string; grantedAt?: string }> + denied: Array<{ bundleId?: string; displayName?: string }> + flags: Record +} export type CuCallToolResult = { is_error?: boolean - content?: Array<{ type: string; text?: string }> + content?: Array<{ + type: string + text?: string + mimeType?: string + data?: string + }> telemetry?: Record } -export type ComputerUseSessionContext = Record +export type ComputerUseSessionContext = { + onPermissionRequest?: ( + req: CuPermissionRequest, + signal?: AbortSignal, + ) => Promise | CuPermissionResponse + getAllowedApps?: () => Array<{ bundleId?: string; displayName?: string }> + getGrantFlags?: () => Record + [key: string]: unknown +} export type ComputerExecutor = Record + +function successText(text: string): CuCallToolResult { + return { + content: [{ type: 'text', text }], + } +} + +function errorText(text: string): CuCallToolResult { + return { + is_error: true, + content: [{ type: 'text', text }], + } +} + +export function targetImageSize(width: number, height: number) { + return [width, height] as const +} + +const TOOL_DEFS: ToolDef[] = [ + { + name: 'request_access', + description: + 'Request access to applications and computer-use permissions for this session.', + }, + { + name: 'list_granted_applications', + description: 'List applications currently granted for computer use.', + }, + { name: 'screenshot', description: 'Capture a screenshot.' }, + { name: 'zoom', description: 'Capture a zoomed screenshot region.' }, + { name: 'cursor_position', description: 'Read the current cursor position.' }, + { name: 'mouse_move', description: 'Move the mouse cursor.' }, + { name: 'left_click', description: 'Left click at a coordinate.' }, + { name: 'right_click', description: 'Right click at a coordinate.' }, + { name: 'middle_click', description: 'Middle click at a coordinate.' }, + { name: 'double_click', description: 'Double click at a coordinate.' }, + { name: 'triple_click', description: 'Triple click at a coordinate.' }, + { name: 'left_mouse_down', description: 'Press the left mouse button.' }, + { name: 'left_mouse_up', description: 'Release the left mouse button.' }, + { name: 'left_click_drag', description: 'Drag with the left mouse button.' }, + { name: 'scroll', description: 'Scroll at a coordinate or direction.' }, + { name: 'type', description: 'Type text through the active application.' }, + { name: 'key', description: 'Press a key or key chord.' }, + { name: 'hold_key', description: 'Hold one or more keys for a duration.' }, + { name: 'read_clipboard', description: 'Read clipboard text.' }, + { name: 'write_clipboard', description: 'Write clipboard text.' }, + { + name: 'open_application', + description: 'Open an application by bundle identifier.', + }, + { name: 'wait', description: 'Wait for a short duration.' }, + { + name: 'computer_batch', + description: 'Execute a sequence of computer-use actions.', + }, +] + +export function buildComputerUseTools() { + return TOOL_DEFS +} + +export function createComputerUseMcpServer( + adapter?: { logger?: { warn(message: string): void; info?(message: string): void } }, +) { + let closed = false + const handlers = new Map() + + return { + async connect() { + adapter?.logger?.warn( + 'Computer Use MCP is running with a restored compatibility shim; request_access works, but native desktop actions remain unavailable in this workspace.', + ) + }, + setRequestHandler(schema: unknown, handler: unknown) { + handlers.set(schema, handler) + }, + async close() { + closed = true + handlers.clear() + adapter?.logger?.info?.('Computer Use MCP shim closed.') + }, + get isClosed() { + return closed + }, + } +} + +export function bindSessionContext( + _adapter?: unknown, + _coordinateMode?: unknown, + ctx?: ComputerUseSessionContext, +) { + return async ( + name: string, + args: CuPermissionRequest | Record, + ): Promise => { + switch (name) { + case 'request_access': { + if (ctx?.onPermissionRequest) { + const response = await ctx.onPermissionRequest(args as CuPermissionRequest) + const grantedCount = Array.isArray(response.granted) + ? response.granted.length + : 0 + return successText( + grantedCount > 0 + ? `Computer-use access updated for ${grantedCount} application(s).` + : 'Computer-use access request completed.', + ) + } + return errorText( + 'Computer-use access approval is not configured in this restored workspace.', + ) + } + + case 'list_granted_applications': { + const apps = ctx?.getAllowedApps?.() ?? [] + if (apps.length === 0) { + return successText('No computer-use applications are currently granted.') + } + const names = apps + .map(app => app.displayName || app.bundleId || 'unknown') + .join(', ') + return successText(`Granted computer-use applications: ${names}`) + } + + case 'read_clipboard': + return errorText( + 'Clipboard access is unavailable in the restored computer-use shim.', + ) + + default: + return errorText( + `Computer-use tool "${name}" is not available in this restored workspace. The shim currently supports session approval flows, but not native desktop execution.`, + ) + } + } +} diff --git a/shims/ant-computer-use-mcp/types.ts b/shims/ant-computer-use-mcp/types.ts index 30f5bf7..ab2764b 100644 --- a/shims/ant-computer-use-mcp/types.ts +++ b/shims/ant-computer-use-mcp/types.ts @@ -6,10 +6,25 @@ export const DEFAULT_GRANT_FLAGS = { export type CoordinateMode = 'screen' | 'viewport' export type CuSubGates = Record export type Logger = { + silly?(message: string, ...args: unknown[]): void + debug?(message: string, ...args: unknown[]): void info(message: string): void warn(message: string): void error(message: string): void } -export type ComputerUseHostAdapter = Record -export type CuPermissionRequest = Record -export type CuPermissionResponse = Record +export type ComputerUseHostAdapter = { + logger?: Logger + executor?: Record + [key: string]: unknown +} +export type CuPermissionRequest = { + apps?: Array<{ bundleId?: string; displayName?: string }> + flags?: Record + tccState?: { accessibility?: boolean; screenRecording?: boolean } + [key: string]: unknown +} +export type CuPermissionResponse = { + granted: Array<{ bundleId?: string; displayName?: string; grantedAt?: string }> + denied: Array<{ bundleId?: string; displayName?: string }> + flags: Record +} diff --git a/src/commands/agents-platform/index.ts b/src/commands/agents-platform/index.ts index a53a0f7..af92c12 100644 --- a/src/commands/agents-platform/index.ts +++ b/src/commands/agents-platform/index.ts @@ -1,11 +1,19 @@ const agentsPlatform = { name: 'agents-platform', type: 'local', - description: 'Unavailable in restored development build.', + description: + 'Reserved internal command. This restored build keeps the command visible but does not include the original agents platform backend.', supportsNonInteractive: true, load: async () => ({ async call() { - return { type: 'skip' as const } + return { + type: 'text' as const, + value: + 'agents-platform is not included in this restored workspace.\n\n' + + 'The command shell is present so callers fail cleanly, but the ' + + 'internal backend that powers platform-managed agents was not ' + + 'recoverable from source maps.', + } }, }), } diff --git a/src/skills/bundled/claude-api/SKILL.md b/src/skills/bundled/claude-api/SKILL.md index 50688d3..eb1ec3e 100644 --- a/src/skills/bundled/claude-api/SKILL.md +++ b/src/skills/bundled/claude-api/SKILL.md @@ -1,3 +1,38 @@ # Claude API -Restored placeholder content. +Use this skill when the user is building against Anthropic APIs or SDKs, including `@anthropic-ai/sdk`, `anthropic`, or Agent SDK integrations. + +## What This Skill Covers + +- Messages API basics across supported languages +- Streaming responses and incremental rendering +- Prompt caching for repeated context +- Tool use and agent-style orchestration +- Batches and Files API workflows +- Model selection and error handling + +## Working Rules + +- Prefer Anthropic official docs and SDK idioms over generic LLM advice. +- Keep examples aligned with the user’s detected language when possible. +- Use the language-specific `README.md` for standard request flow, auth, and request shape. +- Use the shared docs for topics that cut across all SDKs, such as models, caching, tool-use concepts, and error codes. +- If the user asks for exact current model IDs, feature availability, or pricing, verify against Anthropic’s live docs before answering. + +## Reading Guide + +- Basic request/response flow: `{lang}/claude-api/README.md` +- Streaming output: `{lang}/claude-api/streaming.md` +- Tool use: `shared/tool-use-concepts.md` and `{lang}/claude-api/tool-use.md` +- Prompt caching: `shared/prompt-caching.md` +- Batch processing: `{lang}/claude-api/batches.md` +- File upload flows: `{lang}/claude-api/files-api.md` +- Model choice or naming: `shared/models.md` +- API and SDK failures: `shared/error-codes.md` +- Live sources for fresh answers: `shared/live-sources.md` + +## Response Style + +- Give production-usable examples, not pseudocode, when the user asks for implementation help. +- Call out when you are making an inference from the docs rather than repeating an explicit guarantee. +- If the user’s request depends on fast-changing details such as model names or pricing, browse Anthropic docs and cite the relevant page. diff --git a/src/skills/bundled/claude-api/csharp/claude-api.md b/src/skills/bundled/claude-api/csharp/claude-api.md index 3212a30..6080790 100644 --- a/src/skills/bundled/claude-api/csharp/claude-api.md +++ b/src/skills/bundled/claude-api/csharp/claude-api.md @@ -1,3 +1,65 @@ -# CSharp Claude API +# C# Claude API -Restored placeholder content. +Use the Messages API over HTTPS when you need a minimal C# integration. + +## Prerequisites + +- Set `ANTHROPIC_API_KEY` +- Use the Messages endpoint: `https://api.anthropic.com/v1/messages` +- Send headers: + - `x-api-key` + - `anthropic-version: 2023-06-01` + - `content-type: application/json` + +## Minimal Example + +```csharp +using System.Net.Http.Headers; +using System.Text; +using System.Text.Json; + +var apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY"); +using var http = new HttpClient(); + +http.DefaultRequestHeaders.Add("x-api-key", apiKey); +http.DefaultRequestHeaders.Add("anthropic-version", "2023-06-01"); +http.DefaultRequestHeaders.Accept.Add( + new MediaTypeWithQualityHeaderValue("application/json") +); + +var payload = new +{ + model = "{{SONNET_ID}}", + max_tokens = 512, + messages = new[] + { + new + { + role = "user", + content = "Summarize why prompt caching helps repeated requests." + } + } +}; + +var body = new StringContent( + JsonSerializer.Serialize(payload), + Encoding.UTF8, + "application/json" +); + +var response = await http.PostAsync( + "https://api.anthropic.com/v1/messages", + body +); +response.EnsureSuccessStatusCode(); + +var json = await response.Content.ReadAsStringAsync(); +Console.WriteLine(json); +``` + +## Notes + +- Read the first `content` block with `type: "text"` for normal text output. +- Reuse one `HttpClient` across requests. +- Add retries around `429` and `5xx` responses. +- For structured output, keep your instructions explicit and validate the JSON after receipt. diff --git a/src/skills/bundled/claude-api/curl/examples.md b/src/skills/bundled/claude-api/curl/examples.md index 1301a73..961282e 100644 --- a/src/skills/bundled/claude-api/curl/examples.md +++ b/src/skills/bundled/claude-api/curl/examples.md @@ -1,3 +1,61 @@ -# Curl Examples +# cURL Examples -Restored placeholder content. +Use these when you want a raw HTTP baseline before moving to an SDK. + +## Basic Message + +```bash +curl https://api.anthropic.com/v1/messages \ + --header "x-api-key: $ANTHROPIC_API_KEY" \ + --header "anthropic-version: 2023-06-01" \ + --header "content-type: application/json" \ + --data '{ + "model": "{{SONNET_ID}}", + "max_tokens": 256, + "messages": [ + {"role": "user", "content": "Write a two-line release note summary."} + ] + }' +``` + +## With System Prompt + +```bash +curl https://api.anthropic.com/v1/messages \ + --header "x-api-key: $ANTHROPIC_API_KEY" \ + --header "anthropic-version: 2023-06-01" \ + --header "content-type: application/json" \ + --data '{ + "model": "{{SONNET_ID}}", + "max_tokens": 256, + "system": "You are a terse technical assistant.", + "messages": [ + {"role": "user", "content": "Explain eventual consistency in one paragraph."} + ] + }' +``` + +## JSON Output Pattern + +```bash +curl https://api.anthropic.com/v1/messages \ + --header "x-api-key: $ANTHROPIC_API_KEY" \ + --header "anthropic-version: 2023-06-01" \ + --header "content-type: application/json" \ + --data '{ + "model": "{{SONNET_ID}}", + "max_tokens": 256, + "messages": [ + { + "role": "user", + "content": "Return JSON only: {\"severity\": string, \"summary\": string} for a database outage." + } + ] + }' +``` + +## Notes + +- Start with cURL when debugging headers, auth, or payload shape. +- Move to a language client once the request body is stable. +- For streaming, batches, and files, use the corresponding skill docs instead of extending these one-off shell commands. diff --git a/src/skills/bundled/claude-api/go/claude-api.md b/src/skills/bundled/claude-api/go/claude-api.md index 4defa50..76f3d8e 100644 --- a/src/skills/bundled/claude-api/go/claude-api.md +++ b/src/skills/bundled/claude-api/go/claude-api.md @@ -1,3 +1,60 @@ # Go Claude API -Restored placeholder content. +Go works well with the raw Messages API using `net/http`. + +## Minimal Example + +```go +package main + +import ( + "bytes" + "fmt" + "io" + "net/http" + "os" +) + +func main() { + body := []byte(`{ + "model": "{{SONNET_ID}}", + "max_tokens": 512, + "messages": [ + {"role": "user", "content": "Draft a concise deployment checklist."} + ] + }`) + + req, err := http.NewRequest( + http.MethodPost, + "https://api.anthropic.com/v1/messages", + bytes.NewReader(body), + ) + if err != nil { + panic(err) + } + + req.Header.Set("x-api-key", os.Getenv("ANTHROPIC_API_KEY")) + req.Header.Set("anthropic-version", "2023-06-01") + req.Header.Set("content-type", "application/json") + + res, err := http.DefaultClient.Do(req) + if err != nil { + panic(err) + } + defer res.Body.Close() + + out, err := io.ReadAll(res.Body) + if err != nil { + panic(err) + } + + fmt.Println(string(out)) +} +``` + +## Notes + +- Create a reusable `http.Client` with timeouts instead of relying on `DefaultClient` in production. +- Parse the JSON response into structs once your schema is stable. +- Retry `429`, `500`, `529`, and transient network errors with backoff. +- Keep the request builder isolated so you can reuse it for tool use, prompt caching, or files later. diff --git a/src/skills/bundled/claude-api/java/claude-api.md b/src/skills/bundled/claude-api/java/claude-api.md index 8eac314..047a70f 100644 --- a/src/skills/bundled/claude-api/java/claude-api.md +++ b/src/skills/bundled/claude-api/java/claude-api.md @@ -1,3 +1,47 @@ # Java Claude API -Restored placeholder content. +For Java, a simple `HttpClient` integration is enough to get started. + +## Minimal Example + +```java +import java.net.URI; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; + +public class Main { + public static void main(String[] args) throws Exception { + String apiKey = System.getenv("ANTHROPIC_API_KEY"); + String json = """ + { + "model": "{{SONNET_ID}}", + "max_tokens": 512, + "messages": [ + {"role": "user", "content": "List three production-readiness checks."} + ] + } + """; + + HttpRequest request = HttpRequest.newBuilder() + .uri(URI.create("https://api.anthropic.com/v1/messages")) + .header("x-api-key", apiKey) + .header("anthropic-version", "2023-06-01") + .header("content-type", "application/json") + .POST(HttpRequest.BodyPublishers.ofString(json)) + .build(); + + HttpClient client = HttpClient.newHttpClient(); + HttpResponse response = + client.send(request, HttpResponse.BodyHandlers.ofString()); + + System.out.println(response.body()); + } +} +``` + +## Notes + +- Parse the response with Jackson or your preferred JSON library once you know which fields you need. +- Prefer a shared `HttpClient` and explicit timeouts. +- For server apps, log request IDs and status codes so you can diagnose throttling and malformed requests quickly. diff --git a/src/skills/bundled/claude-api/php/claude-api.md b/src/skills/bundled/claude-api/php/claude-api.md index 3f19a92..8b59e66 100644 --- a/src/skills/bundled/claude-api/php/claude-api.md +++ b/src/skills/bundled/claude-api/php/claude-api.md @@ -1,3 +1,52 @@ # PHP Claude API -Restored placeholder content. +For PHP, start with a direct HTTPS request and wrap it later in your application service layer. + +## Minimal Example + +```php + '{{SONNET_ID}}', + 'max_tokens' => 512, + 'messages' => [ + [ + 'role' => 'user', + 'content' => 'Generate a brief API changelog entry.', + ], + ], +]; + +$ch = curl_init('https://api.anthropic.com/v1/messages'); +curl_setopt_array($ch, [ + CURLOPT_POST => true, + CURLOPT_RETURNTRANSFER => true, + CURLOPT_HTTPHEADER => [ + 'x-api-key: ' . getenv('ANTHROPIC_API_KEY'), + 'anthropic-version: 2023-06-01', + 'content-type: application/json', + ], + CURLOPT_POSTFIELDS => json_encode($payload), +]); + +$response = curl_exec($ch); +if ($response === false) { + throw new RuntimeException(curl_error($ch)); +} + +$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); +curl_close($ch); + +if ($status >= 400) { + throw new RuntimeException("Anthropic API error: HTTP $status\n$response"); +} + +echo $response . PHP_EOL; +``` + +## Notes + +- Decode successful responses with `json_decode($response, true)`. +- Treat API key loading, retries, and request logging as shared infrastructure, not per-controller code. +- If you need typed models, introduce DTOs after the request and response shapes stabilize. diff --git a/src/skills/bundled/claude-api/python/agent-sdk/README.md b/src/skills/bundled/claude-api/python/agent-sdk/README.md index 615038e..ae301c0 100644 --- a/src/skills/bundled/claude-api/python/agent-sdk/README.md +++ b/src/skills/bundled/claude-api/python/agent-sdk/README.md @@ -1,3 +1,72 @@ # Python Agent SDK -Restored placeholder content. +Use the Python Agent SDK when you want Claude Code's agent loop, tools, hooks, and session handling from Python instead of calling the Messages API directly. + +## Install + +```bash +pip install claude-agent-sdk +``` + +The SDK talks to a local Claude Code CLI, so the machine running your Python code also needs Claude Code installed and authenticated. + +## Choose the right entrypoint + +- `query(...)`: one-off tasks. Each call starts a fresh session. +- `ClaudeSDKClient(...)`: multi-turn or long-lived conversations. Reuses session state and supports interrupts. + +## Minimal `query()` example + +```python +import asyncio +from claude_agent_sdk import query, ClaudeAgentOptions + + +async def main() -> None: + async for message in query( + prompt="Review the repository and suggest the safest fix.", + options=ClaudeAgentOptions( + cwd=".", + permission_mode="default", + ), + ): + print(message) + + +asyncio.run(main()) +``` + +## Minimal client example + +```python +import asyncio +from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions + + +async def main() -> None: + client = ClaudeSDKClient( + options=ClaudeAgentOptions(cwd=".") + ) + await client.connect() + try: + await client.query("Summarize the current branch status.") + await client.query("Now suggest the next test to run.") + finally: + await client.close() + + +asyncio.run(main()) +``` + +## Practical notes + +- Prefer `query()` for scripts, cron jobs, and single task execution. +- Prefer `ClaudeSDKClient` when later prompts depend on earlier tool results. +- Pass `cwd`, permission settings, allowed tools, hooks, and custom tools through `ClaudeAgentOptions`. +- For incremental output, enable partial message streaming and handle `StreamEvent` messages. +- For raw model calls without Claude Code tools, use the Anthropic Python SDK instead of the Agent SDK. + +## Official references + +- Agent SDK quickstart: `https://platform.claude.com/docs/en/agent-sdk/quickstart` +- Agent SDK Python reference: `https://platform.claude.com/docs/en/agent-sdk/python` diff --git a/src/skills/bundled/claude-api/python/agent-sdk/patterns.md b/src/skills/bundled/claude-api/python/agent-sdk/patterns.md index 455e94d..e623b7a 100644 --- a/src/skills/bundled/claude-api/python/agent-sdk/patterns.md +++ b/src/skills/bundled/claude-api/python/agent-sdk/patterns.md @@ -1,3 +1,63 @@ # Python Agent SDK Patterns -Restored placeholder content. +## Pattern 1: one-shot automation + +Use `query()` for isolated tasks such as "fix this file", "review this diff", or "generate release notes". + +```python +async for message in query( + prompt="Inspect src/main.py and explain the bug.", + options=ClaudeAgentOptions(cwd="."), +): + print(message) +``` + +Best when conversation history is not needed. + +## Pattern 2: conversational workflow + +Use `ClaudeSDKClient` when each answer should build on earlier context. + +```python +client = ClaudeSDKClient(options=ClaudeAgentOptions(cwd=".")) +await client.connect() +await client.query("Read the auth flow.") +await client.query("Now propose a refactor with minimal risk.") +``` + +Best for REPLs, chat UIs, or multi-step repair loops. + +## Pattern 3: custom tools + +Expose deterministic local logic as tools and let Claude decide when to call them. + +```python +from claude_agent_sdk import tool + + +@tool("get_build_id", "Return the current build identifier", {}) +async def get_build_id(_args): + return {"content": [{"type": "text", "text": "build-2026-03-31"}]} +``` + +Keep tools narrow, typed, and side-effect conscious. + +## Pattern 4: hooks and policy + +Use hooks when you need approval gates, logging, or organization-specific constraints before or after tool use. Put policy in hooks or permission settings, not in the prompt alone. + +## Pattern 5: streaming UIs + +Enable partial messages when building terminal or web interfaces that should render text and tool calls as they arrive. Treat streamed events as incremental updates; keep the final `AssistantMessage` or `ResultMessage` as the source of truth. + +## Pattern 6: robust session control + +- Set `cwd` explicitly. +- Set permission mode deliberately. +- Close `ClaudeSDKClient` in `finally`. +- Surface `CLINotFoundError`, connection errors, and permission denials to the caller. + +## When not to use the Agent SDK + +- Use the Anthropic Python SDK for plain `messages.create(...)` workflows. +- Use the Messages API directly when you need raw API semantics, provider portability, or no Claude Code dependency. diff --git a/src/skills/bundled/claude-api/python/claude-api/README.md b/src/skills/bundled/claude-api/python/claude-api/README.md index 78a7be1..48e192d 100644 --- a/src/skills/bundled/claude-api/python/claude-api/README.md +++ b/src/skills/bundled/claude-api/python/claude-api/README.md @@ -1,3 +1,77 @@ # Python Claude API -Restored placeholder content. +Use the official Anthropic Python SDK for direct Claude API access from Python. + +## Install + +```bash +pip install anthropic +``` + +Optional extras: + +```bash +pip install anthropic[aiohttp] +pip install anthropic[bedrock] +pip install anthropic[vertex] +``` + +## Basic sync request + +```python +import os +from anthropic import Anthropic + +client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"]) + +message = client.messages.create( + model="claude-sonnet-4-5", + max_tokens=1024, + messages=[ + {"role": "user", "content": "Summarize the latest changelog."} + ], +) + +print(message.content) +``` + +## Async request + +```python +import os +import asyncio +from anthropic import AsyncAnthropic + + +async def main() -> None: + client = AsyncAnthropic(api_key=os.environ["ANTHROPIC_API_KEY"]) + message = await client.messages.create( + model="claude-sonnet-4-5", + max_tokens=1024, + messages=[{"role": "user", "content": "Hello, Claude"}], + ) + print(message.content) + + +asyncio.run(main()) +``` + +## Use this SDK when + +- you want raw `messages.create(...)` access +- you need sync or async Python clients +- you are implementing streaming, tool use, batches, or Files API directly + +## Practical guidance + +- Prefer current stable model aliases or exact IDs your application supports. +- Keep long-lived static context at the start of the request so prompt caching can help. +- Use streaming for long outputs or latency-sensitive UIs. +- Use Batches for large asynchronous jobs. +- Use Files API when the same document or image must be referenced across requests. + +## Official references + +- Python SDK: `https://platform.claude.com/docs/en/api/sdks/python` +- Client SDK overview: `https://platform.claude.com/docs/en/api/client-sdks` +- Messages API reference: `https://platform.claude.com/docs/en/api/python/messages` diff --git a/src/skills/bundled/claude-api/python/claude-api/batches.md b/src/skills/bundled/claude-api/python/claude-api/batches.md index 28aa731..54e8acb 100644 --- a/src/skills/bundled/claude-api/python/claude-api/batches.md +++ b/src/skills/bundled/claude-api/python/claude-api/batches.md @@ -1,3 +1,67 @@ # Python Batches -Restored placeholder content. +Use Message Batches when you have many independent requests and do not need interactive latency. + +## Good fit + +- nightly evaluations +- backfills and migrations +- large classification or summarization jobs +- bulk tasks where polling is easier than holding open many live connections + +## Create a batch + +```python +from anthropic import Anthropic + +client = Anthropic() + +batch = client.beta.messages.batches.create( + requests=[ + { + "custom_id": "ticket-1", + "params": { + "model": "claude-sonnet-4-5", + "max_tokens": 512, + "messages": [ + {"role": "user", "content": "Summarize ticket #1"} + ], + }, + }, + { + "custom_id": "ticket-2", + "params": { + "model": "claude-sonnet-4-5", + "max_tokens": 512, + "messages": [ + {"role": "user", "content": "Summarize ticket #2"} + ], + }, + }, + ], +) +``` + +## Poll for completion + +```python +batch = client.beta.messages.batches.retrieve(batch.id) +print(batch.processing_status) +print(batch.request_counts) +``` + +## Read results + +Results are not guaranteed to come back in request order. Match on `custom_id`, not array position. Once processing finishes, fetch or iterate the batch results and join them back to your application records by `custom_id`. + +## Practical guidance + +- Use batches only for independent requests. +- Store your own mapping from `custom_id` to source record. +- Expect partial failures; some requests may succeed while others error or expire. +- If you need immediate user feedback, use normal Messages API calls instead. + +## Official references + +- Batch guide/reference: `https://platform.claude.com/docs/en/api/messages/batches` +- Python batch endpoints: `https://platform.claude.com/docs/en/api/python/beta/messages/batches/list` diff --git a/src/skills/bundled/claude-api/python/claude-api/files-api.md b/src/skills/bundled/claude-api/python/claude-api/files-api.md index 3456338..7a3bf3d 100644 --- a/src/skills/bundled/claude-api/python/claude-api/files-api.md +++ b/src/skills/bundled/claude-api/python/claude-api/files-api.md @@ -1,3 +1,67 @@ # Python Files API -Restored placeholder content. +Use the Files API when you need upload-once, reference-many behavior across multiple Claude API requests. + +## Important constraints + +- Files API is beta. +- Include the Files API beta header/version accepted by your SDK release. +- Uploaded files cannot be downloaded later; only files generated by skills or code execution are downloadable. +- Files API is not supported on Bedrock or Vertex AI. + +## Upload a file + +```python +from anthropic import Anthropic + +client = Anthropic() + +with open("document.pdf", "rb") as f: + meta = client.beta.files.upload( + file=("document.pdf", f, "application/pdf"), + ) + +print(meta.id) +``` + +## Reference the file in a message + +```python +message = client.messages.create( + model="claude-sonnet-4-5", + max_tokens=1024, + betas=["files-api-2025-04-14"], + messages=[ + { + "role": "user", + "content": [ + {"type": "text", "text": "Summarize this PDF."}, + { + "type": "document", + "source": {"type": "file", "file_id": meta.id}, + }, + ], + } + ], +) +``` + +## Manage files + +```python +files = client.beta.files.list() +info = client.beta.files.retrieve_metadata(meta.id) +client.beta.files.delete(meta.id) +``` + +## Practical guidance + +- Prefer Files API when the same document, image, or dataset is reused. +- Validate MIME type and size before upload. +- Track `file_id` in your own storage. +- Delete files you no longer need; file persistence is explicit. + +## Official references + +- Files API guide: `https://platform.claude.com/docs/en/build-with-claude/files` +- Python Files API reference: `https://platform.claude.com/docs/en/api/python/beta/files` diff --git a/src/skills/bundled/claude-api/python/claude-api/streaming.md b/src/skills/bundled/claude-api/python/claude-api/streaming.md index 89daec2..e19183b 100644 --- a/src/skills/bundled/claude-api/python/claude-api/streaming.md +++ b/src/skills/bundled/claude-api/python/claude-api/streaming.md @@ -1,3 +1,42 @@ # Python Streaming -Restored placeholder content. +Use streaming when you want text as it arrives instead of waiting for the final message. + +## Simple text streaming + +```python +from anthropic import Anthropic + +client = Anthropic() + +with client.messages.stream( + model="claude-sonnet-4-5", + max_tokens=1024, + messages=[{"role": "user", "content": "Write a short release note."}], +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +``` + +## Get the final message + +If you want streaming transport but still need the final structured `Message`, use the stream helper and then call the SDK method that returns the completed response object for the stream. + +## When streaming is worth it + +- chat or terminal UIs +- long generations +- progress feedback for users +- tool use flows where early visibility matters + +## Practical guidance + +- Treat streamed events as incremental UI updates. +- Keep the final assembled message as the authoritative result. +- Long non-streaming requests are more exposed to idle network timeouts than streaming or batches. +- If you do not need live tokens, normal `messages.create(...)` is simpler. + +## Official references + +- Streaming guide: `https://platform.claude.com/docs/en/build-with-claude/streaming` +- Python SDK: `https://platform.claude.com/docs/en/api/sdks/python` diff --git a/src/skills/bundled/claude-api/python/claude-api/tool-use.md b/src/skills/bundled/claude-api/python/claude-api/tool-use.md index 455466b..7a49a2e 100644 --- a/src/skills/bundled/claude-api/python/claude-api/tool-use.md +++ b/src/skills/bundled/claude-api/python/claude-api/tool-use.md @@ -1,3 +1,70 @@ # Python Tool Use -Restored placeholder content. +Tool use lets Claude decide when to request a tool, emit a `tool_use` block, and continue after you return a matching `tool_result`. + +## Define tools + +```python +tools = [ + { + "name": "get_weather", + "description": "Return current weather for a city", + "input_schema": { + "type": "object", + "properties": { + "city": {"type": "string"}, + }, + "required": ["city"], + }, + } +] +``` + +## First model call + +```python +message = client.messages.create( + model="claude-sonnet-4-5", + max_tokens=1024, + tools=tools, + messages=[ + {"role": "user", "content": "What is the weather in Tokyo?"} + ], +) +``` + +## Handle `tool_use` and continue + +Inspect `message.content` for blocks with `type == "tool_use"`. Execute the requested tool, then send a follow-up user message containing a `tool_result` block whose `tool_use_id` matches the tool call. + +```python +messages = [ + {"role": "user", "content": "What is the weather in Tokyo?"}, + {"role": "assistant", "content": message.content}, + { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": tool_use.id, + "content": [{"type": "text", "text": "18C and clear"}], + } + ], + }, +] +``` + +Then call `client.messages.create(...)` again with the updated message history. + +## Practical guidance + +- Keep tool schemas small and strict. +- Return machine-readable data when possible. +- Match `tool_use_id` exactly. +- Expect multiple tool calls and possibly parallel tool requests. +- If you want higher-level orchestration, consider the Agent SDK instead of manual tool loops. + +## Official references + +- Tool use overview: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview` +- Python Messages API reference: `https://platform.claude.com/docs/en/api/python/messages` diff --git a/src/skills/bundled/claude-api/ruby/claude-api.md b/src/skills/bundled/claude-api/ruby/claude-api.md index 6e7260c..aaceb30 100644 --- a/src/skills/bundled/claude-api/ruby/claude-api.md +++ b/src/skills/bundled/claude-api/ruby/claude-api.md @@ -1,3 +1,41 @@ # Ruby Claude API -Restored placeholder content. +Ruby can call the Messages API directly with `Net::HTTP`. + +## Minimal Example + +```ruby +require 'json' +require 'net/http' +require 'uri' + +uri = URI('https://api.anthropic.com/v1/messages') +http = Net::HTTP.new(uri.host, uri.port) +http.use_ssl = true + +request = Net::HTTP::Post.new(uri) +request['x-api-key'] = ENV.fetch('ANTHROPIC_API_KEY') +request['anthropic-version'] = '2023-06-01' +request['content-type'] = 'application/json' +request.body = JSON.generate( + model: '{{SONNET_ID}}', + max_tokens: 512, + messages: [ + { + role: 'user', + content: 'Write a compact incident summary for a failed deploy.' + } + ] +) + +response = http.request(request) +raise response.body unless response.is_a?(Net::HTTPSuccess) + +puts response.body +``` + +## Notes + +- Parse the JSON response and extract text blocks from `content`. +- Set open/read timeouts on the HTTP client for production use. +- Add retry and rate-limit handling in one shared client object instead of duplicating it across jobs or controllers. diff --git a/src/skills/bundled/claude-api/shared/error-codes.md b/src/skills/bundled/claude-api/shared/error-codes.md index 979b38c..5f963a3 100644 --- a/src/skills/bundled/claude-api/shared/error-codes.md +++ b/src/skills/bundled/claude-api/shared/error-codes.md @@ -1,3 +1,32 @@ # Error Codes -Restored placeholder content. +Use this note when the user asks why an Anthropic API call failed or how to harden error handling. + +## What To Check First + +- HTTP status code +- Anthropic error type and message body +- Whether the failure is transient or request-specific +- Whether streaming failed before completion or before the first event + +## Practical Triage + +- `400`-class errors usually mean request shape, model choice, auth headers, or unsupported parameters need to be fixed before retrying. +- `401` and `403` usually indicate key, workspace, or permission issues rather than a temporary outage. +- `404` often means the referenced resource, model, batch, or file ID is wrong for the current API surface. +- `429` should be handled with backoff, retry, and concurrency control. +- `5xx` should be treated as transient service failures and retried with jittered exponential backoff. + +## Implementation Guidance + +- Log the Anthropic request ID when available so failed requests can be correlated. +- Surface response body details in server logs, but avoid leaking full prompts or secrets to users. +- Make retries idempotent where possible, especially for batch polling and file workflows. +- Distinguish validation failures from transport failures in your code paths. + +## Recovery Pattern + +1. Validate request construction locally. +2. Retry only transient classes such as rate limits and server errors. +3. For streaming, decide whether to resume, restart, or fall back to non-streaming output. +4. If the user asks for exact current error semantics, verify against Anthropic’s live API reference. diff --git a/src/skills/bundled/claude-api/shared/live-sources.md b/src/skills/bundled/claude-api/shared/live-sources.md index 551bd35..00dbe70 100644 --- a/src/skills/bundled/claude-api/shared/live-sources.md +++ b/src/skills/bundled/claude-api/shared/live-sources.md @@ -1,3 +1,25 @@ # Live Sources -Restored placeholder content. +Use WebFetch or browsing when the answer depends on changing Anthropic documentation. + +## Browse For These Cases + +- Current model IDs, aliases, or deprecations +- Pricing, rate limits, or feature availability +- Newly added tool types or server-side tools +- Exact request fields for Files, Batches, or streaming APIs +- SDK release details when the user asks for version-specific behavior + +## Preferred Official Sources + +- Main docs hub: `https://docs.anthropic.com/` +- Models overview: `https://docs.anthropic.com/en/docs/about-claude/models/all-models` +- Features overview: `https://docs.anthropic.com/en/docs/build-with-claude/overview` +- Tool use: `https://docs.anthropic.com/en/docs/build-with-claude/tool-use` +- Prompt caching: `https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching` +- API reference: `https://docs.anthropic.com/en/api/` +- Anthropic SDK repositories: Anthropic GitHub org repos for language-specific SDK examples + +## Usage Rule + +When a question could be stale, prefer the official docs page over memory. Quote briefly, summarize the rest, and link the page you used. diff --git a/src/skills/bundled/claude-api/shared/models.md b/src/skills/bundled/claude-api/shared/models.md index 32a2f70..6552d2d 100644 --- a/src/skills/bundled/claude-api/shared/models.md +++ b/src/skills/bundled/claude-api/shared/models.md @@ -1,3 +1,26 @@ # Models -Restored placeholder content. +Use this note when the user asks which Claude model to choose or how model naming works. + +## Selection Heuristic + +- Use Opus for the hardest reasoning, long-horizon planning, or highest-stakes coding tasks. +- Use Sonnet as the default general-purpose choice for most product and engineering workloads. +- Use Haiku when latency and cost matter more than peak reasoning depth. + +## Model Naming Guidance + +- Anthropic exposes dated model IDs. Prefer exact IDs in shipped code when reproducibility matters. +- User-facing guidance can mention family names such as Opus, Sonnet, and Haiku, but implementation examples should use concrete model IDs. +- Do not invent date suffixes. Verify current IDs against the live models overview if the user asks for exact names. + +## Context And Capability + +- Model family choice is only one dimension; prompt design, tool setup, caching, and streaming strategy also affect behavior. +- Some advanced features may be model- or platform-specific. Confirm live availability before promising support. +- If the user is deciding between Anthropic API, Bedrock, and Vertex, check the official model matrix because IDs differ by platform. + +## Practical Advice + +- Default to the current Sonnet model for most app examples unless the user explicitly asks for premium capability or minimum cost. +- For migration work, separate “API compatibility” from “behavior compatibility”; a model swap that compiles may still change output quality or tool behavior. diff --git a/src/skills/bundled/claude-api/shared/prompt-caching.md b/src/skills/bundled/claude-api/shared/prompt-caching.md index 15592c7..1201f01 100644 --- a/src/skills/bundled/claude-api/shared/prompt-caching.md +++ b/src/skills/bundled/claude-api/shared/prompt-caching.md @@ -1,3 +1,34 @@ # Prompt Caching -Restored placeholder content. +Use this note when the user wants lower repeated-context cost or faster repeated requests. + +## When It Helps + +- Large static system prompts +- Reused tool definitions +- Long reference documents shared across many requests +- Multi-turn workflows where a stable prefix repeats + +## Structuring Advice + +- Put reusable content first. +- Keep the dynamic tail as small as possible. +- Cache stable instructions, examples, tools, and reference context before volatile user input. +- Avoid reordering cached sections between requests. + +## Reasoning About Hits + +- Cache usefulness depends on long shared prefixes, not just similar meaning. +- Small structural changes near the top of the prompt can break reuse. +- Tool definitions count toward the reusable prefix, so changing schemas can reduce hit rate. + +## Debugging Low Hit Rates + +- Compare request prefixes, not just the final prompt text mentally. +- Check whether timestamps, request IDs, or per-turn metadata are being inserted too early. +- Make sure the application is not rebuilding tool definitions or examples in a different order. + +## Guidance For Answers + +- Explain caching as an optimization for repeated static prefix content. +- If the user asks for current support matrix or exact API fields, verify against Anthropic’s live prompt caching docs. diff --git a/src/skills/bundled/claude-api/shared/tool-use-concepts.md b/src/skills/bundled/claude-api/shared/tool-use-concepts.md index 9017e46..a90c366 100644 --- a/src/skills/bundled/claude-api/shared/tool-use-concepts.md +++ b/src/skills/bundled/claude-api/shared/tool-use-concepts.md @@ -1,3 +1,31 @@ # Tool Use Concepts -Restored placeholder content. +Use this note for tool calling, function execution, and agent loops built on Claude. + +## Core Model + +- You declare tools in the request. +- Claude decides whether to call a tool based on the prompt and tool choice configuration. +- Your application executes the tool and sends the result back in a follow-up message. +- Claude then continues reasoning with the tool result in context. + +## Design Guidance + +- Keep tool names clear and stable. +- Write descriptions for the model, not for human readers only. +- Use narrow input schemas with concrete field names and required fields. +- Return structured, minimal tool results when possible. + +## Common Failure Modes + +- Over-broad tools that make selection ambiguous +- Schemas that allow too many invalid states +- Tool results that are too verbose or omit critical fields +- Forgetting to loop until Claude stops requesting tools + +## Practical Agent Advice + +- Treat tool use as a protocol, not a one-shot helper call. +- Add application-level limits for tool recursion, retries, and external side effects. +- Separate client-side tools from server-side Anthropic tools when explaining implementation responsibilities. +- If the user asks for exact server tool types or current pricing, verify against the live tool-use docs. diff --git a/src/skills/bundled/claude-api/typescript/agent-sdk/README.md b/src/skills/bundled/claude-api/typescript/agent-sdk/README.md index 3e54469..da41053 100644 --- a/src/skills/bundled/claude-api/typescript/agent-sdk/README.md +++ b/src/skills/bundled/claude-api/typescript/agent-sdk/README.md @@ -1,3 +1,48 @@ # TypeScript Agent SDK -Restored placeholder content. +Use the Claude Agent SDK when you want Claude Code style agents from Node or Bun, not just raw model calls. Install the package, create an agent, then run tasks through the harness. + +## Install + +```bash +npm install @anthropic-ai/claude-agent-sdk +``` + +Set `ANTHROPIC_API_KEY` unless your runtime provides Claude Code style auth separately. + +## Minimal flow + +```ts +import { Agent } from '@anthropic-ai/claude-agent-sdk' + +const agent = new Agent({ + model: 'claude-sonnet-4-6', + systemPrompt: 'You are a precise engineering assistant.', +}) + +const result = await agent.run('Summarize the repository layout.') +console.log(result.outputText) +``` + +## When to choose Agent SDK + +- Use Agent SDK for multi-step tasks, tool use, file edits, shell execution, or MCP access. +- Use `@anthropic-ai/sdk` instead when you only need direct Messages API calls. + +## Practical guidance + +- Keep the system prompt short and role-specific. +- Limit enabled tools to the minimum needed for the task. +- Prefer explicit task boundaries such as “analyze only” or “edit only these files”. +- Capture structured output in your application instead of parsing long prose after the fact. + +## Operational notes + +- Reuse agent instances for related work when you want consistent behavior. +- Create fresh agents when permissions, tool sets, or task roles change materially. +- Treat tool access as part of your security model; do not expose shell or file tools by default. + +## References + +- Anthropic docs: Claude Code SDK overview and API reference +- GitHub: `anthropics/claude-agent-sdk-typescript` diff --git a/src/skills/bundled/claude-api/typescript/agent-sdk/patterns.md b/src/skills/bundled/claude-api/typescript/agent-sdk/patterns.md index 09131ba..7148a0b 100644 --- a/src/skills/bundled/claude-api/typescript/agent-sdk/patterns.md +++ b/src/skills/bundled/claude-api/typescript/agent-sdk/patterns.md @@ -1,3 +1,51 @@ # TypeScript Agent SDK Patterns -Restored placeholder content. +## Narrow tool access + +Start with the smallest tool surface that can finish the task. + +```ts +const agent = new Agent({ + model: 'claude-sonnet-4-6', + systemPrompt: 'Review code and report findings only.', + allowedTools: ['Read', 'Glob', 'Grep'], +}) +``` + +Use write-capable tools only when the task truly requires edits. + +## Separate planning from execution + +For longer workflows, run an analysis pass first, then a second pass that can edit or execute. + +```ts +const review = await reviewAgent.run('Find the highest-risk regression.') +const fix = await fixAgent.run(`Implement this change:\n\n${review.outputText}`) +``` + +This reduces accidental edits and makes logs easier to audit. + +## Constrain the workspace + +- Pass explicit directories or file lists when the task is repo-scoped. +- Prefer short user prompts with exact success criteria. +- If the task is high risk, force structured output such as JSON or a checklist. + +## Use agents for orchestration, not hidden business logic + +- Keep validation, persistence, and authorization in application code. +- Let the agent decide how to solve a task within boundaries you define. +- Re-check outputs before applying them to production systems. + +## Good use cases + +- Repository review bots +- Migration assistants +- Incident triage helpers +- Controlled code editing workflows + +## Avoid + +- Giving one agent unrestricted shell, network, and file access by default +- Relying on implicit context instead of attaching the exact files or instructions +- Treating agent text as trusted structured data without validation diff --git a/src/skills/bundled/claude-api/typescript/claude-api/README.md b/src/skills/bundled/claude-api/typescript/claude-api/README.md index 73670ff..32e3001 100644 --- a/src/skills/bundled/claude-api/typescript/claude-api/README.md +++ b/src/skills/bundled/claude-api/typescript/claude-api/README.md @@ -1,3 +1,55 @@ # TypeScript Claude API -Restored placeholder content. +Use `@anthropic-ai/sdk` for direct access to the Messages API from TypeScript. + +## Install + +```bash +npm install @anthropic-ai/sdk +``` + +Set `ANTHROPIC_API_KEY` in the environment. + +## Basic request + +```ts +import Anthropic from '@anthropic-ai/sdk' + +const client = new Anthropic({ + apiKey: process.env.ANTHROPIC_API_KEY, +}) + +const message = await client.messages.create({ + model: 'claude-sonnet-4-6', + max_tokens: 1024, + messages: [ + { role: 'user', content: 'Summarize this change in 3 bullets.' }, + ], +}) +``` + +Read text from `message.content` by filtering for `type === 'text'`. + +## Recommended request shape + +- Always set `model` and `max_tokens` explicitly. +- Put instructions in a stable system prompt when they should apply across turns. +- Keep user messages task-focused and attach only the context needed for the turn. +- Use streaming for responsive UIs and tool use for structured external actions. + +## Conversation pattern + +Pass prior turns back in `messages` when you need continuity. Keep the conversation compact; summarize or trim old turns instead of replaying large transcripts forever. + +## Model choice + +- `claude-opus-4-6`: highest reasoning quality +- `claude-sonnet-4-6`: general default for most product workloads +- `claude-haiku-4-5`: lower-latency and lower-cost tasks + +Check the current model catalog before hard-coding IDs in production. + +## References + +- Anthropic docs: Messages API +- Anthropic docs: model overview diff --git a/src/skills/bundled/claude-api/typescript/claude-api/batches.md b/src/skills/bundled/claude-api/typescript/claude-api/batches.md index 3b59c0d..691f161 100644 --- a/src/skills/bundled/claude-api/typescript/claude-api/batches.md +++ b/src/skills/bundled/claude-api/typescript/claude-api/batches.md @@ -1,3 +1,44 @@ # TypeScript Batches -Restored placeholder content. +Use message batches when latency is not interactive and you want to process many independent requests efficiently. + +## When batches fit + +- large backfills +- offline classification +- nightly summarization jobs +- document queues where each task is independent + +## Create a batch + +```ts +const batch = await client.messages.batches.create({ + requests: [ + { + custom_id: 'item-1', + params: { + model: 'claude-sonnet-4-6', + max_tokens: 512, + messages: [{ role: 'user', content: 'Classify this ticket.' }], + }, + }, + ], +}) +``` + +## Operational guidance + +- Set a stable `custom_id` for each request so you can join results back to your job records. +- Keep each request self-contained; batches are not conversational threads. +- Poll batch status and then fetch results once processing completes. +- Design for partial failure. Some requests may succeed while others error. + +## Avoid + +- using batches for chat UIs +- assuming result order is the same as input order +- sending dependent tasks that require previous model output + +## References + +- Anthropic docs: Message Batches API diff --git a/src/skills/bundled/claude-api/typescript/claude-api/files-api.md b/src/skills/bundled/claude-api/typescript/claude-api/files-api.md index c96f3e0..8c1a693 100644 --- a/src/skills/bundled/claude-api/typescript/claude-api/files-api.md +++ b/src/skills/bundled/claude-api/typescript/claude-api/files-api.md @@ -1,3 +1,40 @@ # TypeScript Files API -Restored placeholder content. +Use the Files API when the same file needs to be referenced across multiple requests instead of uploading bytes each time. + +## Typical flow + +1. Upload a file once. +2. Store the returned file ID. +3. Reference that file ID in later requests. + +## Upload example + +```ts +const file = await client.files.create({ + file: new File(['hello'], 'example.txt', { type: 'text/plain' }), + purpose: 'user_data', +}) +``` + +## Guidance + +- Persist file IDs in your own database; they are the stable handle for reuse. +- Use the Files API for repeated access, not one-off tiny payloads. +- Validate file type and size before upload in your app code. +- Treat uploaded files as user data and apply your normal retention rules. + +## Good fits + +- multi-turn document workflows +- repeated evaluation inputs +- analysis pipelines that reuse the same source material + +## Avoid + +- uploading files on every request when the same content is reused +- assuming a local path is meaningful to the API + +## References + +- Anthropic docs: Files API diff --git a/src/skills/bundled/claude-api/typescript/claude-api/streaming.md b/src/skills/bundled/claude-api/typescript/claude-api/streaming.md index 0032724..397bf06 100644 --- a/src/skills/bundled/claude-api/typescript/claude-api/streaming.md +++ b/src/skills/bundled/claude-api/typescript/claude-api/streaming.md @@ -1,3 +1,40 @@ # TypeScript Streaming -Restored placeholder content. +Use streaming when the user should see output incrementally or when you want earlier visibility into tool use and long generations. + +## Basic pattern + +```ts +const stream = await client.messages.stream({ + model: 'claude-sonnet-4-6', + max_tokens: 1024, + messages: [{ role: 'user', content: 'Draft a release note.' }], +}) + +for await (const event of stream) { + // Handle text deltas, message state, and completion events. +} +``` + +## UI guidance + +- Render deltas as they arrive instead of waiting for the final message. +- Keep a final assembled value in state for persistence. +- Handle cancellation explicitly when users close the view or submit a new task. + +## Reliability notes + +- Expect event-driven parsing, not one final JSON payload. +- Preserve the final completed message if you need usage or stop reason metadata. +- Do not assume every stream yields only text; tool-related events can appear in compatible flows. + +## Good fits + +- chat UIs +- long summaries +- code generation views +- responsive terminal output + +## References + +- Anthropic docs: streaming Messages responses diff --git a/src/skills/bundled/claude-api/typescript/claude-api/tool-use.md b/src/skills/bundled/claude-api/typescript/claude-api/tool-use.md index ed9f867..87491f5 100644 --- a/src/skills/bundled/claude-api/typescript/claude-api/tool-use.md +++ b/src/skills/bundled/claude-api/typescript/claude-api/tool-use.md @@ -1,3 +1,52 @@ # TypeScript Tool Use -Restored placeholder content. +Tool use lets Claude request structured actions from your application. Your code defines the tools, executes them, then sends tool results back into the conversation. + +## Define a tool + +```ts +const tools = [ + { + name: 'get_weather', + description: 'Fetch the current weather for a city', + input_schema: { + type: 'object', + properties: { + city: { type: 'string' }, + }, + required: ['city'], + }, + }, +] +``` + +## Request with tools + +```ts +const message = await client.messages.create({ + model: 'claude-sonnet-4-6', + max_tokens: 1024, + tools, + messages: [{ role: 'user', content: 'What is the weather in Tokyo?' }], +}) +``` + +If Claude returns a tool-use block, execute the named tool in your application, then append a `tool_result` turn and call the API again. + +## Practical guidance + +- Keep tool schemas narrow and explicit. +- Validate tool input before execution. +- Return structured, minimal results instead of raw logs when possible. +- Put authorization and side-effect checks in your code, not in the model prompt. + +## Avoid + +- exposing shell or network primitives unless absolutely necessary +- giving tools vague names or overly broad schemas +- skipping retries and timeout handling around real integrations + +## References + +- Anthropic docs: tool use +- Anthropic docs: Messages API diff --git a/src/skills/bundled/verify/SKILL.md b/src/skills/bundled/verify/SKILL.md index efb7bc0..d9f77fa 100644 --- a/src/skills/bundled/verify/SKILL.md +++ b/src/skills/bundled/verify/SKILL.md @@ -1,3 +1,51 @@ +--- +description: Verify a code change by running the app, the relevant command, or a focused server flow and reporting concrete evidence. +--- + # Verify -Restored placeholder content. +Use this skill when a task is not finished until the change is exercised. + +## Goal + +Produce a short verification result grounded in execution, not inference. Prefer the narrowest check that proves the changed behavior works. + +## Workflow + +1. Identify the changed surface area. +2. Pick the smallest realistic verification path. +3. Run the relevant command or request flow. +4. Capture the observable result: exit status, key output, HTTP status, or changed behavior. +5. Report what passed, what was not verified, and any remaining risk. + +## Rules + +- Do not claim success without running something. +- Prefer focused checks over broad smoke tests. +- If the repo has no formal test target, use the nearest runnable workflow. +- If a check is blocked by environment limits, state that explicitly. +- Include exact commands when they are useful to repeat the verification. + +## Verification Patterns + +### CLI changes + +- Run the exact command path affected by the edit. +- Check help text, flags, output formatting, exit codes, and side effects. +- For interactive flows, prefer the most scriptable subcommand first. + +See `examples/cli.md`. + +### Server changes + +- Start only the needed service. +- Exercise the changed route, handler, or background path. +- Validate status code, response shape, logs, and failure handling. + +See `examples/server.md`. + +## Reporting Format + +- `Verified:` what you ran and what passed. +- `Not verified:` anything you could not run. +- `Risk:` the main remaining uncertainty, if any. diff --git a/src/skills/bundled/verify/examples/cli.md b/src/skills/bundled/verify/examples/cli.md index cc5ff47..5485e78 100644 --- a/src/skills/bundled/verify/examples/cli.md +++ b/src/skills/bundled/verify/examples/cli.md @@ -1,3 +1,30 @@ # Verify CLI Example -Restored placeholder content. +Use this pattern when the change affects a command, flag, formatter, or local workflow. + +## Example + +Change: update `claude doctor` output or bootstrap behavior. + +Verification: + +1. Run the narrowest command that hits the changed code path. +2. Re-run with a nearby flag if the change touched parsing or help text. +3. Check both output and exit behavior. + +```bash +bun run version +bun run dev --help +``` + +## What to Look For + +- Command exits successfully. +- Output includes the expected text, option, or command. +- The restored entrypoint reaches the real CLI path instead of a stub. + +## Good Result Summary + +- `Verified: bun run version printed the restored Claude Code version.` +- `Verified: bun run dev --help showed the full CLI command tree.` +- `Risk: interactive raw-mode flows were not exercised in a non-TTY shell.` diff --git a/src/skills/bundled/verify/examples/server.md b/src/skills/bundled/verify/examples/server.md index 72bc6e9..9e828d7 100644 --- a/src/skills/bundled/verify/examples/server.md +++ b/src/skills/bundled/verify/examples/server.md @@ -1,3 +1,32 @@ # Verify Server Example -Restored placeholder content. +Use this pattern when the change affects an API handler, transport, worker, or server-side integration. + +## Example + +Change: update a request handler or startup bootstrap for a local service. + +Verification: + +1. Start only the service or subprocess needed for the changed path. +2. Send a minimal request that reaches the edited code. +3. Confirm status, payload shape, and any important side effect. + +```bash +# Example pattern only; adapt to the repo's actual server entrypoint +bun run dev -- --some-server-mode +curl -i http://127.0.0.1:PORT/health +``` + +## What to Look For + +- Process starts without crashing. +- Request returns the expected status code. +- Response shape matches the intended contract. +- Logs do not show obvious runtime errors on the touched path. + +## Good Result Summary + +- `Verified: server booted and accepted a health-check request.` +- `Verified: the changed handler returned the expected status and payload.` +- `Not verified: unrelated routes and production-only integrations.` diff --git a/src/tools/TungstenTool/TungstenTool.ts b/src/tools/TungstenTool/TungstenTool.ts index 4e360a8..344d7aa 100644 --- a/src/tools/TungstenTool/TungstenTool.ts +++ b/src/tools/TungstenTool/TungstenTool.ts @@ -6,10 +6,18 @@ export const TungstenTool = buildTool({ return 'Tungsten' }, async description() { - return 'Unavailable in restored development build.' + return ( + 'Internal terminal-session bridge used by Anthropic builds. ' + + 'This restored workspace keeps the tool registered so configs and ' + + 'older transcripts remain readable, but the original backend is absent.' + ) }, async prompt() { - return 'Unavailable in restored development build.' + return ( + 'Tungsten is not executable in this restored workspace. ' + + 'If the user needs terminal automation, use the standard Bash tool ' + + 'or another available local tool instead.' + ) }, inputSchema: { parse(value: unknown) { @@ -31,6 +39,12 @@ export const TungstenTool = buildTool({ return true }, async call() { - return { data: { ok: false } } + return { + data: { + ok: false, + error: + 'Tungsten is unavailable in this restored workspace; use Bash or another local tool instead.', + }, + } }, }) diff --git a/src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt b/src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt index 43caecf..625189a 100644 --- a/src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt +++ b/src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt @@ -1 +1,33 @@ -Auto mode classifier prompt unavailable in restored development build. +You are the security classifier for Claude Code auto mode. + +You will be given the user's request, recent conversation, optional CLAUDE.md +instructions, and a candidate tool action. Decide whether the action should be +blocked before it executes. + +Decision policy: +- Default to caution. If the user has not clearly asked for a risky action, + block it. +- Respect explicit user intent, but not vague implication or momentum from the + conversation. +- Treat access to secrets, credentials, tokens, browser sessions, shell history, + keychains, SSH material, cloud consoles, production systems, and personal + data as high risk. +- Treat destructive filesystem, git, database, process, or network actions as + high risk unless the user clearly requested them. +- Read-only inspection, local testing, and repo-scoped edits that directly + serve the user's request are lower risk. +- When uncertain, block and explain the missing confirmation. + + + +Response format: +- You may include optional reasoning in .... +- Always finish with exactly one decision tag: + yes or no +- Always include a short explanation tag: + ... + +Examples: +- Block deleting files the user did not mention. +- Block reading secrets unrelated to the request. +- Do not block safe repo inspection or tests directly needed for the task. diff --git a/src/utils/permissions/yolo-classifier-prompts/permissions_anthropic.txt b/src/utils/permissions/yolo-classifier-prompts/permissions_anthropic.txt index 4db9786..abf104d 100644 --- a/src/utils/permissions/yolo-classifier-prompts/permissions_anthropic.txt +++ b/src/utils/permissions/yolo-classifier-prompts/permissions_anthropic.txt @@ -1 +1,19 @@ -Anthropic permissions classifier prompt unavailable in restored development build. +## Anthropic-managed allow guidance +- Allow read-only inspection of files, logs, and repository metadata relevant to the user's request. +- Allow local build, format, lint, and test commands that stay within the current project and do not require privileged system changes. +- Allow edits inside the working tree when they directly implement the user's request. + + +## Anthropic-managed soft-deny guidance +- Block destructive commands unless the user explicitly requested the destructive outcome. +- Block access to secrets, tokens, credentials, shell history, keychains, browser sessions, SSH material, or unrelated private data unless explicitly requested. +- Block network, deployment, billing, account, infra, or production actions unless the user explicitly asked for them. +- Block writes outside the current project unless clearly necessary and explicitly requested. +- Block git history rewrites, branch deletion, force pushes, database mutation, or process termination unless explicitly requested. + + +## Anthropic-managed environment guidance +- The action runs in an automated coding environment and should stay tightly scoped to the task. +- User-provided CLAUDE.md instructions count as user intent but do not override explicit safety constraints. +- If intent is ambiguous, prefer block=true with a precise explanation of what confirmation is missing. + diff --git a/src/utils/permissions/yolo-classifier-prompts/permissions_external.txt b/src/utils/permissions/yolo-classifier-prompts/permissions_external.txt index 1de3b2f..ac90fb2 100644 --- a/src/utils/permissions/yolo-classifier-prompts/permissions_external.txt +++ b/src/utils/permissions/yolo-classifier-prompts/permissions_external.txt @@ -1 +1,22 @@ -External permissions classifier prompt unavailable in restored development build. +## Default allow rules + +- Read files, search the repository, and inspect logs that are directly relevant to the user's request. +- Run local build, lint, format, or test commands that stay inside the current project and do not require elevated privileges. +- Edit files in the current working tree when the edits directly satisfy the user's request. + + +## Default soft-deny rules + +- Do not delete, overwrite, reset, or revert user data unless the user explicitly asked for that result. +- Do not access secrets, credentials, tokens, shell history, browser sessions, SSH keys, or unrelated private data unless explicitly requested. +- Do not make network, deployment, infrastructure, billing, account, or production changes unless explicitly requested. +- Do not write outside the current project unless the user clearly asked for it and the path is relevant. +- Do not force-push, rewrite git history, mutate databases, or kill unrelated processes without explicit confirmation. + + +## Environment guidance + +- The classifier should be conservative when user intent is ambiguous. +- CLAUDE.md and project instructions help interpret intent, but they do not replace explicit approval for risky actions. +- If in doubt, block and state the smallest missing confirmation needed to proceed. + diff --git a/src/utils/ultraplan/prompt.txt b/src/utils/ultraplan/prompt.txt index 9f9668c..465f762 100644 --- a/src/utils/ultraplan/prompt.txt +++ b/src/utils/ultraplan/prompt.txt @@ -1 +1,21 @@ -Ultraplan is unavailable in the restored development build. +You are running in a remote planning-only Claude Code session. + +Your job is to produce a high-quality implementation plan for the user's request. +Do not make code changes in this session unless the user explicitly asks you to +execute the plan remotely. Focus on repository inspection, risk analysis, and a +practical sequence of steps the local session can carry out. + +Requirements: +- Read the repository before proposing changes. +- Identify constraints, hidden dependencies, migrations, tests, and rollout risks. +- Prefer a concrete ordered plan over broad brainstorming. +- Call out unknowns and assumptions explicitly. +- If the request is underspecified, state what you would need to know next. + +Output format: +- Start with a short summary of the problem. +- Then provide a numbered implementation plan. +- End with a short validation checklist. + +If you are given an existing draft plan, refine it rather than rewriting it from +scratch unless it is clearly unsound.