Skill: manuelkiessling/ask-a-human (version 1.0.1)

--- name: ask-a-human description: Request judgment from random humans when uncertain about subjective decisions. Crowdsourced opinions on tone, style, ethics, and reality checks. CRITICAL - Responses take minutes to hours (or may never arrive). metadata: openclaw: emoji: "🙋" requires: env: ["ASK_A_HUMAN_AGENT_ID"] primaryEnv: ASK_A_HUMAN_AGENT_ID homepage: "https://app.ask-a-human.com" --- # Ask-a-Human: Crowdsourced Judgment for AI Agents This skill connects you to a **global pool of random humans** who answer questions from AI agents. Use it when you need diverse perspectives on subjective decisions. ## CRITICAL: This is Asynchronous **Submitting a question does NOT give you an answer.** It starts a process: - Answers take **minutes to hours** to arrive - Answers **might never arrive** at all - You must poll for responses or check back later - You MUST have a fallback strategy **Do NOT use this if you need an immediate answer.** Use your own judgment or ask the owner directly instead. ## When to Use Request judgment from random humans when: - You're uncertain about **subjective decisions** (tone, wording, style) - You need a **reality check** on your assumptions - The decision involves **ethics or appropriateness** - You want **diverse perspectives**, not just one person's opinion - **AND you can wait or proceed with a fallback** ## What This Is (and Isn't) **This IS:** - A global pool of random strangers who opted in to help AI agents - Crowdsourced judgment from diverse perspectives - Useful for subjective decisions where there's no "correct" answer **This is NOT:** - A way to contact a specific person - A way to ask the owner/operator - A real-time service (responses are async) - Guaranteed to respond (humans may not answer) The strangers answering have **no context beyond what you provide in the question**. Write self-contained questions. ## API Reference Use the `exec` tool to make API calls. The base URL is `https://api.ask-a-human.com`. ### Submit a Question ```bash curl -X POST https://api.ask-a-human.com/agent/questions \ -H "Content-Type: application/json" \ -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID" \ -d '{ "prompt": "Your question with full context", "type": "multiple_choice", "options": ["Option A", "Option B", "Option C"], "min_responses": 5, "timeout_seconds": 3600 }' ``` **Parameters:** - `prompt` (required): The question to ask. Include all necessary context. - `type`: Either `"text"` (open-ended) or `"multiple_choice"` (predefined options) - `options`: Array of choices for multiple_choice questions (2-10 items) - `audience`: Target audience tags: `["technical", "product", "ethics", "creative", "general"]` - `min_responses`: Minimum responses needed (default: 5) - `timeout_seconds`: How long to wait (default: 3600 = 1 hour) **Response:** ```json { "question_id": "q_abc123def456", "status": "OPEN", "expires_at": "2026-02-02T15:30:00Z" } ``` **IMPORTANT: Store the `question_id` in your memory. You need it to check responses.** ### Check Responses ```bash curl https://api.ask-a-human.com/agent/questions/q_abc123def456 \ -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID" ``` **Response:** ```json { "question_id": "q_abc123def456", "status": "PARTIAL", "prompt": "Your original question", "type": "multiple_choice", "options": ["Option A", "Option B", "Option C"], "current_responses": 3, "required_responses": 5, "responses": [ {"selected_option": 0, "confidence": 4}, {"selected_option": 1, "confidence": 5}, {"selected_option": 0, "confidence": 3} ], "summary": { "Option A": 2, "Option B": 1 } } ``` **Status values:** - `OPEN`: Waiting for responses, none received yet - `PARTIAL`: Some responses received, still collecting - `CLOSED`: All requested responses received - `EXPIRED`: Timeout reached ## Async Handling Patterns This is the most important section. Choose the right pattern for your situation. ### Pattern 1: Fire and Forget **Best for:** Low-stakes decisions where getting it slightly wrong isn't catastrophic. ``` 1. Encounter a subjective decision 2. Submit question to ask-a-human, get question_id 3. Store in memory: "Asked about email tone, question_id=q_abc123" 4. Proceed immediately with your best guess 5. During next heartbeat or idle moment, check if answers arrived 6. If answers contradict your guess, note this for future similar decisions ``` **Example internal reasoning:** ``` I need to decide the tone for this error message. I'll ask the humans but proceed with "apologetic" as my best guess. I'm storing question_id=q_abc123 to check later. [Later, during heartbeat] Let me check q_abc123... The humans said "direct, not apologetic" (4 out of 5). I'll remember this preference for future error messages. ``` ### Pattern 2: Blocking Wait with Timeout **Best for:** Important decisions where you can afford to pause for a few minutes. ``` 1. Submit question 2. Tell the user: "I've asked some humans for their opinion. I'll wait up to 5 minutes." 3. Poll every 30-60 seconds (use exponential backoff: 30s, 45s, 67s, 100s...) 4. If answers arrive, proceed with crowd consensus 5. If timeout, proceed with fallback (own judgment) ``` **Polling schedule (exponential backoff):** - Poll 1: Wait 30 seconds - Poll 2: Wait 45 seconds - Poll 3: Wait 67 seconds - Poll 4: Wait 100 seconds - Poll 5: Wait 150 seconds (cap at ~2.5 minutes between polls) **Example:** ``` I'm uncertain about the headline for this blog post. Let me ask the humans. [Submit question, get q_xyz789] I've submitted this to a pool of random humans for their opinion. I'll check back in about 30 seconds. [30 seconds later, check responses] Status: OPEN, 0 responses yet. Checking again in 45 seconds. [45 seconds later] Status: PARTIAL, 2 responses. "Headline B" leading. Checking again in 67 seconds. [67 seconds later] Status: PARTIAL, 4 responses. "Headline B" has 3 votes, "Headline A" has 1. This is enough consensus. I'll proceed with Headline B. ``` ### Pattern 3: Deferred Decision **Best for:** Non-blocking but important decisions where there's other work to do. ``` 1. Submit question 2. Mark the task as "pending human input" in your memory 3. Continue with completely unrelated work 4. When answers arrive (detected via periodic check), revisit the original task 5. If answers never arrive, have a "stale questions" cleanup routine ``` **Example:** ``` Task: Write three blog posts. For Post 1, I need to decide the angle. Submitting to humans (q_post1_angle). For now, I'll start on Post 2 which has a clear direction. [Work on Post 2...] Let me check my pending questions... q_post1_angle now has 5 responses! The humans prefer "practical tutorial" over "thought leadership" (4-1). Now I can complete Post 1 with that direction. ``` ## Handling Edge Cases ### When No Responses Arrive After a reasonable timeout (5-10 minutes for interactive, longer for background): 1. **Proceed with your best judgment** - You're capable of making good decisions 2. **Log that human input wasn't available** - Note this in your reasoning 3. **Consider the stakes** - For high-stakes decisions, maybe ask the owner directly 4. **Don't retry immediately** - The pool may be empty; retrying won't help **Example reasoning:** ``` I waited 5 minutes for human input on the email tone, but received no responses. The human pool may be empty right now. I'll proceed with my best judgment ("professional but warm") and note that this decision wasn't crowd-validated. ``` ### When Answers Arrive Too Late If you already made the decision: 1. **If reversible:** Consider revising based on human input 2. **If not reversible:** Store the feedback for future similar decisions 3. **Log the discrepancy:** "Humans would have said X, I chose Y" **Example:** ``` [Checking old question q_email_tone] The humans responded (3 hours later): they preferred "casual" over "formal". I already sent the email with "formal" tone. I'll remember this preference for future emails to similar recipients. ``` ### Handling Partial Responses When you have some but not all requested responses: - **3+ responses with clear consensus (>66%):** Usually safe to proceed - **2 responses agreeing:** Decent signal, but lower confidence - **Mixed responses with no majority:** The decision may be genuinely subjective; use your judgment ## Writing Good Questions **DO:** - Include all necessary context in the question itself - Use multiple choice when possible (faster responses, clearer data) - Be specific about what you're deciding **DON'T:** - Assume responders know your project/context - Ask compound questions (split into multiple) - Use jargon without explanation **Good example:** ``` We're writing an error message for a payment failure in an e-commerce checkout. The user's credit card was declined. Should the message: A) Apologize and suggest trying another card B) Simply state the card was declined and ask to retry C) Blame the card issuer and suggest contacting their bank ``` **Bad example:** ``` Should we apologize? ``` ## Environment Setup This skill requires the `ASK_A_HUMAN_AGENT_ID` environment variable. Get your agent ID by signing up at https://app.ask-a-human.com. ## Rate Limits - Maximum 60 questions per hour per agent - Use exponential backoff when polling - Don't spam questions for the same decision ## Quick Reference | Action | Command | |--------|---------| | Submit question | `POST /agent/questions` with prompt, type, options | | Check responses | `GET /agent/questions/{question_id}` | | Required header | `X-Agent-ID: $ASK_A_HUMAN_AGENT_ID` | | Status | Meaning | |--------|---------| | OPEN | Waiting, no responses yet | | PARTIAL | Some responses, still collecting | | CLOSED | All responses received | | EXPIRED | Timeout, question closed |

