@ragieai/skills 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "ragieai",
+  "description": "Ragie AI — managed RAG platform for document ingestion, search, and retrieval. Provides skills for integrating Ragie into applications and using the Ragie MCP server.",
+  "author": {
+    "name": "Ragie",
+    "url": "https://ragie.ai"
+  }
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "ragie": {
+      "type": "http",
+      "url": "https://api.ragie.ai/mcp/${RAGIE_PARTITION}",
+      "headers": {
+        "Authorization": "Bearer ${RAGIE_API_KEY}"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ragie Corp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @ragieai/skills
+
+Ragie skills for AI coding agents. Install once and your agent understands how to ingest documents, run retrievals, build RAG pipelines, configure the MCP server, and handle multi-tenancy with Ragie.
+
+Works with Claude Code, Cursor, Cline, Copilot, Windsurf, and [40+ other agents](https://skills.sh).
+
+## Installation
+
+### Via skills CLI (recommended)
+
+Installs into your current project for whichever agent you use:
+
+```bash
+npx skills add ragieai/skills
+```
+
+### Via npm
+
+For programmatic access to skill and reference content:
+
+```bash
+npm install @ragieai/skills
+```
+
+### Local development
+
+Symlink the skill directory directly into Claude Code's skills folder so edits are reflected immediately:
+
+```bash
+ln -s /path/to/ragieai/skills/skills/ragie ~/.claude/skills/ragie
+```
+
+## What's Included
+
+### Skill
+
+One skill — `ragie` — that activates when you ask about integrating Ragie, building RAG pipelines, ingesting documents, configuring the MCP server, or working with retrievals.
+
+### References
+
+| File | Content |
+|------|---------|
+| `quickstart.md` | Install SDK, ingest a document, run first retrieval |
+| `ingestion.md` | Files, URLs, raw text, readiness polling, webhooks, bulk ingest |
+| `retrieval.md` | Search options, `topK`, reranking, hybrid search, metadata filters |
+| `mcp.md` | MCP server URL pattern, configuration, the `retrieve` tool |
+| `partitions.md` | Multi-tenancy, partition isolation, partition management |
+| `metadata-filtering.md` | Tagging documents, filtering at retrieval time |
+| `rag-patterns.md` | RAG responses, streaming, citations, tool use, production checklist |
+| `api-reference.md` | Full REST endpoint reference, error codes |
+| `python.md` | Python SDK equivalents for all patterns |
+
+References are loaded on demand — only what's relevant to the current task is pulled into context.
+
+## MCP Server
+
+The Ragie MCP server exposes a `retrieve` tool scoped to a partition, letting your agent search your knowledge base directly. Configure it with two environment variables:
+
+```bash
+export RAGIE_API_KEY=ragie_...
+export RAGIE_PARTITION=your-partition
+```
+
+The plugin's `.mcp.json` handles the rest. See `mcp.md` for multi-partition setup.
+
+## Programmatic API
+
+```typescript
+import {
+  getSkill,
+  getReference,
+  getSkillPath,
+  getReferencePath,
+  getSkillsDir,
+} from "@ragieai/skills";
+
+// Get skill or reference content as a string
+const skill = getSkill("ragie");
+const quickstart = getReference("quickstart");
+
+// Get absolute file paths
+const skillPath = getSkillPath("ragie");
+const refPath = getReferencePath("rag-patterns");
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  getReference: () => getReference,
+  getReferencePath: () => getReferencePath,
+  getSkill: () => getSkill,
+  getSkillPath: () => getSkillPath,
+  getSkillsDir: () => getSkillsDir
+});
+module.exports = __toCommonJS(index_exports);
+var import_fs = require("fs");
+var import_path = require("path");
+var root = (0, import_path.join)(__dirname, "..");
+function getReferencePath(name) {
+  return (0, import_path.join)(root, "skills", "ragie", "references", `${name}.md`);
+}
+function getSkillPath(name) {
+  return (0, import_path.join)(root, "skills", name, "SKILL.md");
+}
+function getSkillsDir() {
+  return (0, import_path.join)(root, "skills");
+}
+function getReference(name) {
+  return (0, import_fs.readFileSync)(getReferencePath(name), "utf-8");
+}
+function getSkill(name) {
+  return (0, import_fs.readFileSync)(getSkillPath(name), "utf-8");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getReference,
+  getReferencePath,
+  getSkill,
+  getSkillPath,
+  getSkillsDir
+});

package/dist/index.d.cts

@@ -0,0 +1,16 @@
+declare const REFERENCES: readonly ["quickstart", "ingestion", "retrieval", "mcp", "partitions", "metadata-filtering", "rag-patterns", "api-reference", "python"];
+declare const SKILLS: readonly ["ragie"];
+type ReferenceName = (typeof REFERENCES)[number];
+type SkillName = (typeof SKILLS)[number];
+/** Returns the absolute path to a reference file. */
+declare function getReferencePath(name: ReferenceName): string;
+/** Returns the absolute path to a skill's SKILL.md. */
+declare function getSkillPath(name: SkillName): string;
+/** Returns the absolute path to the skills directory. */
+declare function getSkillsDir(): string;
+/** Returns the content of a reference file as a string. */
+declare function getReference(name: ReferenceName): string;
+/** Returns the content of a skill's SKILL.md as a string. */
+declare function getSkill(name: SkillName): string;
+
+export { type ReferenceName, type SkillName, getReference, getReferencePath, getSkill, getSkillPath, getSkillsDir };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+declare const REFERENCES: readonly ["quickstart", "ingestion", "retrieval", "mcp", "partitions", "metadata-filtering", "rag-patterns", "api-reference", "python"];
+declare const SKILLS: readonly ["ragie"];
+type ReferenceName = (typeof REFERENCES)[number];
+type SkillName = (typeof SKILLS)[number];
+/** Returns the absolute path to a reference file. */
+declare function getReferencePath(name: ReferenceName): string;
+/** Returns the absolute path to a skill's SKILL.md. */
+declare function getSkillPath(name: SkillName): string;
+/** Returns the absolute path to the skills directory. */
+declare function getSkillsDir(): string;
+/** Returns the content of a reference file as a string. */
+declare function getReference(name: ReferenceName): string;
+/** Returns the content of a skill's SKILL.md as a string. */
+declare function getSkill(name: SkillName): string;
+
+export { type ReferenceName, type SkillName, getReference, getReferencePath, getSkill, getSkillPath, getSkillsDir };

package/dist/index.js

@@ -0,0 +1,26 @@
+// src/index.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+var root = join(__dirname, "..");
+function getReferencePath(name) {
+  return join(root, "skills", "ragie", "references", `${name}.md`);
+}
+function getSkillPath(name) {
+  return join(root, "skills", name, "SKILL.md");
+}
+function getSkillsDir() {
+  return join(root, "skills");
+}
+function getReference(name) {
+  return readFileSync(getReferencePath(name), "utf-8");
+}
+function getSkill(name) {
+  return readFileSync(getSkillPath(name), "utf-8");
+}
+export {
+  getReference,
+  getReferencePath,
+  getSkill,
+  getSkillPath,
+  getSkillsDir
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ragieai/skills",
+  "version": "0.1.0",
+  "description": "Ragie skills for AI coding agents — document ingestion, retrieval, RAG patterns, and MCP integration",
+  "keywords": [
+    "ragie",
+    "rag",
+    "retrieval",
+    "ai",
+    "skills",
+    "claude",
+    "cursor"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    ".claude-plugin",
+    ".mcp.json"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.4"
+  }
+}

package/skills/ragie/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ragie
+description: >
+  This skill should be used when the user wants to "add Ragie to my project", "integrate Ragie",
+  "use Ragie for RAG", "ingest documents with Ragie", "search documents with Ragie",
+  "set up document retrieval", "build a RAG pipeline", "use the Ragie MCP", "query my knowledge base",
+  "connect Ragie to Claude", or mentions Ragie in the context of document search, retrieval-augmented
+  generation, or knowledge base management. Provides end-to-end guidance for the Ragie managed RAG
+  platform: SDK setup, document ingestion, retrieval, MCP usage, and RAG application patterns.
+version: "1.0.0"
+---
+
+# Ragie
+
+Ragie is a fully managed RAG (Retrieval-Augmented Generation) platform. It handles document ingestion, chunking, embedding, and retrieval — available via REST API, Python/TypeScript SDKs, and an MCP server.
+
+## References
+
+Load the relevant reference for the task at hand:
+
+| Reference | When to load |
+|-----------|--------------|
+| `references/quickstart.md` | Getting started, first integration, install instructions |
+| `references/ingestion.md` | Uploading files/URLs/text, readiness polling, webhooks, bulk ingest |
+| `references/retrieval.md` | Search options, `top_k`, reranking, hybrid search, filters |
+| `references/mcp.md` | MCP server setup, `retrieve` tool, URL pattern, multi-partition config |
+| `references/partitions.md` | Multi-tenancy, partition isolation, partition management |
+| `references/metadata-filtering.md` | Tagging documents, filtering at retrieval time |
+| `references/rag-patterns.md` | Building RAG responses, streaming, citations, tool use, production checklist |
+| `references/api-reference.md` | Full REST endpoint reference, error codes, SDK auth |
+| `references/python.md` | Python SDK equivalents for all patterns |
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Document** | Any ingested file, URL, or raw text. Processed asynchronously. |
+| **Chunk** | A segment produced by Ragie's splitting pipeline. The unit of retrieval. |
+| **Retrieval** | Hybrid semantic + keyword search across chunks. Returns `scored_chunks`. |
+| **Partition** | Logical namespace for isolation (multi-tenancy, environments). |
+| **Metadata** | Key-value pairs on documents; used for filtering at retrieval time. |
+
+## Quick Decision Guide
+
+- **New to Ragie?** → `references/quickstart.md`
+- **Uploading documents?** → `references/ingestion.md`
+- **Searching / querying?** → `references/retrieval.md`
+- **Using Claude Code's MCP tool?** → `references/mcp.md`
+- **Building a RAG app end-to-end?** → `references/rag-patterns.md`
+- **Multiple tenants or environments?** → `references/partitions.md`

package/skills/ragie/references/api-reference.md

@@ -0,0 +1,203 @@
+# Ragie REST API Reference
+
+Base URL: `https://api.ragie.ai`
+
+Authentication: `Authorization: Bearer <RAGIE_API_KEY>` on every request.
+
+---
+
+## Documents
+
+### Create document from URL
+
+```
+POST /documents
+Content-Type: application/json
+
+{
+  "url": "https://example.com/page",
+  "name": "My Doc",           // optional display name
+  "partition": "tenant-id",   // optional partition
+  "metadata": {}              // optional key-value metadata
+}
+```
+
+### Create document from raw bytes
+
+```
+POST /documents/raw
+Content-Type: multipart/form-data
+
+content       <file bytes>
+content_type  application/pdf | text/plain | text/markdown | ...
+name          <string>
+partition     <string>   (optional)
+metadata      <json>     (optional)
+```
+
+### Get document
+
+```
+GET /documents/{document_id}
+```
+
+Response fields: `id`, `name`, `status` (`pending` | `partitioning` | `partitioned` | `refined` | `chunked` | `indexed` | `summary_indexed` | `keyword_indexed` | `ready` | `failed`), `metadata`, `partition`, `created_at`, `updated_at`.
+
+### List documents
+
+```
+GET /documents?page_size=<n>&cursor=<c>&filter=<json>
+Partition: <partition>    ← partition is a header, not a query param
+```
+
+Returns `{ "results": [...], "pagination": { "next_cursor": "..." } }`.
+
+### Update document metadata
+
+```
+PATCH /documents/{document_id}/metadata
+Content-Type: application/json
+
+{
+  "metadata": { "key": "value" }
+}
+```
+
+Performs a partial update. Keys set to `null` are deleted.
+
+### Delete document
+
+```
+DELETE /documents/{document_id}
+```
+
+---
+
+## Retrievals
+
+### Retrieve chunks
+
+```
+POST /retrievals
+Content-Type: application/json
+
+{
+  "query": "What are the rate limits?",
+  "top_k": 8,                       // default 8
+  "rerank": true,                   // cross-encoder rerank (recommended)
+  "partition": "tenant-id",         // scope to partition (optional)
+  "filter": { "product": "api" },   // metadata filter (optional)
+  "max_chunks_per_document": 2,     // limit chunks per source doc (optional)
+  "recency_bias": false             // favor recently ingested docs (optional)
+}
+```
+
+Response:
+
+```json
+{
+  "scored_chunks": [
+    {
+      "id": "chunk_...",
+      "index": 0,
+      "text": "...",
+      "score": 0.92,
+      "document_id": "doc_...",
+      "document_name": "API Docs",
+      "document_metadata": {},
+      "metadata": {}
+    }
+  ]
+}
+```
+
+---
+
+## Partitions
+
+### List partitions
+
+```
+GET /partitions
+```
+
+### Create partition
+
+```
+POST /partitions
+Content-Type: application/json
+
+{ "name": "tenant-42", "description": "optional" }
+```
+
+### Get partition (usage metrics)
+
+```
+GET /partitions/{partition_id}
+```
+
+Returns document count, pages processed/hosted monthly/total.
+
+### Delete partition (and all its documents)
+
+```
+DELETE /partitions/{partition_id}
+```
+
+---
+
+## Webhooks
+
+Register a webhook endpoint to receive document status change events:
+
+```
+POST /webhook_endpoints
+Content-Type: application/json
+
+{ "url": "https://your-server.com/ragie-webhook" }
+```
+
+Ragie sends `document_status_updated` events when documents reach `indexed`, `keyword_indexed`, `ready`, or `failed` states.
+
+---
+
+## Error Codes
+
+| HTTP | Meaning |
+|------|---------|
+| 401 | Invalid or missing API key |
+| 402 | Usage limit exceeded |
+| 404 | Document / partition not found |
+| 422 | Validation error — response body has `detail` array |
+| 429 | Rate limited — retry with exponential back-off |
+| 5xx | Server error — retry |
+
+---
+
+## SDK Install & Auth
+
+### TypeScript / Node
+
+```bash
+npm install ragie
+```
+
+```typescript
+import { Ragie } from "ragie";
+const client = new Ragie({ auth: process.env.RAGIE_API_KEY });
+```
+
+### Python
+
+```bash
+pip install ragie
+```
+
+```python
+from ragie import Ragie
+client = Ragie(auth=os.environ["RAGIE_API_KEY"])
+```
+
+All SDK methods mirror the REST endpoints and return typed response objects. The SDKs handle pagination, retries, and multipart uploads automatically.
+
+Note: The TypeScript SDK uses camelCase (`createDocumentFromUrl`, `topK`, `scoredChunks`, `patchMetadata`). The REST API and Python SDK use snake_case (`create_document_from_url`, `top_k`, `scored_chunks`, `patch_metadata`).

package/skills/ragie/references/ingestion.md

@@ -0,0 +1,127 @@
+# Ragie Document Ingestion
+
+> Python user? See `references/python.md` for Python equivalents.
+
+## Ingestion Methods
+
+| Method | SDK call | Use when |
+|--------|----------|----------|
+| File upload | `documents.create()` | Uploading files — supports all file types (PDF, DOCX, PPTX, images, …) |
+| In-memory data | `documents.createRaw()` | Creating documents from in-memory text or JSON (scraped content, generated text, structured data) |
+| URL | `documents.createDocumentFromUrl()` | Web pages, public S3/GCS links |
+
+**Prefer `documents.create()`** when uploading files, as it supports all file types including binary formats. **Prefer `createRaw()`** when your data is already in memory as a string or object — it is simpler and avoids unnecessary file/Blob wrapping, but only handles text and JSON.
+
+## From a File
+
+Use `documents.create()` with a `Blob`. This is the only method that supports all file types including binary formats (PDF, DOCX, images, etc.).
+
+```typescript
+import { openAsBlob } from "fs";
+
+const doc = await client.documents.create({
+  file: await openAsBlob("doc.pdf"),
+  name: "doc.pdf",
+  partition: "tenant-42", // optional
+  metadata: { type: "report", year: "2024" }, // optional
+});
+```
+
+## From In-Memory Data (Raw Text or JSON)
+
+**This is the preferred method when your data is already in memory** (e.g., scraped content, generated text, API responses). It accepts strings and plain objects — not binary data.
+
+```typescript
+const doc = await client.documents.createRaw({
+  data: "Your text content here...",  // string or plain object (not binary)
+  name: "my-note",
+  partition: "tenant-42", // optional
+});
+```
+
+## From a URL
+
+```typescript
+const doc = await client.documents.createDocumentFromUrl({
+  url: "https://example.com/report.pdf",
+  name: "Q4 Report",              // optional display name
+  partition: "tenant-42",         // optional partition
+  metadata: { type: "report", year: "2024" }, // optional
+});
+```
+
+## Document Lifecycle
+
+Documents are processed asynchronously through several stages:
+
+`pending` → `partitioning` → `partitioned` → `refined` → `chunked` → `indexed` → `summary_indexed` → `keyword_indexed` → `ready` (or `failed`)
+
+For polling, check `status === "ready"` or `status === "failed"`. Intermediate stages are informational.
+
+### Polling for Readiness
+
+```typescript
+async function waitForReady(
+  client: Ragie,
+  docId: string,
+  timeoutMs = 120_000
+): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const doc = await client.documents.get({ documentId: docId });
+    if (doc.status === "ready") return;
+    if (doc.status === "failed") throw new Error(`Document ${docId} failed`);
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  throw new Error(`Document ${docId} not ready after ${timeoutMs}ms`);
+}
+
+const doc = await client.documents.createDocumentFromUrl({ url });
+await waitForReady(client, doc.id);
+// now safe to retrieve
+```
+
+### Webhooks
+
+Ragie can POST to your server when a document's status changes. Register a webhook endpoint via the Ragie dashboard or `POST /webhook_endpoints`. Ragie sends `document_status_updated` events when documents reach `indexed`, `keyword_indexed`, `ready`, or `failed` states.
+
+Use polling during local development; register a webhook endpoint for production.
+
+## Bulk Ingestion
+
+```typescript
+const docs = await Promise.all(
+  urls.map((url) =>
+    client.documents.createDocumentFromUrl({ url, partition: "my-partition" })
+  )
+);
+```
+
+## Document Management
+
+```typescript
+// Get a document
+const doc = await client.documents.get({ documentId: docId });
+
+// List documents (returns a PageIterator — async iterable)
+for await (const page of client.documents.list({ partition: "tenant-42", pageSize: 50 })) {
+  for (const doc of page.result.documents) {
+    console.log(doc.id, doc.name, doc.status);
+  }
+}
+
+// Update metadata (partial update — keys set to null are deleted)
+await client.documents.patchMetadata({
+  documentId: docId,
+  patchDocumentMetadataParams: { metadata: { reviewed: "true", version: "v4" } },
+});
+
+// Delete a document
+await client.documents.delete({ documentId: docId });
+```
+
+## Gotchas
+
+- Always check `status === "ready"` before querying — newly ingested documents are not immediately searchable.
+- **Prefer `createRaw()` for in-memory data** — it's simpler when you already have a string or object. **Prefer `documents.create()` for file uploads** — it supports all file types. `createRaw()` only handles text and JSON (`data: string | object`); binary files (PDF, DOCX, etc.) must use `documents.create({ file: blob })`.
+- Supported file types include PDF, DOCX, PPTX, TXT, MD, HTML, and more. Check the dashboard for the full list.