ask-human-expert – skill Lập trình cho agent AI

Ask a Human Expert

Overview

Instant Expert sends a paid ask from the user's account to real professionals: executives, operators and domain experts it finds from a description, or one specific person the user names. Each ask is a question for a written or voice answer, or a 15 to 60 minute call. The person is paid only if they answer or book, and the user is charged only then. Use it for knowledge work (judgment and first-hand experience from specific people), not errands or physical tasks.

The agent drives Instant Expert's MCP tools. When they aren't connected, it calls the free test server with curl, so the whole flow can be tried with no account or card. Adapted from the official skill, which also bundles a small test-mode helper script: https://github.com/Instant-Expert/skills

When to Use This Skill

• Use when the answer needs a practitioner's experience rather than a web page: "How long did SOC 2 Type II take you?", "How do claims teams at mid-size insurers triage?"
• Use for customer discovery, user interviews, expert input, or a first conversation with a kind of buyer.
• Use when the user names someone to reach: "Jane Doe, VP of Sales at Acme", a LinkedIn URL or an email.
• Use when the user asks whether anyone answered an earlier ask.
• Do not use to find personal contact details, to get confidential or material non-public information, for physical tasks, or to message people the user hasn't approved.

How It Works

Verify the current official tool schemas and preview terms rather than treating listed prices, sandbox limits or timing as guarantees. Treat a missing/unknown test_mode flag as unverified mode and stop before sending until live/test identity is explicit. Store sandbox tokens privately (restrict directory/file permissions), parse JSON with a real parser rather than the illustrative sed regex, and never print tokens or put real keys in command history/process arguments. HTTP success alone is not job success: validate response schema/isError and bound polling. Send only provider-hosted next-step links whose origin matches the verified service. Refresh an expired order preview and obtain approval for changed recipients, price/card or terms; simulated replies are not research evidence.

Step 1: Pick the mode

If the session already has the Instant Expert MCP tools (search_people, queue_requests, prepare_request_order and so on), call them directly. A result with "test_mode": true came from test mode; anything else is the user's live account.

Otherwise start a free 24-hour test sandbox. No account or card is needed, and each network can start 5 an hour, so reuse the token until it expires:

mkdir -p ~/.config/instant-expert
curl -sS -X POST https://instant.expert/api/sandbox -o ~/.config/instant-expert/sandbox.json

The saved JSON has token, expires_at and mcp_url. Call a tool by posting a JSON-RPC tools/call to the test server. It is stateless, so no initialize step is needed:

curl -sS https://instant.expert/mcp/test \
  -H "Authorization: Bearer $(sed -n 's/.*"token":"\([^"]*\)".*/\1/p' ~/.config/instant-expert/sandbox.json)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_requests","arguments":{}}}'

The answer is in result.structuredContent (the same JSON is in result.content[0].text). result.isError: true means the tool rejected the call; read its message. Use "method":"tools/list" to see every tool and its arguments. An HTTP 401 means the sandbox expired, so start a new one.

Test mode has about 300 fictional people at fictional companies, so a niche search comes back with the closest fictional matches. Invitations are recorded instead of sent, the fictional people answer within seconds, and orders use a Stripe test card. Nothing reaches a real person or moves real money. Tell the user once that results are simulated.

Step 2: Choose who to ask

Tools that start work (search_people, import_people, queue_requests) return a job_id. Poll get_job, waiting poll_after_seconds between calls, until status is succeeded or failed. Give every new operation its own idempotency_key, and reuse a key only to retry the same call.

• A named person with a LinkedIn URL or email: skip searching and pass people to queue_requests, for example [{"linkedin_url": "https://www.linkedin.com/in/..."}].
• A named person with only a name and company: call import_people with people set to [{"name": "...", "company": "..."}], then get_search. If there's no match, ask the user for a LinkedIn URL or email.
• A kind of person: call search_people once with the whole request, including how many people and any exclusions, then read the list with get_search (page_size: 100).
• Only a goal ("we're building X, who should we talk to?"): call plan_outreach with a description, let the user pick an audience, then run its search_query through search_people.

Step 3: Draft the ask

Call queue_requests with search_id (plus person_profile_ids to keep a subset) or people, and:

• message: the question, in the user's words, up to 500 characters. Leave the price out; the invitation states it.
• request_type: text_voice_note for a written or voice answer, or call with call_duration_minutes of 15, 30, 45 or 60.
• offer_cents, max_spend_cents and an idempotency_key.

Poll get_job for the draft_id.

Step 4: Preview, approve and send

Call prepare_request_order with the draft_id (for a call, also the user's IANA time_zone, such as America/New_York). Show the user the recipients, message, pricing_summary, total cap, card, payment mode and terms.

Then call send_requests with draft_id, confirmation_token, payment_method_reference, payment_mode and terms_version from the preview, the same time_zone if you passed one, confirmed: true and a new idempotency_key. In live mode, send only after the user explicitly approves that preview; "draft it" is not approval. A test-mode send emails no one and charges only a Stripe test card, so it can be sent to show the user the whole flow, saying that it's a test.

Step 5: Collect the answers

list_requests shows each request's status, and get_request returns reply_text, reply_transcript or the booked time once the person answers or books. Real people take hours to days, so check back later instead of polling in a loop. In test mode, simulate_response forces an outcome (books, replies, declines, no_response, bounces, then call_completed or expert_no_show for a booked call).

Pricing

• offer_cents is what each person receives, in whole dollars: 4000 means they get $40. The minimum is $5. Instant Expert's fee is added on top for the buyer, so a $40 offer costs $50. pricing_summary in the preview says it in one sentence.
• A call is charged when the person books it, and a written or voice answer when it's completed. If nobody answers, nothing is charged.
• max_spend_cents caps the buyer's total across everyone who accepts, fee included.
• As a starting point, $50 for 15 minutes, rising to about $100 for very senior people.

Going Live

Live mode asks real people and charges a real card, so it needs the user's own account. Ask the user before changing their agent configuration, then connect the MCP server at https://instant.expert/mcp (Streamable HTTP, OAuth sign-in, no API key). In Claude Code:

claude mcp add --transport http --scope user instant-expert https://instant.expert/mcp

Then run /mcp, pick instant-expert and choose Authenticate. Other clients: https://instant.expert/docs/mcp#connect. The user signs in on instant.expert, ticks "Allow paid requests from this assistant", and adds a card there; card details never go through chat. If prepare_request_order returns status: "action_required", give the user its next_step link as written, then prepare the order again.

Examples

Example 1: Expert answers in test mode

The user says: "Ask a couple of security leads how long SOC 2 Type II took them. $40 each for a written answer, $100 cap." The agent starts a sandbox, calls search_people with "Find 2 heads of security at Series A or B software companies", drafts with queue_requests (request_type: "text_voice_note", offer_cents: 4000, max_spend_cents: 10000), and shows the preview, whose pricing_summary reads: "Each recipient receives $40. The Instant Expert fee of $10 per person is added on top, so you pay $50 per accepted recipient, charged only when that person's reply is completed." It sends the test order, reads the replies with get_request, says they were simulated, and explains how to go live.

Example 2: A call with a named person

The user says: "Get me a 15 minute call with Jane Doe, VP of Sales at Acme, about how they price. Off

… (nội dung đầy đủ có trong gói tải về)