path: README.md
content: # Ask-a-Human Skill for OpenClaw

Connect your OpenClaw agent to a global pool of random humans for crowdsourced judgment on subjective decisions.

## What is This?

Ask-a-Human gives your agent access to **random strangers** who have opted in to answer questions from AI agents. When your agent is uncertain about:

- Subjective decisions (tone, style, wording)
- Ethics or appropriateness
- Reality checks on assumptions
- A/B choices that need human intuition

...it can submit a question and get responses from multiple humans who have no context beyond what the agent provides.

**Important:** This is NOT for asking a specific person or the owner. It's crowdsourced judgment from diverse, anonymous perspectives.

## Installation

### Option 1: Install from ClawHub (Recommended)

```bash
clawdhub install ask-a-human
```

### Option 2: Manual Installation

1. Create the skill directory:
   ```bash
   mkdir -p ~/.openclaw/skills/ask-a-human
   ```

2. Copy the `SKILL.md` file to the directory:
   ```bash
   cp SKILL.md ~/.openclaw/skills/ask-a-human/
   ```

3. Restart OpenClaw or run:
   ```bash
   openclaw skills list
   ```

## Setup

### 1. Get Your Agent ID

1. Go to [https://app.ask-a-human.com](https://app.ask-a-human.com)
2. Sign up or log in
3. Navigate to Settings > Agent Configuration
4. Create a new agent and copy the Agent ID

### 2. Set the Environment Variable

Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):

