Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add tiangong-ai/agent-skills --skill dify-knowledge-base-search -a claude-code
Open on GitHub

What 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 records is empty and suggest a change to retrieval_model.top_k.
  • Debug this Dify integration and check DIFY_API_BASE_URL and 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-code

2Manually: put the files in place

~/.claude/skills/dify-knowledge-base-search/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/dify-knowledge-base-search/

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

Similar skills

All skills for Backend and APIs →

From the same set5

Project sponsors

Companies that keep this analytics open