yuxuanhui
7797ff88df
- Introduced a new reference document for streaming output issues, detailing the differences between streaming APIs and providing solutions for common problems. - Created a structured output issues reference, outlining the use of `with_structured_output`, `response_format`, and schema enforcement strategies. - Added a user query convention guide to standardize structured questions for skill authors, including block types for queries and data gathering. - Implemented a template for a chat model, encapsulating API key management, request payload construction, and response handling. - Established a symlink for the LangChain dev guide in the Claude skills directory for easier access. - Initialized a skills lock file to manage dependencies and versions for the LangChain dev guide.
109 lines
4.1 KiB
Markdown
109 lines
4.1 KiB
Markdown
# User Query Convention
|
||
|
||
A cross-platform convention for skill authors to define structured questions. Agents parse these blocks and render them via the best available tool on their platform.
|
||
|
||
## Block Types
|
||
|
||
### `<!-- query -->` — Single or multi-choice question
|
||
|
||
Use when the user must pick between approaches, modes, or options.
|
||
|
||
```markdown
|
||
<!-- query
|
||
type: choice
|
||
question: "Which approach do you prefer?"
|
||
options:
|
||
- label: "Code generation"
|
||
description: "Generate integration class in your repo"
|
||
- label: "Third-party library"
|
||
description: "Use langchain-dev-utils built-in adapters"
|
||
default: 1
|
||
-->
|
||
```
|
||
|
||
Fields:
|
||
- `type`: `choice` (single-select) or `multi-choice` (multi-select)
|
||
- `question`: The question to present
|
||
- `options`: 2–4 options, each with `label` and `description`
|
||
- `default`: 1-based index of the default option (applied when user says "use defaults" or doesn't answer)
|
||
|
||
### `<!-- gather -->` — Collect multiple inputs
|
||
|
||
Use when the skill needs several pieces of information from the user before proceeding.
|
||
|
||
```markdown
|
||
<!-- gather
|
||
prompt: "Confirm the following details:"
|
||
fields:
|
||
- name: model_name
|
||
question: "Model name (lowercase)"
|
||
example: "qwen"
|
||
required: true
|
||
- name: api_base
|
||
question: "API base URL"
|
||
example: "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||
required: true
|
||
- name: api_key_env
|
||
question: "API key env var name"
|
||
example: "QWEN_API_KEY"
|
||
required: true
|
||
fallback: "Use reasonable defaults from the provider's documentation."
|
||
-->
|
||
```
|
||
|
||
Fields:
|
||
- `prompt`: Introductory text shown before the questions
|
||
- `fields`: List of inputs to collect; each has `name`, `question`, `example`, and optional `required` (default true)
|
||
- `fallback`: Instruction for the agent when the user declines to answer or says "just use defaults"
|
||
|
||
## Platform Rendering
|
||
|
||
| Platform | `<!-- query -->` | `<!-- gather -->` |
|
||
|----------|-----------------|-------------------|
|
||
| Claude Code | `AskUserQuestion` with `options` | `AskUserQuestion` with one question per field |
|
||
| Gemini CLI | `ask_user` | `ask_user` per field |
|
||
| Copilot CLI | Output as formatted text with numbered options, wait for reply | Output as numbered list with examples, wait for reply |
|
||
| Cursor / Windsurf | Output as formatted text, wait for reply | Output as formatted text, wait for reply |
|
||
| Codex | Output as formatted text (autonomous mode — apply defaults if no response) | Apply defaults (autonomous mode) |
|
||
|
||
### Claude Code example rendering
|
||
|
||
For a `<!-- query -->` block, the agent calls:
|
||
```
|
||
AskUserQuestion({
|
||
questions: [{
|
||
question: "Which approach do you prefer?",
|
||
header: "Approach",
|
||
options: [
|
||
{ label: "Code generation", description: "Generate integration class in your repo" },
|
||
{ label: "Third-party library", description: "Use langchain-dev-utils built-in adapters" }
|
||
],
|
||
multiSelect: false
|
||
}]
|
||
})
|
||
```
|
||
|
||
For a `<!-- gather -->` block, the agent calls `AskUserQuestion` with up to 4 questions (the tool's limit), batching if needed.
|
||
|
||
### Fallback text rendering (Cursor, Copilot, Codex)
|
||
|
||
For platforms without structured prompting, output:
|
||
|
||
```
|
||
**Which approach do you prefer?**
|
||
|
||
1. **Code generation** — Generate integration class in your repo
|
||
2. **Third-party library** — Use langchain-dev-utils built-in adapters
|
||
|
||
(Reply with number or description. Default: 1)
|
||
```
|
||
|
||
## Guidelines for Skill Authors
|
||
|
||
1. **Place blocks inline** where the question naturally occurs in the skill flow — not in a separate section
|
||
2. **Always provide a `default` or `fallback`** — agents running in autonomous mode need a way to proceed without blocking
|
||
3. **Keep options to 2–4** — matches `AskUserQuestion` limits and avoids decision fatigue
|
||
4. **Use `<!-- gather -->` sparingly** — prefer inferring from project context (package manager, existing config) over asking
|
||
5. **Blocks are HTML comments** — they don't render in markdown viewers, so the surrounding prose should still make sense without them
|
||
6. **Prose context around blocks is required** — the block is for the agent's structured rendering; the surrounding markdown provides context for human readers browsing the skill file
|