```bash
export ASK_A_HUMAN_AGENT_ID="your-agent-id-here"
```

Or add to your OpenClaw configuration (`~/.openclaw/openclaw.json`):

```json
{
  "skills": {
    "entries": {
      "ask-a-human": {
        "enabled": true,
        "env": {
          "ASK_A_HUMAN_AGENT_ID": "your-agent-id-here"
        }
      }
    }
  }
}
```

### 3. Verify Installation

Restart OpenClaw and check that the skill is loaded:

```bash
openclaw skills list
```

You should see `ask-a-human` in the list with a green checkmark.

## Quick Test

Ask OpenClaw something subjective:

```
I'm writing an apology email for missing a meeting. Should I:
A) Be very apologetic and offer multiple reschedule options
B) Keep it brief and professional with one reschedule option
C) Explain the reason for missing before apologizing

Can you ask some humans what they think?
```

OpenClaw will:
1. Submit the question to the human pool
2. Either wait for responses or proceed with its best guess (depending on context)
3. Report back with the crowd's verdict

## Understanding the Async Nature

**This is the most important thing to understand:**

Submitting a question does NOT return an answer immediately. Responses take:
- Minutes at best
- Hours typically  
- Forever (never) in some cases

Your agent must:
1. Store the `question_id` in memory
2. Continue with other work or wait with a timeout
3. Poll for responses periodically
4. Have a fallback plan if no responses arrive

See the [SKILL.md](SKILL.md) for detailed async handling patterns.

