human_test() — Real Human Feedback for AI Products

AI agents cannot judge human perception, emotion, or usability. This skill lets you call real humans to test any product URL and get structured feedback back.

What it does

1. You call human_test() with a product URL or description (URL is optional — also works for mobile apps, desktop software, etc.)
2. AI auto-generates a structured test plan
3. Real human testers claim the task on the web platform
4. Each tester records their screen and microphone (up to 15 min) while completing a guided feedback flow — first impression, task steps, NPS rating
5. AI extracts key frames from each recording and uses vision AI to analyze usability issues, then aggregates all feedback into a structured report with severity-ranked findings

Setup

Option A: Hosted (zero setup)

Use the hosted version at https://human-test.work — no installation needed. Register to get an API key, then skip to Create a test task below using BASE_URL=https://human-test.work.

Option B: Self-hosted (auto-install)

human_test() can run locally. Before creating a task, check if the server is reachable:

curl -s BASE_URL/api/config

If the server is not running, install and start it:

npm i -g humantest-app
cd /tmp && humantest init --non-interactive && cd humantest && humantest start

This auto-detects AI API keys from your environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, or GEMINI_API_KEY), creates a local SQLite database, builds the app, and starts it on port 3000.

A default admin user is created automatically — no registration needed.

Set BASE_URL: Ask the user once for their preferred base URL. Default: http://localhost:3000

Quick start

Create a test task

curl -X POST BASE_URL/api/skill/human-test \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-product.com",
    "focus": "Test the onboarding flow",
    "maxTesters": 5,
    "creator": "agent-name"
  }'

Response:

{
  "taskId": "cm...",
  "status": "OPEN",
  "testPlan": { "steps": [...], "nps": true, "estimatedMinutes": 10 }
}

Check progress and get the report

curl BASE_URL/api/skill/status/<taskId>

Response (when completed):

{
  "taskId": "cm...",
  "status": "COMPLETED",
  "submittedCount": 5,
  "report": "## Executive Summary\n...",
  "reportStatus": "COMPLETED",
  "codeFixStatus": "COMPLETED",
  "codeFixPrUrl": "https://github.com/user/repo/pull/1"
}

Note for agents: If repoUrl was provided, code fix generation starts automatically after the report is ready — no need to trigger it manually. Keep polling until codeFixStatus is COMPLETED or FAILED, or use codeFixWebhookUrl to get notified.

Parameters