Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

add skill (#2082)

Mike Fortman180e778e11c4
diff --git a/.claude/skills/dev-stack b/.claude/skills/dev-stack
new file mode 120000
index 000000000..d67a79799
--- /dev/null
+++ b/.claude/skills/dev-stack
@@ -0,0 +1 @@
+../../plugins/openrag/skills/dev-stack
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index 79696881f..6079737f5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Agent Instructions
-This repository ships with **agent skills** that any compliant agent can use to help users install OpenRAG and integrate the OpenRAG SDK. The canonical skill files are markdown with YAML frontmatter (the [Agent Skills](https://github.com/anthropics/skills) format), and live under `plugins/openrag/skills/`.
+This repository ships with **agent skills** that any compliant agent can use to help users install OpenRAG, integrate the OpenRAG SDK, and run the local dev stack. The canonical skill files are markdown with YAML frontmatter (the [Agent Skills](https://github.com/anthropics/skills) format), and live under `plugins/openrag/skills/`.
## Available skills
@@ -8,6 +8,7 @@ This repository ships with **agent skills** that any compliant agent can use to
| --- | --- | --- |
| `openrag_install` | [`plugins/openrag/skills/install/SKILL.md`](plugins/openrag/skills/install/SKILL.md) | Plan and execute a minimal OpenRAG installation, verify locally. |
| `openrag_sdk` | [`plugins/openrag/skills/sdk/SKILL.md`](plugins/openrag/skills/sdk/SKILL.md) | Guide SDK integration (Python, TypeScript, MCP) with code examples. |
+| `openrag_dev_stack` | [`plugins/openrag/skills/dev-stack/SKILL.md`](plugins/openrag/skills/dev-stack/SKILL.md) | Start, monitor, restart, or stop the local dev stack (Docker infra + host backend + host frontend). |
## How to use these skills
@@ -15,7 +16,7 @@ Pick the path that matches your agent runtime.
### Claude Code (this repo)
-`.claude/skills/` symlinks into the plugin, so after cloning the repo the skills are auto-discovered by Claude Code — invoke with `/install` or `/sdk`, or let Claude trigger them automatically based on the description fields.
+`.claude/skills/` symlinks into the plugin, so after cloning the repo the skills are auto-discovered by Claude Code — invoke with `/install`, `/sdk`, or `/dev-stack`, or let Claude trigger them automatically based on the description fields.
### Claude Code (install globally, any repo)
diff --git a/plugins/README.md b/plugins/README.md
index 28e494821..540e0af9e 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -17,11 +17,13 @@ openrag/
│ │ └── plugin.json # plugin manifest (name, version, repo)
│ └── skills/
│ ├── install/SKILL.md # guided OpenRAG installation
-│ └── sdk/SKILL.md # OpenRAG SDK integration helper
+│ ├── sdk/SKILL.md # OpenRAG SDK integration helper
+│ └── dev-stack/SKILL.md # local dev stack runner (infra + backend + frontend)
├── .claude/
│ └── skills/ # symlinks into plugins/openrag/skills
-│ ├── install -> ../../plugins/openrag/skills/install
-│ └── sdk -> ../../plugins/openrag/skills/sdk
+│ ├── install -> ../../plugins/openrag/skills/install
+│ ├── sdk -> ../../plugins/openrag/skills/sdk
+│ └── dev-stack -> ../../plugins/openrag/skills/dev-stack
└── AGENTS.md # entry point for any agent working in the repo
```
@@ -33,7 +35,7 @@ There are four ways to get these skills in front of an agent.
### 1. Clone this repo and use Claude Code
-No install step. `.claude/skills/` symlinks into the plugin, so Claude Code auto-discovers `install` and `sdk` when it starts in this directory. Invoke with `/install` or `/sdk`, or let Claude trigger them automatically based on the `description` fields.
+No install step. `.claude/skills/` symlinks into the plugin, so Claude Code auto-discovers `install`, `sdk`, and `dev-stack` when it starts in this directory. Invoke with `/install`, `/sdk`, or `/dev-stack`, or let Claude trigger them automatically based on the `description` fields.
### 2. Install into Claude Code globally (any project)
diff --git a/plugins/openrag/.claude-plugin/plugin.json b/plugins/openrag/.claude-plugin/plugin.json
index b85d80996..6cd61d9e1 100644
--- a/plugins/openrag/.claude-plugin/plugin.json
+++ b/plugins/openrag/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "openrag",
- "version": "0.1.0",
- "description": "OpenRAG agent skills: guided installation and SDK integration helpers.",
+ "version": "0.2.0",
+ "description": "OpenRAG agent skills: guided installation, SDK integration, and local dev-stack management.",
"repository": "https://github.com/langflow-ai/openrag"
}
diff --git a/plugins/openrag/skills/dev-stack/SKILL.md b/plugins/openrag/skills/dev-stack/SKILL.md
new file mode 100644
index 000000000..24270d23f
--- /dev/null
+++ b/plugins/openrag/skills/dev-stack/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: openrag_dev_stack
+description: Start, monitor, restart, or stop the local OpenRAG dev stack (Docker infra + host backend + host frontend). Use when the user says "start the dev stack", "run the app locally", "restart the backend/frontend", "factory-reset", "is the stack up?", or asks to bring services up/down for local development.
+---
+
+# OpenRAG local dev stack
+
+The local dev setup has three parts that normally run in three terminals. As an agent, run them from one session: part 1 is a detached Docker command, parts 2 and 3 are long-running processes you must launch **in the background** (however your runtime runs a command without blocking) and monitor.
+
+Run everything from the repo root.
+
+## 1. Infrastructure (OpenSearch, Langflow, Dashboards)
+
+```bash
+make dev-local-cpu
+```
+
+- Builds langflow/opensearch images if needed, then starts containers detached — the command itself exits when containers are up. Run it in the foreground (first run can take several minutes if images need building; use a generous timeout).
+- Endpoints: Langflow http://localhost:7860, OpenSearch http://localhost:9200, Dashboards http://localhost:5601.
+- Verify with `docker compose ps` — expect `opensearch`, `dashboards`, and `langflow` containers running/healthy. Wait for OpenSearch to be healthy before starting the backend.
+
+## 2. Backend (host process)
+
+```bash
+make backend
+```
+
+- Long-running (uvicorn via `uv run python src/main.py`) — launch in the background with its output captured somewhere you can read back. If your runtime already captures background output, don't also tee to a log file.
+- Requires `.env` in the repo root (the target errors clearly if missing; fix by copying `.env.example`).
+- Serves on http://localhost:8000 (`OPENRAG_BACKEND_PORT`). Ready when uvicorn logs "Application startup complete".
+
+## 3. Frontend (host process)
+
+```bash
+make frontend
+```
+
+- Long-running (Next.js dev server) — launch in the background with its output captured, same as the backend.
+- Installs `frontend/node_modules` automatically on first run.
+- Serves on http://localhost:3000 (`FRONTEND_PORT`). Ready when Next prints the local URL / "Ready".
+
+## Restarting
+
+- **Backend only** (the most common case): kill the backend background process, then relaunch `make backend` in the background as in section 2. Same pattern for the frontend.
+- **Containers only**: `make stop` then `make dev-local-cpu`.
+- **Factory reset** (fix a wedged stack by wiping all state): destructive — removes volumes, `langflow-data/`, `config/`, `data/`, and JWT keys. Get explicit user confirmation before running it. The plain target prompts interactively for "yes", which an agent can't answer, so run:
+
+ ```bash
+ make factory-reset FORCE=true
+ ```
+
+ Then bring the stack back up: `make dev-local-cpu`, and relaunch backend and frontend.
+
+## Monitoring
+
+- Watch the backend and frontend processes' output for errors; report crashes to the user rather than silently restarting on a loop.
+- Container logs: `make logs-os`, `make logs-lf`, or `docker compose logs -f <service>`.
+- If the user wants to watch backend/frontend logs themselves, point them at wherever your runtime exposes background process output, or give them a `tail -f` command for the process's log/output file.
+- Status check: `docker compose ps` for containers; `curl -s http://localhost:8000/health` for the backend and `curl -s -o /dev/null -w '%{http_code}' http://localhost:3000` for the frontend.
+
+## Stopping
+
+- Backend/frontend: kill their background processes.
+- Containers: `make stop` (stops and removes all OpenRAG containers). `make clean` also removes volumes — destructive, only on explicit request.