## Troubleshooting

### Skill not loading

1. Check that `ASK_A_HUMAN_AGENT_ID` is set:
   ```bash
   echo $ASK_A_HUMAN_AGENT_ID
   ```

2. Verify the skill file exists:
   ```bash
   ls ~/.openclaw/skills/ask-a-human/SKILL.md
   ```

3. Check OpenClaw logs for errors:
   ```bash
   openclaw logs --skill ask-a-human
   ```

### No responses received

- The human pool may be empty at certain times
- Try increasing `timeout_seconds`
- Ensure your question is clear and self-contained
- Check that your agent ID is valid at [https://app.ask-a-human.com](https://app.ask-a-human.com)

### Rate limit errors

- Maximum 60 questions per hour per agent
- Use exponential backoff when polling
- Don't submit duplicate questions

## API Reference

The skill uses the Ask-a-Human API at `https://api.ask-a-human.com`:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/questions` | POST | Submit a new question |
| `/api/questions/{id}` | GET | Check status and responses |

All requests require the `X-Agent-ID` header.

## Examples

See [examples/usage.md](examples/usage.md) for detailed workflow examples.

## Links

- [Ask-a-Human Web App](https://app.ask-a-human.com)
- [API Documentation](https://api.ask-a-human.com/docs)
- [OpenClaw Documentation](https://docs.clawd.bot)
- [ClawHub Registry](https://clawhub.io)

## License

MIT


path: examples/usage.md
content: # Ask-a-Human Usage Examples for OpenClaw

These examples show real-world workflows demonstrating how OpenClaw agents can use the ask-a-human skill for various subjective decisions.

## Example 1: Email Tone Decision (Fire and Forget Pattern)

**Scenario:** The agent is helping draft an email to a client about a project delay.

### Conversation

**User:** Help me write an email to our client explaining that the project will be delayed by 2 weeks.

**Agent (internal reasoning):**
```
This requires a tone decision. I could be very apologetic, matter-of-fact, or 
somewhere in between. Let me ask the humans while I draft options.
```

**Agent (action):**
```bash
curl -X POST https://api.ask-a-human.com/api/questions \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID" \
  -d '{
    "prompt": "We need to email a client about a 2-week project delay. What tone should the email take?\n\nContext: B2B software project, good relationship with client, delay is due to unexpected technical complexity.",
    "type": "multiple_choice",
    "options": [
      "Very apologetic - emphasize how sorry we are",
      "Professional and matter-of-fact - state the facts, offer solution",
      "Proactive - frame as an opportunity for additional features",
      "Transparent - detailed explanation of what caused the delay"
    ],
    "min_responses": 5,
    "timeout_seconds": 600
  }'
```

**API Response:**
```json
{
  "question_id": "q_delay_email_001",
  "status": "OPEN"
}
```

**Agent (stores in memory):** `Pending question q_delay_email_001 about delay email tone`

**Agent (to user):**
```
I've asked some humans for their opinion on the best tone. While waiting,
I'll draft the email using a professional, matter-of-fact approach (my best guess).

---

Subject: Project Timeline Update - [Project Name]

Dear [Client],

I wanted to update you on our timeline for [Project Name]. Due to unexpected 
technical complexity in [specific area], we need an additional two weeks to 
deliver the quality you expect.

New delivery date: [Date]

We've identified the issues and have a clear path forward. I'd be happy to 
discuss the details on a call if you'd like.

Best regards,
[Name]

---

I can adjust the tone once the human responses come in, or you can proceed 
with this version.
```

**[2 minutes later, agent checks during heartbeat]**

**Agent (internal):**
```bash
curl https://api.ask-a-human.com/api/questions/q_delay_email_001 \
  -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID"
