RAGFlow Skill

Operate RAGFlow v0.25.x deployments through the bundled Node CLI and API client. Use when user needs to manage RAGFlow datasets, documents, uploads, parsing,...

Security Scan

The skill's files, instructions, and required environment variables are consistent with a CLI client for managing a RAGFlow v0.25.x deployment; nothing in the bundle appears to request unrelated credentials or perform unexplained exfiltration.

Purpose & Capability

Name/description (RAGFlow CLI) matches the included Node scripts and API client. Required binaries (node) and required env vars (RAGFLOW_URL, RAGFLOW_API_KEY) are appropriate and expected for the stated purpose.

Instruction Scope

SKILL.md instructs the agent to run the bundled CLI (scripts/ragflow.js) and documents the API route shapes and optional env tuning variables. The runtime behavior (reading local files for uploads, creating temp files only for the repro script, calling the configured RAGFlow server) matches the documented scope. The instructions do not ask the agent to read unrelated system secrets or external endpoints beyond the RAGFlow server and optional embed flows.

Install Mechanism

This is instruction-only (no network install/downloads). The bundle includes Node scripts and a JS API client that will be executed by node; no external installers, URL downloads, or archive extraction are present in the manifest.

Credentials

Only RAGFLOW_URL and RAGFLOW_API_KEY are required and declared (primary credential = RAGFLOW_API_KEY). Optional envs referenced in docs and code (RAGFLOW_WEB_TOKEN, RAGFLOW_REPRO_*, RAGFLOW_DELETE_CHUNK_*) are explained and tied to documented features. No unrelated service credentials are requested.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or global agent configuration. It creates only temporary files for diagnostics and cleans them up; it uses the provided API key to call the target RAGFlow instance as expected.

Assessment

