Use when user wants to "hand off to SDK", "run autonomous agent", "bridge CLI and SDK", "long-running tasks", "autonomous development", or mentions SDK bridge workflows. Provides comprehensive patterns for hybrid CLI/SDK development with the Claude Agent SDK.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Use when user wants to "hand off to SDK", "run autonomous agent", "bridge CLI and SDK", "long-running tasks", "autonomous development", or mentions SDK bridge workflows. Provides comprehensive patterns for hybrid CLI/SDK development with the Claude Agent SDK.
version
1.4.0
SDK Bridge Patterns
Bridge Claude Code CLI and Agent SDK for seamless hybrid workflows. Hand off long-running tasks to autonomous agents, monitor progress, and resume in CLI when complete.
Quick Reference
Commands:
/sdk-bridge:init - Initialize project for SDK bridge
/sdk-bridge:handoff - Hand off work to autonomous SDK agent
/sdk-bridge:status - Monitor progress
/sdk-bridge:resume - Resume in CLI after completion
/sdk-bridge:cancel - Stop running SDK agent
Workflow: Plan → Init → Handoff → Monitor → Resume
When to Use SDK Bridge
✅ Use SDK Bridge when:
Task has 10+ well-defined features to implement
You want autonomous progress while away
Task benefits from multi-session iteration
You've created a plan and want unattended execution
Features are testable and have clear completion criteria
❌ Don't use for:
Exploratory work (stay in CLI for interactivity)
Tasks requiring frequent user input or decisions
Simple single-feature changes
When you need to iterate on prompts or approaches
Core Workflow Pattern
Phase 1: Plan in CLI (Interactive)
Work interactively to create a comprehensive plan:
# Create plan with feature list
/plan
# Review generated feature_list.jsoncat feature_list.json | jq '.[] | {description, test}'# Refine if needed# Edit feature_list.json to clarify vague features# Ensure each feature has clear test criteria# Commit the plan
git add feature_list.json CLAUDE.md
git commit -m "Initial project plan"
Best practices:
Make features specific and testable
Order features by dependency
Include test criteria in each feature
15-50 features is ideal (too few: not worth automation, too many: risk of drift)
Phase 2: Initialize SDK Bridge
/sdk-bridge:init
This creates .claude/sdk-bridge.local.md with configuration:
Model selection (Sonnet vs Opus)
Session limits
Progress stall threshold
Auto-handoff settings
Review and customize the configuration for your project needs.
Phase 3: Handoff to SDK (Autonomous)
/sdk-bridge:handoff
What happens:
Validation: Handoff-validator agent checks:
feature_list.json exists with failing features
Git repository initialized
Harness and SDK installed
No conflicting SDK processes
API authentication configured
Launch: If validation passes:
Harness starts in background with nohup
PID saved to .claude/sdk-bridge.pid
Output logged to .claude/sdk-bridge.log
Tracking created in .claude/handoff-context.json
Autonomous Work: SDK agent:
Reads feature_list.json and claude-progress.txt
Implements ONE feature per session
Tests implementation
Updates passes: true in feature_list.json
Logs progress to claude-progress.txt
Commits to git
Repeats until complete or limit reached
You can close the CLI - the SDK agent runs independently.
DEBUG: Verbose output including API auth method, agent responses
INFO: Standard progress messages
WARNING: Only warnings and errors
ERROR: Only error messages
webhook_url [v1.4.0]: Optional webhook for notifications
Receives POST requests with JSON payloads
Events: feature_complete, error, completion
Leave empty to disable
Common Patterns
Pattern 1: Standard Long-Running Development
# Day 1: Planning
/plan
# Create 40 features for a new web app
/sdk-bridge:init
/sdk-bridge:handoff
# Close laptop, go home# Day 2: Check progress
/sdk-bridge:status
# 32/40 features passing, 12 sessions used# Day 3: SDK completes
/sdk-bridge:resume
# Review: 38/40 done, 2 features need clarification# Fix issues manually, continue development
/sdk-bridge:status
# If progress seems slowtail -50 .claude/sdk-bridge.log
# If stuck on one feature
grep "Feature #N" claude-progress.txt
5. Commit Often (Manually)
Before handoff, commit your plan:
git add .
git commit -m "Initial plan with 40 features"
After resume, review and commit:
git log --oneline -20 # Review SDK commits# If satisfied
git commit -m "SDK completed features 1-38"# If not
git reset --hard HEAD~5 # Revert last 5 commits
6. Reserve Sessions Wisely
If SDK uses 18/20 sessions and stops:
2 sessions reserved for you to:
Manually complete hard features
Fix issues SDK couldn't resolve
Wrap up and test
7. Use Stall Detection
If SDK attempts same feature 3+ times:
Feature description likely too vague
Feature may be blocked on external dependency
Edit feature_list.json to clarify or skip
8. Test Before Large Handoffs
Try with a small test:
# Create 5-feature test planecho'[...]' > feature_list.json
/sdk-bridge:handoff
# Wait 15 minutes
/sdk-bridge:status
# If working well, scale up to full plan
Troubleshooting
SDK Won't Start
# Check logscat .claude/sdk-bridge.log
# Common issues:# 1. API key not setecho$ANTHROPIC_API_KEY# Should not be empty# Or use OAuth: claude setup-token# 2. SDK not installed
python3 -c "import claude_agent_sdk"# 3. Harness missingls ~/.claude/skills/long-running-agent/harness/autonomous_agent.py
# If missing: /user:lra-setup# 4. Git not initialized
git status
# If not a repo: git init
/sdk-bridge:resume
# Shows: "❌ Tests failing"# Check which tests
npm test# or pytest# Common issues:# - SDK implemented feature but tests need update# - Edge cases not covered# - Environment differences (API keys, DB)# Fix:# Update tests or implementation
git add .
git commit -m "Fix edge cases found by tests"
Completion Not Detected
# SDK stopped but no completion signal
ps aux | grep autonomous_agent # Not running# Check logs for errorstail -100 .claude/sdk-bridge.log
# Manually check progress
jq '.[] | select(.passes==false) | .description' feature_list.json
# If work complete, manually resumecat > .claude/sdk_complete.json << EOF
{
"timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"reason": "manual_completion",
"session_count": 15
}
EOF
/sdk-bridge:resume
High API Costs
# Use Sonnet instead of Opus# Edit .claude/sdk-bridge.local.md:
model: claude-sonnet-4-5-20250929
# Reduce max sessions
max_sessions: 15 # Instead of 30# Better features = fewer retries# Make feature descriptions clearer
Advanced Patterns
Custom Completion Signals
SDK can signal early completion:
{"timestamp":"2025-12-15T10:30:00Z","reason":"blocked_on_external_dependency","session_count":8,"exit_code":2,"message":"Need Stripe API keys before continuing","blocking_features":[23,24,25]}
This allows graceful handback when SDK encounters blockers.
Project-Specific Protocols
Create .claude/CLAUDE.md with project-specific guidance:
# Project Protocol## Code Standards- Use TypeScript strict mode
- All functions must have JSDoc comments
- Tests required for all public APIs
## Testing- Run `npm test` after each feature
- Feature passes only if all tests pass
- Add tests before implementation
## Git- Commit after each passing feature
- Use conventional commit format
- Never force push
The SDK reads this before each session.
Multi-Agent Workflows
Use different models for different work:
# Use Opus for complex features
model: claude-opus-4-5-20251101
/sdk-bridge:handoff
# ... completes complex features ...
/sdk-bridge:resume
# Switch to Sonnet for simple features# Edit .claude/sdk-bridge.local.md:
model: claude-sonnet-4-5-20250929
/sdk-bridge:handoff
# ... completes remaining simple features ...
Version 1.4.0 Features
SDK Bridge 1.4.0 introduces several production-quality improvements to the autonomous agent harness.
Retry Logic with Exponential Backoff
The harness now automatically retries failed sessions with exponential backoff delays:
3 retry attempts per session on transient errors
Exponential backoff: 1s, 2s, 4s delays between retries
Only retries on exceptions/errors, not on feature implementation failures
Prevents API rate limiting and handles temporary network issues
[2025-01-06 10:30:00] [WARNING] Session attempt 1 failed with error: Connection timeout
[2025-01-06 10:30:01] [INFO] Retry attempt 2/3 after 1s delay
[2025-01-06 10:30:03] [INFO] Retry attempt 3/3 after 2s delay
Progress Persistence Across Crashes
State is now saved to .claude/sdk-checkpoint.json after each feature, enabling recovery after crashes:
Control execution order with the priority field in feature_list.json:
Feature list with priorities:
[{"description":"Set up database schema","test":"migrations run successfully","passes":false,"priority":100},{"description":"User authentication","test":"login/logout works","passes":false,"priority":90},{"description":"Nice-to-have feature","test":"works as expected","passes":false,"priority":10},{"description":"Default priority feature","test":"works correctly","passes":false}]
Priority behavior:
Higher numbers execute first (100 before 90 before 10)
Default priority is 0 if not specified
Features with same priority preserve original order
Completed features are skipped regardless of priority
Best practices:
Use 100 for critical infrastructure (DB, auth)
Use 50 for core features
Use 10 for nice-to-haves
Use 0 (default) for unordered features
New State Files
Version 1.4.0 adds:
File
Purpose
Managed By
.claude/sdk-checkpoint.json
Crash recovery state
Harness
Configuration Reference (1.4.0)
New configuration options in .claude/sdk-bridge.local.md:
---enabled:truemodel:claude-sonnet-4-5-20250929max_sessions:20reserve_sessions:2progress_stall_threshold:3auto_handoff_after_plan:false# New in 1.4.0:log_level:INFO# DEBUG, INFO, WARNING, ERRORwebhook_url:https://...# Optional webhook endpoint---