```

**API Response:**
```json
{
  "question_id": "q_delay_email_001",
  "status": "PARTIAL",
  "current_responses": 4,
  "summary": {
    "Professional and matter-of-fact - state the facts, offer solution": 3,
    "Transparent - detailed explanation of what caused the delay": 1
  }
}
```

**Agent (to user):**
```
Update: 4 humans have responded to my tone question. 3 out of 4 recommend
the professional, matter-of-fact approach - which matches what I drafted.
The consensus validates this direction. Ready to send?
```

---

## Example 2: Content Headline Choice (Blocking Wait Pattern)

**Scenario:** The agent is helping write a blog post and needs to choose a headline.

### Conversation

**User:** I've written this blog post about remote work productivity. Can you help me pick the best headline?

**Agent:**
```
I have a few headline options. Let me ask some humans which one resonates best.
This is an important decision, so I'll wait a few minutes for responses.
```

**Agent (action):**
```bash
curl -X POST https://api.ask-a-human.com/api/questions \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID" \
  -d '{
    "prompt": "Which headline would make you most likely to click and read a blog post about remote work productivity tips?\n\nTarget audience: Software developers working remotely",
    "type": "multiple_choice",
    "options": [
      "10 Proven Ways to Stay Productive While Working from Home",
      "Why Your Home Office Setup Is Killing Your Productivity",
      "The Remote Developer'\''s Guide to Deep Work",
      "I Doubled My Output Working from Home. Here'\''s How."
    ],
    "audience": ["creative", "product"],
    "min_responses": 5,
    "timeout_seconds": 300
  }'
```

**Agent (to user):**
```
I've submitted four headline options to a pool of random humans. I'll check 
back every 30 seconds or so. This usually takes 2-5 minutes.

Waiting for responses... (0/5 received)
```

**[30 seconds later]**

**Agent (checks):**
```
Still waiting... (1/5 received)
```

**[45 seconds later]**

**Agent (checks):**
```
Making progress... (3/5 received)
```

**[67 seconds later]**

**Agent (checks):**
```json
{
  "status": "CLOSED",
  "current_responses": 5,
  "summary": {
    "Why Your Home Office Setup Is Killing Your Productivity": 3,
    "I Doubled My Output Working from Home. Here's How.": 2
  }
}
```

**Agent (to user):**
```
The humans have spoken! 5 responses received.

Results:
- "Why Your Home Office Setup Is Killing Your Productivity" - 3 votes (60%)
- "I Doubled My Output Working from Home. Here's How." - 2 votes (40%)

The winner is the provocative "killing your productivity" angle. This makes 
sense - it creates curiosity and a bit of urgency. Want me to use this headline?
```

---

## Example 3: Code Review Sensitivity Check (Deferred Pattern)

**Scenario:** The agent is reviewing code and found something that might be a sensitive issue to raise.

### Conversation

**User:** Review the code changes in this PR for our authentication system.

**Agent (internal reasoning):**
```
I found a potential security issue, but I'm not sure how to phrase feedback 
without sounding alarmist or condescending. I'll ask humans while I continue 
reviewing the rest of the PR.
```

**Agent (action):**
```bash
curl -X POST https://api.ask-a-human.com/api/questions \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: $ASK_A_HUMAN_AGENT_ID" \
  -d '{
    "prompt": "I'\''m reviewing code and found a junior developer stored passwords with MD5 hashing instead of bcrypt. How should I phrase feedback that'\''s helpful but not condescending?\n\nContext: This is a code review comment that will be public to the team.",
    "type": "text",
    "audience": ["technical", "product"],
    "min_responses": 3,
    "timeout_seconds": 1800
  }'
```

**Agent (stores in memory):** 
```
Pending: q_code_review_tone - How to phrase password hashing feedback
Continue with: Rest of PR review
```

**Agent (to user):**
```
I'm reviewing the PR and making notes. I've found a few things to discuss.

In the meantime, I've asked some humans for advice on phrasing feedback for 
a sensitive issue I found. I'll incorporate their suggestions into my final 
review comments.

Continuing with the review...
```

**[Agent continues reviewing other parts of the code]**

**Agent:**
```
Here's what I've found so far:

1. ✅ Input validation looks good
2. ✅ SQL injection prevention is solid
3. ⚠️ Rate limiting could be improved (line 45)
4. 🔴 Password hashing concern (waiting for human input on phrasing)
5. ✅ Session management is correct
```

**[5 minutes later, agent checks pending questions]**

**API Response:**
```json
{
  "question_id": "q_code_review_tone",
  "status": "CLOSED",
  "responses": [
    {
      "answer": "Frame it as a learning opportunity: 'I noticed MD5 here - have you considered bcrypt? It's the current standard because [reason]. Happy to pair on this if helpful!'"
    },
    {
      "answer": "Lead with the why: 'MD5 has known vulnerabilities for password storage. Let's upgrade to bcrypt - I can point you to some good resources.'"
    },
    {
      "answer": "Be direct but kind: 'This needs to use bcrypt instead of MD5 for security. Not a big change - want me to suggest the specific code?'"
    }
  ]
}
```

**Agent (to user):**
```
Great news - I got feedback on how to phrase the password hashing comment. 
Here's my complete review:

## Code Review: Authentication PR

### Must Fix
**Password Hashing (auth/users.py:78)**
I noticed MD5 is used for password hashing here. MD5 has known vulnerabilities 
for password storage - let's upgrade to bcrypt which is the current standard. 
Not a big change! Happy to suggest the specific code if helpful.

### Should Fix
**Rate Limiting (auth/login.py:45)**
Consider adding rate limiting to prevent brute force attempts...

[rest of review]
```

---

## Example 4: Handling No Responses (Timeout Fallback)

**Scenario:** The agent asks a question but no humans respond.

### Conversation

**User:** What color scheme should I use for my new SaaS dashboard?

**Agent:**
```
That's a subjective design decision. Let me ask some humans for their opinion
while I analyze your existing brand colors.

Submitted question to human pool. Waiting up to 5 minutes...
```

**[5 minutes pass with polling every 30-60 seconds]**

**API Response (final check):**
```json
{
  "question_id": "q_color_scheme",
  "status": "OPEN",
  "current_responses": 0
}
```

**Agent (to user):**
```
I waited 5 minutes but didn't receive any human responses. The pool might 
be quiet right now.

I'll proceed with my own analysis instead:

Based on your existing brand colors (#2563EB blue, #F8FAFC off-white), 
I'd recommend:

1. **Primary:** Keep your brand blue for CTAs and key actions
2. **Background:** Light gray (#F1F5F9) for main areas
3. **Accent:** A complementary orange (#EA580C) for alerts/notifications
4. **Text:** Dark gray (#1E293B) for readability

This follows your brand while maintaining dashboard usability conventions.
Would you like me to generate a complete color palette spec?
```

---

## Example 5: Handling Late Responses

**Scenario:** Humans respond after the agent already made a decision.

### Agent (internal, during heartbeat)

```
Checking stale questions from earlier sessions...

q_api_naming from 3 hours ago now has responses:
- Original question: "Should this API endpoint be named /users/deactivate 
  or /users/archive?"
- I chose: /users/deactivate
- Human consensus: 4 out of 5 said /users/archive

The decision was already made and deployed. Storing this feedback for future 
reference: "Humans prefer 'archive' over 'deactivate' for soft-delete operations."
```

**Agent (might mention to user in appropriate context):**
```
By the way, I got late feedback on that API naming question from earlier.
The humans preferred "archive" over "deactivate" (4-1). The endpoint is already
deployed, but I'll keep this in mind for future naming decisions.
```

---

## Pattern Summary

| Pattern | Use When | Example |
|---------|----------|---------|
| **Fire and Forget** | Low-stakes, can proceed with best guess | Email tone, minor wording choices |
| **Blocking Wait** | Important decision, can pause 2-5 minutes | Headlines, user-facing copy |
| **Deferred** | Important but non-blocking, other work to do | Code review tone, design decisions |

## Tips for Writing Good Questions

1. **Include context** - Responders don't know your project
2. **Be specific** - "Which headline?" not "What do you think?"
3. **Use multiple choice** - Faster responses, clearer data
4. **Set appropriate audiences** - `technical` for code, `creative` for content
5. **Provide options** - Give 3-5 choices, not open-ended when possible


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)