This skill appears to be a straightforward Node-based CLI for managing a RAGFlow v0.25.x server and only requires the server URL and API key. Before installing: 1) Confirm you trust the RAGFlow server you will point it at and be comfortable giving the skill the RAGFLOW_API_KEY (the CLI will use that key to perform CRUD operations and to upload files). 2) Be aware that any local files you pass to upload commands will be read and transmitted to the configured server. 3) The bundle includes a repro diagnostic script that creates and deletes a temporary dataset — review/avoid running it on production tenants. 4) If you need higher assurance, inspect the included scripts (lib/api.js and scripts/*.js) yourself or run them in a sandboxed environment; there are no hidden network endpoints or extra credentials requested beyond those documented.

Use this skill to operate RAGFlow through scripts/ragflow.js. The CLI wraps the full v0.25.x REST API - every action goes through node {baseDir}/scripts/ragflow.js <command> [options]. Prefer --json on any command when the output will be parsed or chained into another step.

Requirements

• Set RAGFLOW_URL and RAGFLOW_API_KEY in the environment or this skill's .env.
• Use Node.js to run bundled scripts.
• Set RAGFLOW_WEB_TOKEN only when list-models needs a web-session token for /v1/llm/my_llms.
• Tune chunk deletion retries only when needed with RAGFLOW_DELETE_CHUNK_RETRIES and RAGFLOW_DELETE_CHUNK_RETRY_DELAY_MS.
• Tune the chunk deletion diagnostic script only when needed with RAGFLOW_REPRO_TIMEOUT_MS, RAGFLOW_REPRO_DELETE_RETRIES, RAGFLOW_REPRO_DELETE_RETRY_DELAY_MS, and RAGFLOW_REPRO_EMBEDDING_MODEL.

Quick Command Reference

Scenario	Commands
Knowledge base setup	create-dataset, list-datasets, get-dataset, update-dataset, delete-datasets
Document ingestion	upload-documents, list-documents, get-document, update-document, delete-documents, metadata-summary
Parsing & chunking	start-parsing, stop-parsing, wait-parsing, list-chunks, add-chunk, update-chunk, delete-chunks
Direct retrieval	retrieve
Chat assistant	create-chat, list-chats, get-chat, update-chat, patch-chat, delete-chats
Chat sessions	create-session, list-sessions, delete-sessions, chat, chat-session
Agent	create-agent, list-agents, get-agent, update-agent, delete-agents
Agent sessions	create-agent-session, list-agent-sessions, delete-agent-sessions, agent-chat
Embedded website access	list-system-tokens, create-system-token, delete-system-token, embed-code, embed-info, embed-chat, embed-agent-chat
Model discovery	list-models
System	system-version, get-log-levels, set-log-level

Common Workflows

Full RAG pipeline (upload -> parse -> retrieve)

1. create-dataset --name "My KB" --chunk-method naive
2. upload-documents --dataset <id> --files ./doc1.pdf ./doc2.txt
3. start-parsing --dataset <id> --doc-ids <doc_id1> <doc_id2>
4. wait-parsing --dataset <id> --doc-ids <doc_id1> <doc_id2>
5. retrieve --question "What is X?" --datasets <id>

Chat assistant with sessions

1. create-chat --name "Q&A" --datasets <id> --llm-id qwen-turbo@Tongyi-Qianwen
2. create-session --chat <chat_id>
3. chat-session --chat <chat_id> --session <session_id> --question "Hello"

Agent workflow

1. create-agent --title "Assistant" --dsl @agent_dsl.json
2. create-agent-session --agent <agent_id>
3. agent-chat --agent <agent_id> --session <session_id> --question "Hello"

Embedded website access

1. embed-code --chat <chat_id> --type fullscreen or embed-code --agent <agent_id> --type widget
2. embed-info --chat <chat_id> or embed-info --agent <agent_id>
3. embed-chat --chat <chat_id> --question "Hello" or embed-agent-chat --agent <agent_id> --question "Hello"

embed-chat automatically creates the embedded chatbot session when --session is omitted. RAGFlow's shared-site route only creates a session and returns the prologue on the first no-session request, so the CLI bootstraps session_id first and then sends the real question.

Workflow Decision Guide

The first step in any RAGFlow operation is resolving the target resource ID. After that, choose the right path:

1. Need CLI syntax or option details? -> Read references/COMMANDS.md - it's organized by workflow scenario with full option tables.
2. Editing client code or checking request/response shapes? -> Read references/API.md - it has code examples for every RagflowClient method.
3. A command failed? -> Read references/TROUBLESHOOTING.md - common errors with causes and fixes.
4. Formatting output for the user? -> Read references/REFERENCE.md - consistent response templates and status labels.

Key Constraints

• Destructive deletes need confirmation. RAGFlow deletes are immediate and irreversible. Confirm before running delete-datasets, delete-documents, delete-chunks, delete-chats, delete-sessions, or delete-agents - unless the resource is a temporary artifact you created in the same workflow and the user asked you to clean up.
• Upload and parsing are separate steps. RAGFlow does not auto-parse on upload because different documents may need different chunk methods. Upload first, adjust config if needed, then start parsing explicitly.
• Preserve user-uploaded filenames. RAGFlow stores the multipart filename as the document name. If a user attachment is materialized as a task ID or temporary path, pass the original filename inline: upload-documents --files <original-name>=<path>.
• Use v0.25.x route shapes from the references. The RAGFlow API has changed between versions. The routes and payloads in the reference docs match v0.25.x - inventing fallback payloads will produce errors on real servers.
• Tenant model identifiers use the model@provider format. When creating datasets with --embedding-model or chat assistants with --llm-id, the server expects the full identifier, for example text-embedding-v4@Tongyi-Qianwen or qwen-turbo@Tongyi-Qianwen, not a numeric model row ID. Use list-models to discover model names and providers.
• Chat sessions use the API-key SDK route. chat-session posts to /api/v1/chats/{chat_id}/completions with session_id in the body. This is the v0.25.x API-key route - the login-session frontend route is intentionally avoided.
• Embedded access uses beta tokens and embedded sessions. embed-code, embed-info, embed-chat, and embed-agent-chat use the shared-site /api/v1/chatbots/* or /api/v1/agentbots/* routes. If --beta is not supplied, the CLI reuses the first /api/v1/system/tokens item with beta or creates one. For chatbot completions, the CLI auto-bootstraps session_id unless --session is supplied.
• Agent DSL requires specific top-level fields. RAGFlow agents need components, history, path, retrieval, globals, and graph in the DSL. Missing fields cause KeyError at creation time.
• Chunk deletion may need retries. The v0.25.0 server can return rm_chunk deleted chunks 0, expect N due to document-store refresh lag even when the chunk exists. The CLI handles this automatically - it retries after confirming the chunk is still visible via exact ID lookup. If retries still fail, run scripts/repro-delete-chunks.js for a clean diagnosis.

Output Format

When presenting results to the user, follow the templates in references/REFERENCE.md. Key conventions:

• 3+ items with attributes -> Table, abbreviating long IDs
• Sequential steps -> Numbered list
• Parsing status -> Use labels: UNSTART, RUNNING, CANCEL, DONE, FAIL
• Search results -> Table with similarity scores, content as quote blocks
• Errors -> Show code and human-readable message