Add unified captcha third-party services skill with official API workflow

captcha-third-party-services/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: captcha-third-party-services
+description: Unified captcha workflow for 2Captcha, YesCaptcha, and Anti-Captcha. Use when users need official API-based task submission (`createTask`), polling (`getTaskResult`), balance checks (`getBalance`), provider fallback, or debugging captcha token pipelines for reCAPTCHA/hCaptcha/Turnstile/FunCaptcha and similar challenge types.
+---
+
+# Captcha Third Party Services
+
+## Overview
+
+Use official APIs to create captcha tasks, poll completion, and return solve tokens with consistent behavior across providers.
+
+Read `references/official-docs-and-analysis.md` when you need provider-specific details, method URLs, and compatibility notes.
+
+## Inputs To Collect
+
+- Provider: `2captcha`, `yescaptcha`, or `anti-captcha`
+- Captcha task type (for example `RecaptchaV2TaskProxyless`, `TurnstileTaskProxyless`, `HCaptchaTaskProxyless`)
+- Target metadata: `websiteURL`, `websiteKey` and task-specific fields
+- API key (runtime secret, not hardcoded into committed files)
+
+## API Key Handling
+
+Prefer environment variables:
+
+- `CAPTCHA_2CAPTCHA_KEY`
+- `CAPTCHA_YESCAPTCHA_KEY`
+- `CAPTCHA_ANTI_CAPTCHA_KEY`
+
+Only use direct `--api-key` arguments for one-off tests.
+
+## Unified Workflow
+
+1. Check balance before creating tasks.
+2. Build a `task` payload that matches provider-supported task schema.
+3. Submit `createTask`.
+4. Poll `getTaskResult` every 3-5 seconds until `status=ready` or timeout.
+5. Return `solution` token and timing/cost metadata.
+
+## Provider Selection Strategy
+
+- Start with preferred provider from user.
+- If provider returns permanent task validation errors, fix payload first.
+- If provider returns transient capacity/timeouts, fail over to next provider.
+- Keep task type and site parameters identical during failover to isolate provider variance.
+
+Recommended fallback order:
+
+1. `yescaptcha`
+2. `2captcha`
+3. `anti-captcha`
+
+Adjust order using account balance, measured solve latency, and recent success rate.
+
+## Use The Bundled CLI
+
+Use `scripts/captcha_api_cli.py` for deterministic API calls.
+
+### Balance
+
+```bash
+python3 scripts/captcha_api_cli.py balance --provider 2captcha
+python3 scripts/captcha_api_cli.py balance --provider yescaptcha
+python3 scripts/captcha_api_cli.py balance --provider anti-captcha
+```
+
+### Create Task
+
+```bash
+python3 scripts/captcha_api_cli.py create-task \
+  --provider 2captcha \
+  --task-json '{"type":"RecaptchaV2TaskProxyless","websiteURL":"https://example.com","websiteKey":"SITE_KEY"}'
+```
+
+### Poll Task Result
+
+```bash
+python3 scripts/captcha_api_cli.py get-task-result \
+  --provider 2captcha \
+  --task-id 123456789
+```
+
+### End-To-End Solve (Create + Poll)
+
+```bash
+python3 scripts/captcha_api_cli.py solve \
+  --provider yescaptcha \
+  --task-json '{"type":"TurnstileTaskProxyless","websiteURL":"https://example.com","websiteKey":"SITE_KEY"}' \
+  --poll-interval 3 \
+  --timeout 180
+```
+
+## Raw Curl Patterns
+
+Use these when a user explicitly asks for direct HTTP examples.
+
+### createTask
+
+```bash
+curl -sS https://api.<provider-domain>/createTask \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "clientKey":"<API_KEY>",
+    "task":{
+      "type":"RecaptchaV2TaskProxyless",
+      "websiteURL":"https://example.com",
+      "websiteKey":"SITE_KEY"
+    }
+  }'
+```
+
+### getTaskResult
+
+```bash
+curl -sS https://api.<provider-domain>/getTaskResult \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "clientKey":"<API_KEY>",
+    "taskId":123456789
+  }'
+```
+
+### getBalance
+
+```bash
+curl -sS https://api.<provider-domain>/getBalance \
+  -H 'Content-Type: application/json' \
+  -d '{"clientKey":"<API_KEY>"}'
+```
+
+## Troubleshooting
+
+- `errorId != 0`: treat as API-level failure and inspect `errorCode`/`errorDescription`.
+- Stuck in `processing`: extend timeout or switch provider.
+- Invalid key/site params: validate task type and required fields from official docs.
+- Low balance: call `getBalance` and select another provider if needed.
+
+## Compliance
+
+- Use these services only for authorized security testing and legitimate automation.
+- Respect target website Terms of Service and applicable laws.