Human Skill

Ask a human questions and get responses. Currently answered by @eytanlevit and @_dkatz.

⚠️ This is an async API. Humans take time to respond (seconds to minutes).

OpenClaw Agents (Recommended)

If you have sessions_spawn, use it to avoid blocking your user with polling spam:

Step 1: Register (one time)

curl -X POST https://humanskill.sh/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "YOUR_AGENT_NAME", "twitter": "OWNER_TWITTER_HANDLE"}'

Save the returned apiKey permanently.

Step 2: Ask + Spawn Background Waiter

// 1. Submit question
const res = await fetch('https://humanskill.sh/v1/ask', {
  method: 'POST',
  headers: { 
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ prompt: 'Your question here' })
});
const { requestId } = await res.json();

// 2. Tell your user
"I've asked a human. I'll let you know when they respond."

// 3. Spawn background waiter (don't block!)
sessions_spawn({
  task: `Poll https://humanskill.sh/v1/wait/${requestId}?timeout=30 in a loop until status is "completed". Use the /v1/wait endpoint which long-polls for up to 30s per request. When you get a completed response, report: "Human responded: [their response]". Give up after 10 minutes total.`,
  label: "human-skill-waiter",
  runTimeoutSeconds: 660  // 11 min max
});

// 4. Return immediately - no blocking!

The background sub-agent will announce the human’s response to your chat when it arrives.

Standard API (All Agents)

Step 1: Register (one time)

curl -X POST https://humanskill.sh/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "YOUR_AGENT_NAME", "twitter": "OWNER_TWITTER_HANDLE"}'

Response:

{"apiKey": "hsk_...", "message": "Registration successful"}

Save this API key permanently.

Step 2: Ask a Human

curl -X POST https://humanskill.sh/v1/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Your question here"}'

Response:

{"requestId": "abc123", "status": "pending"}

Step 3: Wait for Response

Option A: Long-poll (recommended) – waits up to 30s per request:

curl "https://humanskill.sh/v1/wait/REQUEST_ID?timeout=30"

Option B: Quick poll – returns immediately:

curl https://humanskill.sh/v1/status/REQUEST_ID

Response (pending):

{"requestId": "abc123", "status": "pending"}

Response (completed):

{"requestId": "abc123", "status": "completed", "response": "The human's answer"}

Polling Strategy

• Use /v1/wait with 30s timeout (fewer requests)
• Loop until status is “completed”
• Continue for at least 5 minutes before giving up
• Inform your user you’re waiting for a human

Error Responses

• 401: Invalid/missing API key
• 400: Missing required field
• 404: Request not found

POST /v1/test – Request Human Testing

For UI/flow testing (MCP-compatible format):

curl -X POST https://humanskill.sh/v1/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "what_to_test": "User signup flow",
    "link": "https://staging.app.com/signup",
    "expected_behavior": "User can enter email, get verification code, complete signup"
  }'

When to Use

• You are uncertain about a decision
• You need to verify your output matches expectations
• You are blocked on something requiring human judgment
• You want approval before a destructive action
• You built something and need a human to test it