dify-knowledge-base-search — Claude Code skill: Dify search
The dify-knowledge-base-search skill tests Dify dataset retrieval and helps debug knowledge-base queries, retrieval_model settings, and response data.
MIT 114 installs ★ 11 updated 2026-10-19
npx skills add tiangong-ai/agent-skills --skill dify-knowledge-base-search -a claude-codeWhat dify-knowledge-base-search does
The skill guides an agent through a Dify Knowledge Base Search request. It takes JSON with query and an optional retrieval_model.top_k, then sends a POST request to /datasets/${DIFY_DATASET_ID}/retrieve with the required content and bearer-auth headers. The payload template is stored in assets/example-request.json.
The setup uses DIFY_API_BASE_URL, DIFY_DATASET_ID, and DIFY_API_KEY; the base URL must include /v1. A successful response has status 200 and contains query plus records. When records is empty, the skill suggests retrying with a moderately higher top_k. Without DIFY_API_KEY, authentication fails. Reference files cover environment variables, request and response shapes, and testing.
What it helps with
- test a Dify dataset retrieval request
- trace a Dify authentication failure
- tune
retrieval_model.top_k - investigate empty or weak search results
- check the expected Dify request and response shapes
Example prompts for the agent
- Test the Dify knowledge-base search for “how do I request a refund?” and show the request body.
- Explain why
recordsis empty and suggest a change toretrieval_model.top_k. - Debug this Dify integration and check
DIFY_API_BASE_URLand the authorization header.
How to install dify-knowledge-base-search
1Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill dify-knowledge-base-search -a claude-code2Manually: put the files in place
~/.claude/skills/dify-knowledge-base-search/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dify-knowledge-base-search/
1Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill dify-knowledge-base-search -a codex2Manually: put the files in place
.agents/skills/dify-knowledge-base-search/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill dify-knowledge-base-search -a cursor2Manually: put the files in place
.cursor/skills/dify-knowledge-base-search/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install tiangong-ai/agent-skills dify-knowledge-base-search2Manually: put the files in place
.github/skills/dify-knowledge-base-search/SKILL.md1Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill dify-knowledge-base-search -a gemini-cli2Platform CLI
gemini skills install https://github.com/tiangong-ai/agent-skills --path dify-knowledge-base-searchManually: put the files in place
.devin/skills/dify-knowledge-base-search/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add tiangong-ai/agent-skills --skill dify-knowledge-base-search -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about dify-knowledge-base-search
How do I install dify-knowledge-base-search in Claude Code?
Run npx skills add tiangong-ai/agent-skills --skill dify-knowledge-base-search -a claude-code. The skill will be placed at ~/.claude/skills/dify-knowledge-base-search/SKILL.md.
What does dify-knowledge-base-search do?
It helps an agent call Dify’s dataset retrieve API and inspect knowledge-base search results. It also covers retrieval_model options and common route, authentication, and result-quality issues.
What must be configured before making a request?
Set DIFY_API_BASE_URL with /v1 included, along with DIFY_DATASET_ID and DIFY_API_KEY. The request sends the key as Authorization: Bearer $DIFY_API_KEY.
Source text
SKILL.md · MIT
---
name: dify-knowledge-base-search
description: Dify dataset retrieve API for knowledge base chunk search/testing. Use when integrating or debugging Dify knowledge base retrieval requests, retrieval_model options, or response shaping.
---
# Dify Knowledge Base Search
## Prepare required inputs
- Provide `data` as JSON containing `query` and optional `retrieval_model.top_k`.
- Read these env vars:
- `DIFY_API_BASE_URL`: base API URL and include `/v1` (example: `https://api.dify.ai/v1`).
- `DIFY_DATASET_ID`: target dataset ID.
- `DIFY_API_KEY`: send as `Authorization: Bearer <DIFY_API_KEY>`.
## Send request
- Endpoint: `${DIFY_API_BASE_URL}/datasets/${DIFY_DATASET_ID}/retrieve`
- Headers:
- `Content-Type: application/json`
- `Authorization: Bearer <DIFY_API_KEY>`
- Use `assets/example-request.json` as the payload template.
```bash
curl -sS --location --request POST "$DIFY_API_BASE_URL/datasets/$DIFY_DATASET_ID/retrieve" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DIFY_API_KEY" \
--data @assets/example-request.json
```
## Interpret response
- Request shape: `{ "query": string, "retrieval_model"?: { "top_k": number } }`
- Success shape: 200 with `{ query, records: [...] }`
- If `records` is empty, increase `retrieval_model.top_k` moderately and retry.
## Troubleshoot quickly
- If auth fails, verify `DIFY_API_KEY` and `Authorization` header format.
- If route fails, verify `DIFY_API_BASE_URL` includes `/v1`.
- If results are low quality, refine `query` and tune `top_k`.
## References
- `references/env.md`
- `references/request-response.md`
- `references/testing.md`
## Assets
- `assets/example-request.json`
© tiangong-ai · MIT · tiangong-ai/agent-skills