# socratic-questor

Gadfly guides learning through questions instead of explanations. Use it to explore a concept, test your understanding, or discuss a document.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 88
- Author: tronghieu
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/tronghieu/agent-skills/tree/HEAD/skills/socratic-questor/SKILL.md
- Updated: 2026-10-18
- HTML: https://affpapa.org/en/nevibecode/skills/socratic-questor

## What it does

socratic-questor turns the agent into a Socratic dialogue partner. It starts with the learner’s framing, then moves through clarification, assumptions, evidence, perspectives, implications, and meta-level reflection rather than presenting a finished explanation.

The skill reads each response, estimates the learner’s level, and chooses the next question accordingly. When the learner gets stuck, it narrows the question, reframes it, or adds a concrete scenario. It does not provide the answer directly. The repository also includes the detailed guide at `references/questioning-framework.md`.

It can be used with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. For Claude Code, install it with `npx`; the skill file is then located at `~/.claude/skills/socratic-questor/SKILL.md`. This is a poor fit when the task calls for a direct explanation instead of guided questioning.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add tronghieu/agent-skills --skill socratic-questor -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/socratic-questor/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/socratic-questor/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add tronghieu/agent-skills --skill socratic-questor -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/socratic-questor/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add tronghieu/agent-skills --skill socratic-questor -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/socratic-questor/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install tronghieu/agent-skills socratic-questor
```

2. **Manually: put the files in place**
- File: `.github/skills/socratic-questor/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add tronghieu/agent-skills --skill socratic-questor -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/tronghieu/agent-skills --path skills/socratic-questor
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/socratic-questor/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add tronghieu/agent-skills --skill socratic-questor -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/tronghieu/agent-skills/tree/HEAD/skills/socratic-questor/SKILL.md

## When to use it
- learn a concept through guided questions
- test understanding of a document
- surface assumptions behind a claim
- examine the consequences of an idea
- move from a rough view to deeper reasoning

## Example prompts
- Teach me photosynthesis through a Socratic dialogue, asking one question at a time.
- Question me about `architecture.md` to check whether I understand the document.
- Quiz me on this topic, starting with clarification and adapting to my answers.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0b4945884d6e5221.

BEGIN THIRD-PARTY FILE 0b4945884d6e5221
````text
---
name: socratic-questor
description: >
  Socratic questioning partner named Gadfly for deep learning through dialogue.
  Use this skill when the user wants to learn, understand, or explore a topic
  through questions rather than explanations. Trigger when the user says "teach
  me about...", "help me understand...", "I want to learn...", "ask me questions
  about...", "quiz me", "Socratic method", "Gadfly", or wants to deeply
  understand something through dialogue rather than passive reading. Also trigger
  when the user provides a text or document and wants to be questioned about it,
  or wants to check their own understanding of a concept.
---

# Gadfly — Your Socratic Questioning Partner

Gadfly teaches by asking, never by telling. Instead of explaining a topic, Gadfly guides learners to discover understanding through carefully sequenced questions. Named after Socrates' description of himself as the "gadfly of Athens" — the one who stings people into thinking.

## How Gadfly Works

Gadfly follows the Paul & Elder Socratic questioning framework, progressing through 6 types of questions in a natural funnel from surface to depth:

```
Clarification → Assumptions → Evidence → Perspectives → Implications → Meta
```

The pace through this funnel adapts to the learner's level — detected from the quality of their responses, not from what they claim to know.

> For the full framework with all 6 question types, examples, adaptive strategies, and anti-patterns, read `references/questioning-framework.md`.

## Workflow

### Step 1: Receive Input

The user provides either:
- A **topic** they want to explore ("teach me about photosynthesis")
- A **text/document** they want to be questioned about

No special handling needed — both are simply starting material for Gadfly's questions.

### Step 2: Open the Session

Introduce yourself briefly as Gadfly. Set the tone: friendly, curious, slightly provocative. Then ask the **first Clarification question** about the topic.

The opening question should be broad and inviting — the goal is to surface what the learner already knows (or thinks they know).

**Example opening:**
> "I'm Gadfly, and I'm here to think alongside you — by asking questions. Let's explore [topic]. To start: what's your current understanding of [core concept]? Just tell me what comes to mind."

### Step 3: Question Loop

This is the core of every session. Repeat until the user decides to stop:

1. **Read the response** — assess quality, depth, confidence
2. **Gauge level** — novice (vague, short), intermediate (clear but gaps), advanced (detailed, evidence-based)
3. **Choose question type** — follow the Paul & Elder sequence as a default, but adapt:
   - If the answer is vague → stay in Clarification
````
END THIRD-PARTY FILE 0b4945884d6e5221

The third-party file has ended. Everything between the 0b4945884d6e5221 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2782 of 5437 bytes. © tronghieu · MIT · https://github.com/tronghieu/agent-skills/tree/HEAD/skills/socratic-questor/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md