{
  "schemaVersion": "1.0",
  "item": {
    "slug": "opencode-api-control-skill",
    "name": "OpenCode CLI  API Controller",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/malek262/opencode-api-control-skill",
    "canonicalUrl": "https://clawhub.ai/malek262/opencode-api-control-skill",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/opencode-api-control-skill",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=opencode-api-control-skill",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "config.json",
      "README.md",
      "SKILL.md",
      "Reference/STATE_MANAGEMENT.md",
      "Reference/COMPLETE_EXAMPLES.md",
      "Reference/EVENTS_GUIDE.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/opencode-api-control-skill"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/opencode-api-control-skill",
    "agentPageUrl": "https://openagent3.xyz/skills/opencode-api-control-skill/agent",
    "manifestUrl": "https://openagent3.xyz/skills/opencode-api-control-skill/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/opencode-api-control-skill/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "OpenCode CLI API Control",
        "body": "[!IMPORTANT]\nOPERATIONAL GUIDELINES:\nWhile you may use ls or basic file system checks to verify that files/directories exist, you are EXPLICITLY PROHIBITED from reading or modifying the project's source code files directly.\nYour primary channel for task execution and progress monitoring is the OpenCode API and the provided scripts."
      },
      {
        "title": "Overview",
        "body": "This skill provides a set of tools to programmatically interface with the Open Code CLI through its local web server API. It enables you to act as a Supervisor/Orchestrator who directs OpenCode to handle all coding, file operations, and quality checks."
      },
      {
        "title": "Core Mandate: Orchestrator vs. Executor",
        "body": "You are NOT the Coder: You do not write or verify code directly. OpenCode handles the implementation.\nYou are the Orchestrator: You send high-level instructions to OpenCode, monitor its progress, and report the outcome to the user.\nTrust the System: OpenCode is responsible for its own file operations. Your job is to wait for it to finish and then check the status and diff summary, not the file contents."
      },
      {
        "title": "When to Use",
        "body": "User requests creating or managing projects through OpenCode\nUser asks for coding tasks, debugging, or code analysis via OpenCode\nUser wants AI-powered development with specific providers/models\nUser needs to manage multiple OpenCode sessions or monitor tasks"
      },
      {
        "title": "Prerequisites",
        "body": "OpenCode server running (Preferred: bash ./scripts/start_server.sh)\nConfiguration file exists: ./config.json\nRequired scripts in ./scripts/ directory"
      },
      {
        "title": "Configuration",
        "body": "Read settings from ./config.json:\n\nBASE_URL=$(jq -r '.base_url' ./config.json)\nPROJECTS_DIR=$(jq -r '.projects_base_dir' ./config.json)"
      },
      {
        "title": "Your Role as Orchestrator",
        "body": "You are the supervisor and communication bridge between the user and OpenCode.\n\nOperational Boundaries:\n\n❌ NEVER read or edit the code files generated by OpenCode directly for development tasks.\n❌ NEVER try to fix or verify code logic by inspecting the project files yourself.\n✅ MAY use ls or simple directory checks only to confirm file existence if necessary.\n⚠️ PREFER using the provided scripts and API for all project-related information.\n\nRequired Workflow:\n\n✅ PRIMARY: Use monitor_session.sh or check_status.sh to track progress.\n✅ PRIMARY: Use get_diff.sh to see a summary of what was changed.\n✅ ALWAYS report the results based on the API response or script output.\n✅ TRUST OpenCode's implementation of the requested features."
      },
      {
        "title": "Server Initialization Wait",
        "body": "CRITICAL: After starting OpenCode web server, it takes 10-15 seconds to fully initialize. You MUST verify server readiness before sending any requests.\n\nCorrect initialization sequence:\n\n# Start server using the robust backgrounding script\nbash ./scripts/start_server.sh\n\n\n# 3. Now safe to proceed with operations\nbash ./scripts/update_providers.sh\n# ... continue workflow\n\nNever send requests immediately after starting the server - always verify health first."
      },
      {
        "title": "Intelligent Task Monitoring",
        "body": "For long-running tasks, use smart monitoring strategies:\n\nOption 1: Event-based monitoring (Recommended)\n\n# Start task\nbash ./scripts/send_message.sh \"Complex task\" &\n\n# Monitor events (blocks until completion)\nbash ./scripts/monitor_session.sh\n\nOption 2: Intelligent polling\n\n# For environments where event streaming is unreliable\nbash ./scripts/send_message.sh \"Build application\"\n\n# Smart polling with exponential backoff\nSLEEP_TIME=2\nMAX_SLEEP=30\n\nwhile true; do\n  STATUS=$(bash ./scripts/check_status.sh)\n  \n  if [ \"$STATUS\" = \"idle\" ]; then\n    echo \"✓ Task completed\"\n    break\n  elif [ \"$STATUS\" = \"busy\" ]; then\n    echo \"⟳ Still working... (checking again in ${SLEEP_TIME}s)\"\n    sleep $SLEEP_TIME\n    \n    # Increase wait time (but cap at MAX_SLEEP)\n    SLEEP_TIME=$((SLEEP_TIME < MAX_SLEEP ? SLEEP_TIME + 2 : MAX_SLEEP))\n  else\n    echo \"⚠ Unexpected status: $STATUS\"\n    break\n  fi\ndone\n\nOption 3: Timeout-based waiting\n\n# For predictable task durations\nbash ./scripts/send_message.sh \"Quick task\"\n\n# Wait reasonable time before checking\nsleep 10\n\n# Then check once\nif [ \"$(bash ./scripts/check_status.sh)\" = \"idle\" ]; then\n  bash ./scripts/get_diff.sh\nfi\n\nAnti-patterns to AVOID:\n\n❌ Checking status every 1-2 seconds (wastes resources)\n❌ Reading files repeatedly to see if task is done\n❌ Using ls or file system checks for progress\n❌ Making multiple API calls without waiting\n\nBest practices:\n\n✅ Use monitor_session.sh for real-time updates\n✅ Use exponential backoff for polling (start 2s, increase to 30s)\n✅ Estimate task duration and wait appropriately\n✅ Only check final results after confirmation of completion\n✅ Let OpenCode agents work independently - don't micromanage"
      },
      {
        "title": "Task Initiation Protocol",
        "body": "Before starting any task (new project, code analysis, debugging, etc.), ask the user in ONE message:\n\nI'll help you with that. Two quick questions:\n\nProvider: Use default from config, or specify a provider (opencode, anthropic, gemini, etc.)?\nMonitoring:\n\nStandard (recommended): Send task → wait for completion summary → notify you when done (saves tokens)\nReal-time: Show live progress, file edits, and events as they happen (uses more tokens)\n\n\n\nHow would you like to proceed?\n\nDefault if not specified: Use config defaults + Standard mode."
      },
      {
        "title": "Why This Matters",
        "body": "Standard mode: Uses send_message.sh → waits → shows final summary. Efficient for most tasks.\nReal-time mode: Uses monitor_session.sh with event streaming. Good for long/complex tasks where you want visibility."
      },
      {
        "title": "Example Response Handling",
        "body": "\"Default provider, standard mode\" → Proceed immediately\n\"Use Claude Sonnet, real-time\" → Run select_provider.sh then monitor_session.sh\n\"Gemini Pro\" → Find provider + ask monitoring preference if not specified"
      },
      {
        "title": "Task Completion Verification",
        "body": "When a task completes, get summary via:\n\n# Get file changes summary (not individual files)\nbash ./scripts/get_diff.sh\n\n# Output example:\n# added: src/App.tsx (+120/-0)\n# modified: package.json (+5/-2)\n# added: src/components/Dashboard.tsx (+89/-0)\n\nThis gives you all information needed to report to the user without reading actual file contents.\n\nOnly read specific files if:\n\nUser explicitly asks to see code\nUser requests explanation of specific implementation\nDebugging a reported issue\n\nOtherwise, trust the diff summary and OpenCode's implementation."
      },
      {
        "title": "Step 1: Verify Server",
        "body": "# Check health\ncurl -s \"$BASE_URL/global/health\" | jq\n\n# Expected: {\"healthy\": true, \"version\": \"...\"}"
      },
      {
        "title": "Step 2: Update Providers Cache",
        "body": "# Run provider update script\nbash ./scripts/update_providers.sh\n\nThis caches only connected providers to ./providers.json."
      },
      {
        "title": "Step 3: Create or Select Project",
        "body": "New Project:\n\nPROJECT_NAME=\"dashboard-app\"\nPROJECT_PATH=\"$PROJECTS_DIR/$PROJECT_NAME\"\nmkdir -p \"$PROJECT_PATH\"\n\nExisting Project:\n\nPROJECT_NAME=\"existing-app\"\nPROJECT_PATH=\"$PROJECTS_DIR/$PROJECT_NAME\"\n# Verify exists\n[ -d \"$PROJECT_PATH\" ] || { echo \"Project not found\"; exit 1; }"
      },
      {
        "title": "Step 4: Create Session",
        "body": "Create a session in the project directory using the provided script:\n\nSESSION_ID=$(bash ./scripts/create_session.sh \"$PROJECT_PATH\" \"Session Title\")"
      },
      {
        "title": "Step 5: Save Session State",
        "body": "# Use state management script\nbash ./scripts/save_state.sh \"$SESSION_ID\" \"$PROJECT_PATH\""
      },
      {
        "title": "Step 6: Send Message",
        "body": "Use the provided script to send prompts to the AI:\n\n# Use defaults from config\nbash ./scripts/send_message.sh \"Your prompt here\"\n\n# Or use a specific provider and model\nbash ./scripts/send_message.sh \"Your prompt\" \"anthropic\" \"claude-sonnet-4-5\""
      },
      {
        "title": "Step 7: Monitor Progress (For Long Tasks)",
        "body": "# Start monitoring in background\nbash ./scripts/monitor_session.sh &\n\n# Or check status periodically\nbash ./scripts/check_status.sh"
      },
      {
        "title": "Automatic (uses default from config.json)",
        "body": "bash ./scripts/send_message.sh \"Create app\""
      },
      {
        "title": "User Specifies Provider",
        "body": "When the user specifies a provider (e.g., \"use Gemini Pro\" or \"with Claude Sonnet\"), use the search script:\n\n# Search for provider and model hints\nRESULT=$(bash ./scripts/select_provider.sh \"gemini\" \"pro\")\n# Returns: gemini gemini-3-pro\n\n# Extract and use the returned values\nPROVIDER_ID=$(echo \"$RESULT\" | cut -d' ' -f1)\nMODEL_ID=$(echo \"$RESULT\" | cut -d' ' -f2)\n\nbash ./scripts/send_message.sh \"Your prompt\" \"$PROVIDER_ID\" \"$MODEL_ID\""
      },
      {
        "title": "Agent Selection",
        "body": "Default (no agent specified - recommended):\n\nbash ./scripts/send_message.sh \"Build app\"\n\nPlanning phase:\n\nbash ./scripts/send_message.sh \"Analyze requirements\" \"plan\"\n\nImplementation phase:\n\nbash ./scripts/send_message.sh \"Implement features\" \"build\""
      },
      {
        "title": "Pattern 1: New Project from Scratch",
        "body": "# 1. Update providers\nbash ./scripts/update_providers.sh\n\n# 2. Create project directory\nmkdir -p \"$PROJECTS_DIR/new-app\"\n\n# 3. Create session\nSESSION_ID=$(bash ./scripts/create_session.sh \"$PROJECTS_DIR/new-app\" \"New App\")\n\n# 4. Send initial task\nbash ./scripts/send_message.sh \"Create React app with TypeScript and Tailwind\"\n\n# 5. Monitor progress\nbash ./scripts/monitor_session.sh"
      },
      {
        "title": "Pattern 2: Continue Existing Project",
        "body": "# 1. Load saved project state\nbash ./scripts/load_project.sh \"existing-app\"\n\n# 2. Send new task\nbash ./scripts/send_message.sh \"Add authentication feature\""
      },
      {
        "title": "Pattern 3: Multi-Phase Development",
        "body": "# Phase 1: Planning\nbash ./scripts/create_session.sh \"$PROJECT_PATH\" \"Planning\"\nbash ./scripts/send_message.sh \"Plan e-commerce platform\" \"plan\"\n\n# Phase 2: Implementation\nbash ./scripts/send_message.sh \"Implement the plan\" \"build\"\n\n# Phase 3: Review\nbash ./scripts/get_diff.sh"
      },
      {
        "title": "Pattern 4: Use Specific Provider",
        "body": "# User says: \"Create dashboard using Claude Sonnet\"\n\n# 1. Select provider\nPROVIDER_MODEL=$(bash ./scripts/select_provider.sh \"claude\" \"sonnet\")\nPROVIDER_ID=$(echo \"$PROVIDER_MODEL\" | cut -d' ' -f1)\nMODEL_ID=$(echo \"$PROVIDER_MODEL\" | cut -d' ' -f2)\n\n# 2. Create project and session\nmkdir -p \"$PROJECTS_DIR/dashboard\"\nSESSION_ID=$(bash ./scripts/create_session.sh \"$PROJECTS_DIR/dashboard\" \"Dashboard\")\n\n# 3. Send with selected provider\nbash ./scripts/send_message.sh \"Create dashboard\" \"$PROVIDER_ID\" \"$MODEL_ID\""
      },
      {
        "title": "Event Monitoring",
        "body": "For long-running tasks, monitor events:\n\n# Start monitoring (shows progress in real-time)\nbash ./scripts/monitor_session.sh\n\n# This will:\n# - Show text deltas as they're generated\n# - Display status changes (busy/idle)\n# - Show final token count and cost\n# - Exit when task completes"
      },
      {
        "title": "State Management",
        "body": "All session state is saved in ./state/:\n\n# Save current session\nbash ./scripts/save_state.sh \"$SESSION_ID\" \"$PROJECT_PATH\"\n\n# Load state (sets environment variables)\nsource ./scripts/load_state.sh\necho $SESSION_ID\necho $PROJECT_PATH\n\n# Save project-specific state\nbash ./scripts/save_project.sh \"project-name\"\n\n# Load project-specific state\nbash ./scripts/load_project.sh \"project-name\"\n\n# List all saved projects\nls -1 ./state/*.json | grep -v current.json | xargs -n1 basename .json"
      },
      {
        "title": "File Operations",
        "body": "Get session changes:\n\nbash ./scripts/get_diff.sh\n\nGet file content:\n\ncurl -s \"$BASE_URL/file/content?directory=$PROJECT_PATH&path=src/App.tsx\" \\\n  jq -r '.content'\n\nList directory:\n\ncurl -s \"$BASE_URL/file?directory=$PROJECT_PATH&path=src\" \\\n  jq -r '.[] | \"\\(.type): \\(.path)\"'"
      },
      {
        "title": "Error Handling",
        "body": "All scripts return proper exit codes:\n\n0 = Success\n1 = Error\n\nCheck script status:\n\nif bash ./scripts/send_message.sh \"prompt\"; then\n  echo \"Success\"\nelse\n  echo \"Failed - check server or authentication\"\nfi"
      },
      {
        "title": "Authentication",
        "body": "This skill assumes the OpenCode server is running in a trusted local environment and does not use password authentication by default."
      },
      {
        "title": "Quick Reference",
        "body": "TaskCommandUpdate providersbash ./scripts/update_providers.shCreate sessionbash ./scripts/create_session.sh \"$PATH\" \"Title\"Send messagebash ./scripts/send_message.sh \"prompt\"With providerbash ./scripts/send_message.sh \"prompt\" \"provider\" \"model\"Monitor progressbash ./scripts/monitor_session.shCheck statusbash ./scripts/check_status.shGet changesbash ./scripts/get_diff.shSave statebash ./scripts/save_state.sh \"$SID\" \"$PATH\"Load statesource ./scripts/load_state.shSave projectbash ./scripts/save_project.sh \"name\"Load projectbash ./scripts/load_project.sh \"name\"Select providerbash ./scripts/select_provider.sh \"name\" \"model\""
      },
      {
        "title": "Important Notes",
        "body": "Always run from skill directory: Scripts use relative paths\nUpdate providers at workflow start: Ensures cache is fresh\nCreate projects in PROJECTS_BASE_DIR: Configured in config.json\nEach session belongs to one project directory: Don't mix\nLoad state before curl commands: Ensures variables are set\nScripts handle authentication: No need to add headers manually"
      },
      {
        "title": "Troubleshooting",
        "body": "\"No active session\":\n\n# Load or create session first\nbash ./scripts/create_session.sh \"$PROJECT_PATH\" \"Title\"\n\n\"Provider not found\":\n\n# Update providers cache\nbash ./scripts/update_providers.sh\n\n# Check available providers\njq -r '.providers[] | .id' ./providers.json\n\n\"HTML response instead of JSON\":\n\nMissing directory parameter\nCheck: Are you using full PROJECT_PATH?"
      },
      {
        "title": "Advanced Usage",
        "body": "For complex workflows, state management, or advanced patterns, see:\n\nReference/STATE_MANAGEMENT.md - Advanced state handling\nReference/PROVIDERS_REFERENCE.md - Provider selection details\nReference/EVENTS_GUIDE.md - Event monitoring patterns\nReference/COMPLETE_EXAMPLES.md - Full workflow examples\nReference/API_QUICK_REFERENCE.md - Raw API endpoints"
      },
      {
        "title": "Directory Structure",
        "body": "opencode-api-control/\n├── SKILL.md                    # This file\n├── config.json                 # Configuration\n├── providers.json              # Connected providers cache\n├── scripts/                    # Helper scripts\n│   ├── update_providers.sh\n│   ├── create_session.sh\n│   ├── send_message.sh\n│   ├── monitor_session.sh\n│   ├── check_status.sh\n│   ├── get_diff.sh\n│   ├── save_state.sh\n│   ├── load_state.sh\n│   ├── save_project.sh\n│   ├── load_project.sh\n│   └── select_provider.sh\n├── state/                      # Session state\n│   ├── current.json\n│   └── project-name.json\n└── Reference/                       # Reference docs\n    ├── STATE_MANAGEMENT.md\n    ├── PROVIDERS_REFERENCE.md\n    ├── EVENTS_GUIDE.md\n    ├── COMPLETE_EXAMPLES.md\n    └── API_QUICK_REFERENCE.md\n\nAuthor: Malek RSH | Repository: OpenCode-CLI-Controller"
      }
    ],
    "body": "OpenCode CLI API Control\n\n[!IMPORTANT] OPERATIONAL GUIDELINES: While you may use ls or basic file system checks to verify that files/directories exist, you are EXPLICITLY PROHIBITED from reading or modifying the project's source code files directly. Your primary channel for task execution and progress monitoring is the OpenCode API and the provided scripts.\n\nOverview\n\nThis skill provides a set of tools to programmatically interface with the Open Code CLI through its local web server API. It enables you to act as a Supervisor/Orchestrator who directs OpenCode to handle all coding, file operations, and quality checks.\n\nCore Mandate: Orchestrator vs. Executor\nYou are NOT the Coder: You do not write or verify code directly. OpenCode handles the implementation.\nYou are the Orchestrator: You send high-level instructions to OpenCode, monitor its progress, and report the outcome to the user.\nTrust the System: OpenCode is responsible for its own file operations. Your job is to wait for it to finish and then check the status and diff summary, not the file contents.\nWhen to Use\nUser requests creating or managing projects through OpenCode\nUser asks for coding tasks, debugging, or code analysis via OpenCode\nUser wants AI-powered development with specific providers/models\nUser needs to manage multiple OpenCode sessions or monitor tasks\nPrerequisites\nOpenCode server running (Preferred: bash ./scripts/start_server.sh)\nConfiguration file exists: ./config.json\nRequired scripts in ./scripts/ directory\nConfiguration\n\nRead settings from ./config.json:\n\nBASE_URL=$(jq -r '.base_url' ./config.json)\nPROJECTS_DIR=$(jq -r '.projects_base_dir' ./config.json)\n\nImportant Agent Responsibilities\nYour Role as Orchestrator\n\nYou are the supervisor and communication bridge between the user and OpenCode.\n\nOperational Boundaries:\n\n❌ NEVER read or edit the code files generated by OpenCode directly for development tasks.\n❌ NEVER try to fix or verify code logic by inspecting the project files yourself.\n✅ MAY use ls or simple directory checks only to confirm file existence if necessary.\n⚠️ PREFER using the provided scripts and API for all project-related information.\n\nRequired Workflow:\n\n✅ PRIMARY: Use monitor_session.sh or check_status.sh to track progress.\n✅ PRIMARY: Use get_diff.sh to see a summary of what was changed.\n✅ ALWAYS report the results based on the API response or script output.\n✅ TRUST OpenCode's implementation of the requested features.\nServer Initialization Wait\n\nCRITICAL: After starting OpenCode web server, it takes 10-15 seconds to fully initialize. You MUST verify server readiness before sending any requests.\n\nCorrect initialization sequence:\n\n# Start server using the robust backgrounding script\nbash ./scripts/start_server.sh\n\n\n# 3. Now safe to proceed with operations\nbash ./scripts/update_providers.sh\n# ... continue workflow\n\n\nNever send requests immediately after starting the server - always verify health first.\n\nIntelligent Task Monitoring\n\nFor long-running tasks, use smart monitoring strategies:\n\nOption 1: Event-based monitoring (Recommended)\n\n# Start task\nbash ./scripts/send_message.sh \"Complex task\" &\n\n# Monitor events (blocks until completion)\nbash ./scripts/monitor_session.sh\n\n\nOption 2: Intelligent polling\n\n# For environments where event streaming is unreliable\nbash ./scripts/send_message.sh \"Build application\"\n\n# Smart polling with exponential backoff\nSLEEP_TIME=2\nMAX_SLEEP=30\n\nwhile true; do\n  STATUS=$(bash ./scripts/check_status.sh)\n  \n  if [ \"$STATUS\" = \"idle\" ]; then\n    echo \"✓ Task completed\"\n    break\n  elif [ \"$STATUS\" = \"busy\" ]; then\n    echo \"⟳ Still working... (checking again in ${SLEEP_TIME}s)\"\n    sleep $SLEEP_TIME\n    \n    # Increase wait time (but cap at MAX_SLEEP)\n    SLEEP_TIME=$((SLEEP_TIME < MAX_SLEEP ? SLEEP_TIME + 2 : MAX_SLEEP))\n  else\n    echo \"⚠ Unexpected status: $STATUS\"\n    break\n  fi\ndone\n\n\nOption 3: Timeout-based waiting\n\n# For predictable task durations\nbash ./scripts/send_message.sh \"Quick task\"\n\n# Wait reasonable time before checking\nsleep 10\n\n# Then check once\nif [ \"$(bash ./scripts/check_status.sh)\" = \"idle\" ]; then\n  bash ./scripts/get_diff.sh\nfi\n\n\nAnti-patterns to AVOID:\n\n❌ Checking status every 1-2 seconds (wastes resources)\n❌ Reading files repeatedly to see if task is done\n❌ Using ls or file system checks for progress\n❌ Making multiple API calls without waiting\n\nBest practices:\n\n✅ Use monitor_session.sh for real-time updates\n✅ Use exponential backoff for polling (start 2s, increase to 30s)\n✅ Estimate task duration and wait appropriately\n✅ Only check final results after confirmation of completion\n✅ Let OpenCode agents work independently - don't micromanage\nTask Initiation Protocol\n\nBefore starting any task (new project, code analysis, debugging, etc.), ask the user in ONE message:\n\nI'll help you with that. Two quick questions:\n\nProvider: Use default from config, or specify a provider (opencode, anthropic, gemini, etc.)?\nMonitoring:\nStandard (recommended): Send task → wait for completion summary → notify you when done (saves tokens)\nReal-time: Show live progress, file edits, and events as they happen (uses more tokens)\n\nHow would you like to proceed?\n\nDefault if not specified: Use config defaults + Standard mode.\n\nWhy This Matters\nStandard mode: Uses send_message.sh → waits → shows final summary. Efficient for most tasks.\nReal-time mode: Uses monitor_session.sh with event streaming. Good for long/complex tasks where you want visibility.\nExample Response Handling\n\"Default provider, standard mode\" → Proceed immediately\n\"Use Claude Sonnet, real-time\" → Run select_provider.sh then monitor_session.sh\n\"Gemini Pro\" → Find provider + ask monitoring preference if not specified\nTask Completion Verification\n\nWhen a task completes, get summary via:\n\n# Get file changes summary (not individual files)\nbash ./scripts/get_diff.sh\n\n# Output example:\n# added: src/App.tsx (+120/-0)\n# modified: package.json (+5/-2)\n# added: src/components/Dashboard.tsx (+89/-0)\n\n\nThis gives you all information needed to report to the user without reading actual file contents.\n\nOnly read specific files if:\n\nUser explicitly asks to see code\nUser requests explanation of specific implementation\nDebugging a reported issue\n\nOtherwise, trust the diff summary and OpenCode's implementation.\n\nCore Workflow\nStep 1: Verify Server\n# Check health\ncurl -s \"$BASE_URL/global/health\" | jq\n\n# Expected: {\"healthy\": true, \"version\": \"...\"}\n\nStep 2: Update Providers Cache\n# Run provider update script\nbash ./scripts/update_providers.sh\n\n\nThis caches only connected providers to ./providers.json.\n\nStep 3: Create or Select Project\n\nNew Project:\n\nPROJECT_NAME=\"dashboard-app\"\nPROJECT_PATH=\"$PROJECTS_DIR/$PROJECT_NAME\"\nmkdir -p \"$PROJECT_PATH\"\n\n\nExisting Project:\n\nPROJECT_NAME=\"existing-app\"\nPROJECT_PATH=\"$PROJECTS_DIR/$PROJECT_NAME\"\n# Verify exists\n[ -d \"$PROJECT_PATH\" ] || { echo \"Project not found\"; exit 1; }\n\nStep 4: Create Session\n\nCreate a session in the project directory using the provided script:\n\nSESSION_ID=$(bash ./scripts/create_session.sh \"$PROJECT_PATH\" \"Session Title\")\n\nStep 5: Save Session State\n# Use state management script\nbash ./scripts/save_state.sh \"$SESSION_ID\" \"$PROJECT_PATH\"\n\nStep 6: Send Message\n\nUse the provided script to send prompts to the AI:\n\n# Use defaults from config\nbash ./scripts/send_message.sh \"Your prompt here\"\n\n# Or use a specific provider and model\nbash ./scripts/send_message.sh \"Your prompt\" \"anthropic\" \"claude-sonnet-4-5\"\n\nStep 7: Monitor Progress (For Long Tasks)\n# Start monitoring in background\nbash ./scripts/monitor_session.sh &\n\n# Or check status periodically\nbash ./scripts/check_status.sh\n\nProvider Selection\nAutomatic (uses default from config.json)\nbash ./scripts/send_message.sh \"Create app\"\n\nUser Specifies Provider\n\nWhen the user specifies a provider (e.g., \"use Gemini Pro\" or \"with Claude Sonnet\"), use the search script:\n\n# Search for provider and model hints\nRESULT=$(bash ./scripts/select_provider.sh \"gemini\" \"pro\")\n# Returns: gemini gemini-3-pro\n\n# Extract and use the returned values\nPROVIDER_ID=$(echo \"$RESULT\" | cut -d' ' -f1)\nMODEL_ID=$(echo \"$RESULT\" | cut -d' ' -f2)\n\nbash ./scripts/send_message.sh \"Your prompt\" \"$PROVIDER_ID\" \"$MODEL_ID\"\n\nAgent Selection\n\nDefault (no agent specified - recommended):\n\nbash ./scripts/send_message.sh \"Build app\"\n\n\nPlanning phase:\n\nbash ./scripts/send_message.sh \"Analyze requirements\" \"plan\"\n\n\nImplementation phase:\n\nbash ./scripts/send_message.sh \"Implement features\" \"build\"\n\nCommon Patterns\nPattern 1: New Project from Scratch\n# 1. Update providers\nbash ./scripts/update_providers.sh\n\n# 2. Create project directory\nmkdir -p \"$PROJECTS_DIR/new-app\"\n\n# 3. Create session\nSESSION_ID=$(bash ./scripts/create_session.sh \"$PROJECTS_DIR/new-app\" \"New App\")\n\n# 4. Send initial task\nbash ./scripts/send_message.sh \"Create React app with TypeScript and Tailwind\"\n\n# 5. Monitor progress\nbash ./scripts/monitor_session.sh\n\nPattern 2: Continue Existing Project\n# 1. Load saved project state\nbash ./scripts/load_project.sh \"existing-app\"\n\n# 2. Send new task\nbash ./scripts/send_message.sh \"Add authentication feature\"\n\nPattern 3: Multi-Phase Development\n# Phase 1: Planning\nbash ./scripts/create_session.sh \"$PROJECT_PATH\" \"Planning\"\nbash ./scripts/send_message.sh \"Plan e-commerce platform\" \"plan\"\n\n# Phase 2: Implementation\nbash ./scripts/send_message.sh \"Implement the plan\" \"build\"\n\n# Phase 3: Review\nbash ./scripts/get_diff.sh\n\nPattern 4: Use Specific Provider\n# User says: \"Create dashboard using Claude Sonnet\"\n\n# 1. Select provider\nPROVIDER_MODEL=$(bash ./scripts/select_provider.sh \"claude\" \"sonnet\")\nPROVIDER_ID=$(echo \"$PROVIDER_MODEL\" | cut -d' ' -f1)\nMODEL_ID=$(echo \"$PROVIDER_MODEL\" | cut -d' ' -f2)\n\n# 2. Create project and session\nmkdir -p \"$PROJECTS_DIR/dashboard\"\nSESSION_ID=$(bash ./scripts/create_session.sh \"$PROJECTS_DIR/dashboard\" \"Dashboard\")\n\n# 3. Send with selected provider\nbash ./scripts/send_message.sh \"Create dashboard\" \"$PROVIDER_ID\" \"$MODEL_ID\"\n\nEvent Monitoring\n\nFor long-running tasks, monitor events:\n\n# Start monitoring (shows progress in real-time)\nbash ./scripts/monitor_session.sh\n\n# This will:\n# - Show text deltas as they're generated\n# - Display status changes (busy/idle)\n# - Show final token count and cost\n# - Exit when task completes\n\nState Management\n\nAll session state is saved in ./state/:\n\n# Save current session\nbash ./scripts/save_state.sh \"$SESSION_ID\" \"$PROJECT_PATH\"\n\n# Load state (sets environment variables)\nsource ./scripts/load_state.sh\necho $SESSION_ID\necho $PROJECT_PATH\n\n# Save project-specific state\nbash ./scripts/save_project.sh \"project-name\"\n\n# Load project-specific state\nbash ./scripts/load_project.sh \"project-name\"\n\n# List all saved projects\nls -1 ./state/*.json | grep -v current.json | xargs -n1 basename .json\n\nFile Operations\n\nGet session changes:\n\nbash ./scripts/get_diff.sh\n\n\nGet file content:\n\ncurl -s \"$BASE_URL/file/content?directory=$PROJECT_PATH&path=src/App.tsx\" \\\n  jq -r '.content'\n\n\nList directory:\n\ncurl -s \"$BASE_URL/file?directory=$PROJECT_PATH&path=src\" \\\n  jq -r '.[] | \"\\(.type): \\(.path)\"'\n\nError Handling\n\nAll scripts return proper exit codes:\n\n0 = Success\n1 = Error\n\nCheck script status:\n\nif bash ./scripts/send_message.sh \"prompt\"; then\n  echo \"Success\"\nelse\n  echo \"Failed - check server or authentication\"\nfi\n\nAuthentication\n\nThis skill assumes the OpenCode server is running in a trusted local environment and does not use password authentication by default.\n\nQuick Reference\nTask\tCommand\nUpdate providers\tbash ./scripts/update_providers.sh\nCreate session\tbash ./scripts/create_session.sh \"$PATH\" \"Title\"\nSend message\tbash ./scripts/send_message.sh \"prompt\"\nWith provider\tbash ./scripts/send_message.sh \"prompt\" \"provider\" \"model\"\nMonitor progress\tbash ./scripts/monitor_session.sh\nCheck status\tbash ./scripts/check_status.sh\nGet changes\tbash ./scripts/get_diff.sh\nSave state\tbash ./scripts/save_state.sh \"$SID\" \"$PATH\"\nLoad state\tsource ./scripts/load_state.sh\nSave project\tbash ./scripts/save_project.sh \"name\"\nLoad project\tbash ./scripts/load_project.sh \"name\"\nSelect provider\tbash ./scripts/select_provider.sh \"name\" \"model\"\nImportant Notes\nAlways run from skill directory: Scripts use relative paths\nUpdate providers at workflow start: Ensures cache is fresh\nCreate projects in PROJECTS_BASE_DIR: Configured in config.json\nEach session belongs to one project directory: Don't mix\nLoad state before curl commands: Ensures variables are set\nScripts handle authentication: No need to add headers manually\nTroubleshooting\n\n\"No active session\":\n\n# Load or create session first\nbash ./scripts/create_session.sh \"$PROJECT_PATH\" \"Title\"\n\n\n\"Provider not found\":\n\n# Update providers cache\nbash ./scripts/update_providers.sh\n\n# Check available providers\njq -r '.providers[] | .id' ./providers.json\n\n\n\"HTML response instead of JSON\":\n\nMissing directory parameter\nCheck: Are you using full PROJECT_PATH?\nAdvanced Usage\n\nFor complex workflows, state management, or advanced patterns, see:\n\nReference/STATE_MANAGEMENT.md - Advanced state handling\nReference/PROVIDERS_REFERENCE.md - Provider selection details\nReference/EVENTS_GUIDE.md - Event monitoring patterns\nReference/COMPLETE_EXAMPLES.md - Full workflow examples\nReference/API_QUICK_REFERENCE.md - Raw API endpoints\nDirectory Structure\nopencode-api-control/\n├── SKILL.md                    # This file\n├── config.json                 # Configuration\n├── providers.json              # Connected providers cache\n├── scripts/                    # Helper scripts\n│   ├── update_providers.sh\n│   ├── create_session.sh\n│   ├── send_message.sh\n│   ├── monitor_session.sh\n│   ├── check_status.sh\n│   ├── get_diff.sh\n│   ├── save_state.sh\n│   ├── load_state.sh\n│   ├── save_project.sh\n│   ├── load_project.sh\n│   └── select_provider.sh\n├── state/                      # Session state\n│   ├── current.json\n│   └── project-name.json\n└── Reference/                       # Reference docs\n    ├── STATE_MANAGEMENT.md\n    ├── PROVIDERS_REFERENCE.md\n    ├── EVENTS_GUIDE.md\n    ├── COMPLETE_EXAMPLES.md\n    └── API_QUICK_REFERENCE.md\n\n\nAuthor: Malek RSH | Repository: OpenCode-CLI-Controller"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/malek262/opencode-api-control-skill",
    "publisherUrl": "https://clawhub.ai/malek262/opencode-api-control-skill",
    "owner": "malek262",
    "version": "1.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/opencode-api-control-skill",
    "downloadUrl": "https://openagent3.xyz/downloads/opencode-api-control-skill",
    "agentUrl": "https://openagent3.xyz/skills/opencode-api-control-skill/agent",
    "manifestUrl": "https://openagent3.xyz/skills/opencode-api-control-skill/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/opencode-api-control-skill/agent.md"
  }
}