{
  "schemaVersion": "1.0",
  "item": {
    "slug": "ragora",
    "name": "ragora",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/mregmi/ragora",
    "canonicalUrl": "https://clawhub.ai/mregmi/ragora",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/ragora",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ragora",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/ragora"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/ragora",
    "agentPageUrl": "https://openagent3.xyz/skills/ragora/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ragora/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ragora/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Ragora Skill for OpenClaw",
        "body": "Use this skill to answer questions with Ragora data. You have two integration paths:\n\nMCP (Model Context Protocol) — preferred when your client supports MCP tool binding.\nREST API — use directly via HTTP when MCP is unavailable or when you need fine-grained control.\n\nBoth paths share the same authentication, data model, and search capabilities."
      },
      {
        "title": "Source of Truth Docs",
        "body": "Consult these docs first when behavior differs across environments:\n\nMCP guide: https://ragora.app/docs?section=mcp-guide\nGetting started: https://ragora.app/docs?section=getting-started\nAPI overview: https://ragora.app/docs?section=api-overview\nRetrieve API: https://ragora.app/docs?section=api-retrieve\nErrors and limits: https://ragora.app/docs?section=api-errors\nBilling API: https://ragora.app/docs?section=api-billing"
      },
      {
        "title": "Core Concepts",
        "body": "Before using any tools, understand the Ragora data model."
      },
      {
        "title": "Collections",
        "body": "A collection is a knowledge base — a curated set of documents indexed for semantic search. Each collection has:\n\nName — human-readable label (e.g., \"Employee Handbook\").\nSlug — URL-safe identifier used in dynamic tools and API paths (e.g., employee_handbook).\nDescription — what the collection contains and when to use it.\nStats — document count, chunk count, last updated timestamp."
      },
      {
        "title": "Documents & Chunks",
        "body": "Each collection contains documents (files, pages, articles). Documents are split into chunks — small passages optimized for semantic retrieval. When you search, results are returned at the chunk level with metadata pointing back to the source document."
      },
      {
        "title": "Versions",
        "body": "Some collections support versioned documentation (e.g., API docs v1.0, v2.0). Use list_versions_{slug}() or the API to discover available versions, then pass a version parameter to scope your search."
      },
      {
        "title": "Tags & Filters",
        "body": "Collections may support:\n\nCustom tags — string labels attached to documents (e.g., [\"legal\", \"msa\", \"2024\"]). Pass as custom_tags to narrow results.\nFilters — key-value metadata filters (e.g., {\"region\": \"US\", \"department\": \"engineering\"}). Pass as filters to constrain results."
      },
      {
        "title": "Credits & Billing",
        "body": "Own collections and subscriptions — free MCP/API access, no credit cost.\nMarketplace products (pay-per-use) — each retrieval deducts credits based on seller pricing.\nCredits are measured in USD. Check with check_balance() or GET /v1/billing/balance.\nTop up at https://app.ragora.app/settings/billing."
      },
      {
        "title": "Authentication",
        "body": "All requests (MCP and REST) require a Ragora API key.\n\nFormat: sk_live_<uuid> (e.g., sk_live_a1b2c3d4-e5f6-7890-abcd-ef1234567890)\nCreate one: https://app.ragora.app/settings/api-keys\nShown once — copy and store it securely at creation time.\nHashed on server — SHA-256 + bcrypt. Ragora cannot recover a lost key; generate a new one."
      },
      {
        "title": "Security rules",
        "body": "Never pass API keys in URL query parameters.\nNever print full API keys in logs, outputs, or final answers.\nIf the key is missing or invalid, stop and ask the user for a valid key.\nMask keys in any debug output: sk_live_****...."
      },
      {
        "title": "MCP endpoint",
        "body": "URL: https://mcp.ragora.app/mcp\nAuth header: Authorization: Bearer <RAGORA_API_KEY>\n\nOpenClaw config (YAML):\n\nname: ragora\ntype: http\nurl: https://mcp.ragora.app/mcp\nheaders:\n  Authorization: Bearer ${RAGORA_API_KEY}\n\nClaude Desktop / Cursor / VS Code config (JSON):\n\n{\n  \"mcpServers\": {\n    \"ragora\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.ragora.app/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${RAGORA_API_KEY}\"\n      }\n    }\n  }\n}\n\nSecurity note: Set RAGORA_API_KEY as an environment variable in your OS or secret manager. Never hardcode the raw sk_live_* value in config files that may be committed to version control."
      },
      {
        "title": "REST API base URL",
        "body": "Base: https://api.ragora.app/v1\nAuth header: Authorization: Bearer <RAGORA_API_KEY>\nContent-Type: application/json for all POST/PUT requests."
      },
      {
        "title": "Via MCP",
        "body": "Confirm server health:\n\ncurl -s https://mcp.ragora.app/health\n\nCall discover_collections(). If it returns collections, you're connected.\n\n\nIf empty — user may need to access a knowledge base: https://ragora.app/marketplace\n\n\nIf credits are low — call check_balance() and tell user to top up at https://app.ragora.app/settings/billing."
      },
      {
        "title": "Via REST API",
        "body": "Confirm server health:\n\ncurl -s https://api.ragora.app/v1/health\n\nList collections:\n\ncurl https://api.ragora.app/v1/collections \\\n  -H \"Authorization: Bearer <RAGORA_API_KEY>\"\n\nIf the response is 401 or 403, the API key is invalid or expired. Ask the user to generate a new one."
      },
      {
        "title": "Operating Rules",
        "body": "Start with discover_collections() (MCP) or GET /v1/collections (API) before targeted retrieval, unless the user explicitly names a known collection.\nPrefer targeted collection search over global search once you know the likely collections.\nUse global search for broad exploration only — ambiguity, unknown source, or discovery pass.\nKeep retrieval iterative: run multiple focused queries instead of one long query.\nInclude source attribution from returned results in final answers.\nCall out uncertainty when evidence is partial, conflicting, or missing.\nIf credits are low or errors mention billing limits, check balance and report constraints.\nChoose MCP tools when available; fall back to REST API when MCP binding fails or when you need features not exposed via MCP (e.g., pagination, collection metadata)."
      },
      {
        "title": "Static tools (always available)",
        "body": "ToolParametersDescriptiondiscover_collections()noneList all accessible knowledge bases with descriptions, stats, available operations, and usage examples.search(query, top_k?)query (required), top_k (1-20, default 5)Search across ALL accessible collections at once.search_collection(collection_name, query, top_k?, custom_tags?, filters?)collection_name (required), query (required), top_k (1-20, default 5), custom_tags (list of strings), filters (object)Search a specific collection by name or slug.check_balance()noneCredits remaining and estimated USD value."
      },
      {
        "title": "Dynamic tools (per-collection, returned in manifest)",
        "body": "The Gateway generates these tools for each collection you have access to. The {slug} is the collection's URL-safe name (e.g., employee_handbook, k8s_troubleshooting).\n\nToolParametersDescriptionsearch_{slug}(query, top_k?, version?, custom_tags?, filters?)query (required), top_k (1-20, default 5), version (optional string), custom_tags (list of strings), filters (object)Semantic search within the collection.get_topic_{slug}(topic)topic (required string)Retrieve information about a specific topic from the collection.list_versions_{slug}()noneList all available documentation versions for the collection."
      },
      {
        "title": "MCP Resources",
        "body": "URIDescriptionragora://collectionsLists all accessible collections with metadata, stats, and available operations."
      },
      {
        "title": "MCP Prompts",
        "body": "PromptParametersDescriptionsearch_collection_promptcollection_name, queryPre-built prompt for searching a specific collection.summarize_collectioncollection_namePre-built prompt for summarizing an entire collection.compare_sourcescollection_names, questionPre-built prompt for comparing information across multiple collections."
      },
      {
        "title": "REST API Reference",
        "body": "Use these endpoints when MCP tool binding is unavailable, or when you need direct HTTP control.\n\nAll endpoints require: Authorization: Bearer <RAGORA_API_KEY>"
      },
      {
        "title": "Health check",
        "body": "GET https://api.ragora.app/v1/health\n\nResponse: 200 OK with {\"status\": \"ok\"} if the service is up."
      },
      {
        "title": "List collections",
        "body": "GET https://api.ragora.app/v1/collections\n\nReturns all collections accessible to the authenticated user.\n\nResponse:\n\n{\n  \"collections\": [\n    {\n      \"name\": \"Employee Handbook\",\n      \"slug\": \"employee_handbook\",\n      \"description\": \"Company policies, benefits, and procedures\",\n      \"stats\": {\n        \"document_count\": 45,\n        \"chunk_count\": 1230,\n        \"last_updated\": \"2025-11-15T08:30:00Z\"\n      },\n      \"supported_features\": [\"search\", \"get_topic\", \"versions\", \"filters\"]\n    }\n  ]\n}"
      },
      {
        "title": "Search across all collections",
        "body": "POST https://api.ragora.app/v1/search\n\nRequest:\n\n{\n  \"query\": \"vacation policy for remote employees\",\n  \"top_k\": 5\n}\n\nResponse:\n\n{\n  \"results\": [\n    {\n      \"content\": \"Remote employees are entitled to 20 days of paid vacation per year...\",\n      \"score\": 0.94,\n      \"source\": {\n        \"collection\": \"employee_handbook\",\n        \"document\": \"benefits-guide.md\",\n        \"chunk_id\": \"ch_abc123\"\n      },\n      \"metadata\": {}\n    }\n  ],\n  \"usage\": {\n    \"cost_usd\": 0.0,\n    \"balance_remaining_usd\": 99.95\n  }\n}"
      },
      {
        "title": "Search a specific collection",
        "body": "POST https://api.ragora.app/v1/collections/{slug}/search\n\nRequest:\n\n{\n  \"query\": \"log retention duration and deletion policy\",\n  \"top_k\": 5,\n  \"version\": \"2.0\",\n  \"custom_tags\": [\"compliance\", \"soc2\"],\n  \"filters\": {\n    \"region\": \"US\"\n  }\n}\n\nResponse: same structure as global search, but scoped to the named collection."
      },
      {
        "title": "Get topic from a collection",
        "body": "POST https://api.ragora.app/v1/collections/{slug}/topic\n\nRequest:\n\n{\n  \"topic\": \"remote work policy\"\n}\n\nResponse:\n\n{\n  \"content\": \"Detailed information about the remote work policy...\",\n  \"source\": {\n    \"collection\": \"employee_handbook\",\n    \"document\": \"remote-work.md\"\n  },\n  \"usage\": {\n    \"cost_usd\": 0.0,\n    \"balance_remaining_usd\": 99.95\n  }\n}"
      },
      {
        "title": "List versions for a collection",
        "body": "GET https://api.ragora.app/v1/collections/{slug}/versions\n\nResponse:\n\n{\n  \"versions\": [\n    {\"version\": \"2.0\", \"label\": \"v2.0 (latest)\", \"is_default\": true},\n    {\"version\": \"1.5\", \"label\": \"v1.5\", \"is_default\": false},\n    {\"version\": \"1.0\", \"label\": \"v1.0 (legacy)\", \"is_default\": false}\n  ]\n}"
      },
      {
        "title": "Check balance",
        "body": "GET https://api.ragora.app/v1/billing/balance\n\nResponse:\n\n{\n  \"credits_remaining\": 9950,\n  \"estimated_usd\": 99.50,\n  \"currency\": \"USD\"\n}"
      },
      {
        "title": "MCP Gateway endpoints (tool proxy)",
        "body": "If you need to call MCP tools via REST (e.g., dynamic tools like search_employee_handbook):\n\nGet manifest — lists all available MCP tools for your account:\n\nGET https://api.ragora.app/v1/mcp/manifest\n\nExecute a tool — call any MCP tool by name:\n\nPOST https://api.ragora.app/v1/mcp/execute\n\nRequest:\n\n{\n  \"tool\": \"search_employee_handbook\",\n  \"arguments\": {\n    \"query\": \"vacation policy\",\n    \"top_k\": 5\n  }\n}\n\nResponse:\n\n{\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"text\": \"Found 5 results:\\n\\n1. **Vacation Policy** (score: 0.95)\\n   Remote employees are entitled to...\\n   Source: benefits-guide.md\"\n    }\n  ],\n  \"usage\": {\n    \"cost_usd\": 0.0,\n    \"balance_remaining_usd\": 99.95\n  }\n}"
      },
      {
        "title": "HTTP status codes",
        "body": "StatusMeaningAgent action200SuccessProcess results normally.400Bad request — malformed query, missing required paramCheck request format. Fix the query and retry.401Unauthorized — missing or invalid API keyStop. Ask the user to provide a valid sk_live_ key.403Forbidden — key is valid but lacks access to this collectionInform user they need to purchase/subscribe to this collection at the marketplace.404Not found — collection slug or endpoint doesn't existCheck the slug with discover_collections() or GET /v1/collections.422Validation error — params are present but invalid (e.g., top_k=50)Read the error message, fix the parameter, and retry.429Rate limited — too many requestsWait and retry with exponential backoff (see Rate Limiting below).402Payment required — insufficient creditsCall check_balance(). Tell user to top up at billing page.500Server errorRetry once after 2 seconds. If it persists, inform user of a temporary service issue.503Service unavailableRetry once after 5 seconds. If it persists, inform user."
      },
      {
        "title": "Error response format",
        "body": "{\n  \"error\": {\n    \"code\": \"insufficient_credits\",\n    \"message\": \"Your balance is too low to complete this search. Current balance: $0.05.\",\n    \"details\": {}\n  }\n}"
      },
      {
        "title": "Common error codes in response body",
        "body": "CodeDescriptionAgent actioninvalid_api_keyKey format wrong or key revokedAsk user for a new key.expired_api_keyKey has expiredAsk user to generate a new key at dashboard.insufficient_creditsNot enough credits for this retrievalReport balance and link to billing.collection_not_foundSlug doesn't match any collectionRe-run discovery, check spelling.collection_access_deniedUser hasn't purchased accessLink user to the marketplace.rate_limit_exceededToo many requests in windowBack off and retry.invalid_queryQuery is empty or too longFix and retry with a shorter, clearer query.version_not_foundRequested version doesn't existCall list_versions_{slug}() to see valid versions."
      },
      {
        "title": "Limits",
        "body": "MCP tools: 60 calls per minute per API key.\nREST API: 120 requests per minute per API key.\nRate limit headers are returned on every response:\n\nX-RateLimit-Limit — max requests in the window.\nX-RateLimit-Remaining — requests left in the current window.\nX-RateLimit-Reset — Unix timestamp when the window resets."
      },
      {
        "title": "Retry strategy",
        "body": "When you receive a 429 response:\n\nRead the Retry-After header (seconds to wait) if present.\nIf no Retry-After, use exponential backoff: wait 1s, then 2s, then 4s.\nMaximum 3 retries before giving up and informing the user.\nNever retry 401 or 403 — these require user action, not waiting."
      },
      {
        "title": "Best practices to avoid rate limits",
        "body": "Batch your queries logically: 3-5 focused queries per task, not 20 rapid-fire calls.\nUse top_k=10-15 instead of making multiple top_k=3 calls for the same question.\nCache discover_collections() results within a session — collection lists rarely change mid-conversation."
      },
      {
        "title": "Authentication Troubleshooting",
        "body": "SymptomLikely causeFix401 Unauthorized on every callMissing or malformed Authorization headerEnsure header is exactly Authorization: Bearer sk_live_xxxxx. No extra spaces, no quotes around the token.401 but key looks correctKey was revoked or regeneratedAsk user to check active keys at https://app.ragora.app/settings/api-keys.401 with invalid_api_key codeKey format is wrong (e.g., missing sk_live_ prefix)Verify format: must start with sk_live_ followed by a UUID.401 with expired_api_key codeKey has an expiration and it passedGenerate a new key from the dashboard.403 ForbiddenKey is valid but doesn't have access to the requested collectionUser needs to purchase or subscribe to the collection.MCP tools not appearingMCP server not configured or wrong URLVerify MCP URL is https://mcp.ragora.app/mcp and header is set. Run health check.MCP tools appear but return errorsKey in MCP config is a placeholderReplace sk_live_xxx with the actual key.ECONNREFUSED or timeoutNetwork issue or service outageCheck https://mcp.ragora.app/health. If down, fall back to REST API or wait."
      },
      {
        "title": "1. Understand intent",
        "body": "Classify request type: factual lookup, summary, comparison, extraction, or verification.\nIdentify likely domains/collections from user wording."
      },
      {
        "title": "2. Discover scope",
        "body": "Run discover_collections() (MCP) or GET /v1/collections (API).\nSelect 1-3 collections most relevant to the question.\nIf no relevant collection exists, state that explicitly and stop."
      },
      {
        "title": "3. Retrieve evidence",
        "body": "First pass: one targeted query per selected collection.\nSecond pass: refine with specific sub-queries (dates, entities, claims, thresholds).\nTune top_k based on task:\n\ntop_k=3-5 for direct factual questions.\ntop_k=8-12 for comparisons or comprehensive summaries.\ntop_k=15-20 for exhaustive research or due diligence."
      },
      {
        "title": "4. Synthesize",
        "body": "Merge evidence by claim, not by source order.\nResolve conflicts by preferring direct passages and recency cues in content.\nDistinguish facts from inferences."
      },
      {
        "title": "5. Respond",
        "body": "Give a concise answer first.\nThen provide evidence bullets with collection/source references.\nEnd with gaps, caveats, or suggested follow-up queries when confidence is not high."
      },
      {
        "title": "Research a topic across multiple collections",
        "body": "Scenario: User asks \"What is our data retention policy and how does it compare to SOC 2 requirements?\"\n\ndiscover_collections() → find security_handbook, compliance_docs, soc2_guide\nsearch_collection(\"security_handbook\", \"data retention policy duration\", top_k=5)\nsearch_collection(\"compliance_docs\", \"SOC 2 data retention requirements\", top_k=5)\nsearch_collection(\"soc2_guide\", \"retention controls audit evidence\", top_k=5)\nSynthesize: compare internal policy against SOC 2 requirements, note gaps.\nRespond with findings, citing each collection."
      },
      {
        "title": "Compare two vendor contracts",
        "body": "Scenario: User asks \"Compare the SLA terms between Vendor A and Vendor B.\"\n\ndiscover_collections() → find vendor_a_contract, vendor_b_contract\nsearch_collection(\"vendor_a_contract\", \"SLA uptime guarantees penalties\", top_k=8)\nsearch_collection(\"vendor_b_contract\", \"SLA uptime guarantees penalties\", top_k=8)\nSecond pass for specifics:\n\nsearch_collection(\"vendor_a_contract\", \"termination notice period remedies\", top_k=5)\nsearch_collection(\"vendor_b_contract\", \"termination notice period remedies\", top_k=5)\n\n\nBuild comparison table: uptime %, penalty structure, notice periods, exclusions.\nHighlight key differences and risks."
      },
      {
        "title": "Due diligence deep dive",
        "body": "Scenario: User asks \"Summarize everything we know about Company X's security posture.\"\n\nsearch(\"Company X security audit penetration test vulnerability\", top_k=15) — broad discovery pass.\nIdentify which collections returned results (e.g., due_diligence_reports, vendor_assessments).\nTargeted follow-up:\n\nsearch_collection(\"due_diligence_reports\", \"Company X SOC 2 ISO 27001 certifications\", top_k=10)\nsearch_collection(\"vendor_assessments\", \"Company X data encryption access controls\", top_k=10)\nsearch_collection(\"due_diligence_reports\", \"Company X incident history breach\", top_k=5)\n\n\nOrganize findings by category: certifications, technical controls, incident history, gaps.\nPresent with confidence levels and note areas with no data."
      },
      {
        "title": "Versioned documentation lookup",
        "body": "Scenario: User asks \"What changed in the authentication flow between API v1 and v2?\"\n\nlist_versions_api_docs() → returns [\"1.0\", \"2.0\"]\nsearch_api_docs(query=\"authentication flow token exchange\", version=\"1.0\", top_k=5)\nsearch_api_docs(query=\"authentication flow token exchange\", version=\"2.0\", top_k=5)\nDiff the results: what was added, changed, or removed.\nPresent a clear changelog-style summary."
      },
      {
        "title": "REST API workflow (no MCP)",
        "body": "Scenario: MCP binding is unavailable. User asks \"Find our vacation policy.\"\n\nHealth check:\n\ncurl -s https://api.ragora.app/v1/health\n\nList collections:\n\ncurl https://api.ragora.app/v1/collections \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\"\n\nSearch the relevant collection:\n\ncurl -X POST https://api.ragora.app/v1/collections/employee_handbook/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"vacation policy paid time off\", \"top_k\": 5}'\n\nParse the results array, extract content and source fields, and compose the answer."
      },
      {
        "title": "Query Patterns",
        "body": "Use short, specific queries. Prefer multiple passes over one monolithic query."
      },
      {
        "title": "By task type",
        "body": "TaskQuery patternExampleFactual lookup\"<entity> <metric/attribute> <time period>\"\"ACME Corp revenue 2024 Q3\"Policy/requirements\"<policy type> eligibility criteria exceptions\"\"parental leave eligibility criteria exceptions\"ComparisonRun same query across each collection\"pricing limits SLA exclusions\" × 2 collectionsValidationFirst \"<claim>\", then \"counterexample exception to <claim>\"\"all employees get 20 vacation days\" then \"exceptions to vacation day policy\"Extraction\"<entity> <specific data point>\"\"ACME Corp CEO contact information\"Timeline\"<entity> <event type> chronological\"\"product launches timeline 2023 2024\""
      },
      {
        "title": "Query refinement strategy",
        "body": "Start broad: \"data retention policy\" — see what's available.\nNarrow by entity: \"customer data retention policy\" — scope to a specific domain.\nNarrow by attribute: \"customer data retention duration deletion schedule\" — get specifics.\nAdd constraints: Use filters and custom_tags if results are noisy."
      },
      {
        "title": "Discover collections",
        "body": "MCP:\n\ndiscover_collections()\n\nAPI:\n\ncurl https://api.ragora.app/v1/collections \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\""
      },
      {
        "title": "Broad search when unsure",
        "body": "MCP:\n\nsearch(query=\"SOC 2 retention policy for customer logs\", top_k=8)\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SOC 2 retention policy for customer logs\", \"top_k\": 8}'"
      },
      {
        "title": "Targeted collection search",
        "body": "MCP:\n\nsearch_collection(\n  collection_name=\"security-handbook\",\n  query=\"log retention duration and deletion policy\",\n  top_k=5\n)\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/collections/security_handbook/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"log retention duration and deletion policy\", \"top_k\": 5}'"
      },
      {
        "title": "Search with version",
        "body": "MCP:\n\nsearch_api_docs(\n  query=\"authentication flow changes\",\n  version=\"2.0\",\n  top_k=5\n)\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/collections/api_docs/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"authentication flow changes\", \"version\": \"2.0\", \"top_k\": 5}'"
      },
      {
        "title": "Get topic from a collection",
        "body": "MCP:\n\nget_topic_employee_handbook(topic=\"remote work policy\")\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/collections/employee_handbook/topic \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"topic\": \"remote work policy\"}'"
      },
      {
        "title": "Filtered search",
        "body": "MCP:\n\nsearch_collection(\n  collection_name=\"contracts\",\n  query=\"termination for convenience notice period\",\n  top_k=10,\n  custom_tags=[\"msa\", \"legal\"],\n  filters={\"region\": \"US\"}\n)\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/collections/contracts/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"termination for convenience notice period\", \"top_k\": 10, \"custom_tags\": [\"msa\", \"legal\"], \"filters\": {\"region\": \"US\"}}'"
      },
      {
        "title": "Credit check",
        "body": "MCP:\n\ncheck_balance()\n\nAPI:\n\ncurl https://api.ragora.app/v1/billing/balance \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\""
      },
      {
        "title": "Compare across collections",
        "body": "MCP prompt:\n\ncompare_sources(\n  collection_names=[\"vendor-a-docs\", \"vendor-b-docs\"],\n  question=\"What are the SLA differences?\"\n)\n\nAPI (manual — run two searches and compare):\n\n# Search vendor A\ncurl -X POST https://api.ragora.app/v1/collections/vendor_a_docs/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SLA uptime guarantees penalties\", \"top_k\": 8}'\n\n# Search vendor B\ncurl -X POST https://api.ragora.app/v1/collections/vendor_b_docs/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SLA uptime guarantees penalties\", \"top_k\": 8}'"
      },
      {
        "title": "Choosing top_k",
        "body": "ScenarioRecommended top_kRationaleSimple factual question3-5Few precise results keep context small.Multi-facet question5-8Need coverage across sub-topics.Comparison across collections8-12 per collectionNeed enough evidence from each side.Exhaustive research / due diligence15-20Comprehensive coverage at the cost of more context.Quick validation of a claim2-3Just need to confirm or deny."
      },
      {
        "title": "Managing context window size",
        "body": "Prefer targeted searches over global searches. search_collection() returns fewer, more relevant results than search().\nSummarize as you go. After retrieving results, extract the key facts before moving to the next query. Don't accumulate raw results.\nUse multi-pass retrieval. First pass: broad query with top_k=5. Read results. Second pass: specific follow-up queries targeting gaps.\nDrop low-relevance results. If a result has a low relevance score or doesn't relate to the question, ignore it.\nDon't retrieve what you already know. If a previous query already answered part of the question, don't re-query for it."
      },
      {
        "title": "When results are too large",
        "body": "If a single query returns more text than is useful:\n\nReduce top_k to 3.\nAdd custom_tags or filters to narrow scope.\nUse a more specific query instead of a broad one.\nFocus on the highest-scoring results and discard the rest."
      },
      {
        "title": "When results are insufficient",
        "body": "If a query returns no results or irrelevant results:\n\nBroaden the query: remove specific terms, use synonyms.\nTry global search() instead of collection-specific.\nCheck if the collection exists with discover_collections().\nTry a different collection if multiple are available.\nIf still empty, tell the user that no relevant data was found."
      },
      {
        "title": "Standard response structure",
        "body": "**Answer**: <2-6 sentence direct answer>\n\n**Evidence**:\n- <claim> — *<collection_name> / <source_document>*\n- <claim> — *<collection_name> / <source_document>*\n- <claim> — *<collection_name> / <source_document>*\n\n**Caveats**:\n- <what is missing, uncertain, or conflicting>\n\n**Suggested follow-ups** (if applicable):\n- <exact query the user could ask next>"
      },
      {
        "title": "Source citation rules",
        "body": "Always cite the collection name and source document for every claim.\nFormat: — *Collection Name / document-name.md*\nIf multiple results support the same claim, cite the highest-scoring one.\nIf results conflict, cite both and note the conflict."
      },
      {
        "title": "Confidence indicators",
        "body": "High confidence: multiple results agree, high relevance scores (>0.85), from authoritative collections.\nMedium confidence: single result or moderate scores (0.6-0.85). Note: \"Based on a single source.\"\nLow confidence: low scores (<0.6), tangential results, or inferred conclusions. Note: \"This is inferred and may need verification.\""
      },
      {
        "title": "Comparison format",
        "body": "When comparing across collections, use a table:\n\n| Aspect | Vendor A | Vendor B |\n|--------|----------|----------|\n| Uptime SLA | 99.9% | 99.95% |\n| Penalty | 5% credit per hour | 10% credit per hour |\n| Notice period | 30 days | 60 days |\n\n*Sources: vendor_a_contract/sla.md, vendor_b_contract/sla.md*"
      },
      {
        "title": "Failure Handling",
        "body": "FailureAgent actionNo resultsBroaden wording, remove overly specific constraints, retry with search(). If still empty, inform user.Too many noisy resultsConstrain by collection, add custom_tags/filters, use narrower entity/date terms.Conflicting evidencePresent both sides, note the conflict, cite both sources, and propose a follow-up query to resolve.Access denied (403)Explain that collection access may need to be purchased. Link to marketplace.Credit errors (402)Run check_balance(), report the balance, and link to billing page.Rate limited (429)Wait per Retry-After header or use exponential backoff. Max 3 retries.Server error (500/503)Retry once after 2-5 seconds. If it persists, inform user of a temporary issue.MCP connection failureFall back to REST API endpoints. Inform user of the switch.TimeoutReduce top_k, simplify the query, and retry.Invalid collection slugRe-run discover_collections() and check available slugs."
      },
      {
        "title": "Quality Bar",
        "body": "Never fabricate unseen facts — all claims must come from retrieved evidence.\nAlways ground claims in retrieved evidence with source citations.\nPrefer precise wording over broad generalization.\nKeep final responses concise, decision-oriented, and source-backed.\nDistinguish between directly stated facts and inferred conclusions.\nWhen evidence is incomplete, explicitly state what is missing rather than guessing.\nIf a question cannot be answered from available collections, say so directly."
      }
    ],
    "body": "Ragora Skill for OpenClaw\n\nUse this skill to answer questions with Ragora data. You have two integration paths:\n\nMCP (Model Context Protocol) — preferred when your client supports MCP tool binding.\nREST API — use directly via HTTP when MCP is unavailable or when you need fine-grained control.\n\nBoth paths share the same authentication, data model, and search capabilities.\n\nSource of Truth Docs\n\nConsult these docs first when behavior differs across environments:\n\nMCP guide: https://ragora.app/docs?section=mcp-guide\nGetting started: https://ragora.app/docs?section=getting-started\nAPI overview: https://ragora.app/docs?section=api-overview\nRetrieve API: https://ragora.app/docs?section=api-retrieve\nErrors and limits: https://ragora.app/docs?section=api-errors\nBilling API: https://ragora.app/docs?section=api-billing\nCore Concepts\n\nBefore using any tools, understand the Ragora data model.\n\nCollections\n\nA collection is a knowledge base — a curated set of documents indexed for semantic search. Each collection has:\n\nName — human-readable label (e.g., \"Employee Handbook\").\nSlug — URL-safe identifier used in dynamic tools and API paths (e.g., employee_handbook).\nDescription — what the collection contains and when to use it.\nStats — document count, chunk count, last updated timestamp.\nDocuments & Chunks\n\nEach collection contains documents (files, pages, articles). Documents are split into chunks — small passages optimized for semantic retrieval. When you search, results are returned at the chunk level with metadata pointing back to the source document.\n\nVersions\n\nSome collections support versioned documentation (e.g., API docs v1.0, v2.0). Use list_versions_{slug}() or the API to discover available versions, then pass a version parameter to scope your search.\n\nTags & Filters\n\nCollections may support:\n\nCustom tags — string labels attached to documents (e.g., [\"legal\", \"msa\", \"2024\"]). Pass as custom_tags to narrow results.\nFilters — key-value metadata filters (e.g., {\"region\": \"US\", \"department\": \"engineering\"}). Pass as filters to constrain results.\nCredits & Billing\nOwn collections and subscriptions — free MCP/API access, no credit cost.\nMarketplace products (pay-per-use) — each retrieval deducts credits based on seller pricing.\nCredits are measured in USD. Check with check_balance() or GET /v1/billing/balance.\nTop up at https://app.ragora.app/settings/billing.\nConnection Setup\nAuthentication\n\nAll requests (MCP and REST) require a Ragora API key.\n\nFormat: sk_live_<uuid> (e.g., sk_live_a1b2c3d4-e5f6-7890-abcd-ef1234567890)\nCreate one: https://app.ragora.app/settings/api-keys\nShown once — copy and store it securely at creation time.\nHashed on server — SHA-256 + bcrypt. Ragora cannot recover a lost key; generate a new one.\nSecurity rules\nNever pass API keys in URL query parameters.\nNever print full API keys in logs, outputs, or final answers.\nIf the key is missing or invalid, stop and ask the user for a valid key.\nMask keys in any debug output: sk_live_****....\nMCP endpoint\nURL: https://mcp.ragora.app/mcp\nAuth header: Authorization: Bearer <RAGORA_API_KEY>\n\nOpenClaw config (YAML):\n\nname: ragora\ntype: http\nurl: https://mcp.ragora.app/mcp\nheaders:\n  Authorization: Bearer ${RAGORA_API_KEY}\n\n\nClaude Desktop / Cursor / VS Code config (JSON):\n\n{\n  \"mcpServers\": {\n    \"ragora\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.ragora.app/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${RAGORA_API_KEY}\"\n      }\n    }\n  }\n}\n\n\nSecurity note: Set RAGORA_API_KEY as an environment variable in your OS or secret manager. Never hardcode the raw sk_live_* value in config files that may be committed to version control.\n\nREST API base URL\nBase: https://api.ragora.app/v1\nAuth header: Authorization: Bearer <RAGORA_API_KEY>\nContent-Type: application/json for all POST/PUT requests.\nConnectivity Check (Run First)\nVia MCP\nConfirm server health:\ncurl -s https://mcp.ragora.app/health\n\n\nCall discover_collections(). If it returns collections, you're connected.\n\nIf empty — user may need to access a knowledge base: https://ragora.app/marketplace\n\nIf credits are low — call check_balance() and tell user to top up at https://app.ragora.app/settings/billing.\n\nVia REST API\nConfirm server health:\ncurl -s https://api.ragora.app/v1/health\n\nList collections:\ncurl https://api.ragora.app/v1/collections \\\n  -H \"Authorization: Bearer <RAGORA_API_KEY>\"\n\nIf the response is 401 or 403, the API key is invalid or expired. Ask the user to generate a new one.\nOperating Rules\nStart with discover_collections() (MCP) or GET /v1/collections (API) before targeted retrieval, unless the user explicitly names a known collection.\nPrefer targeted collection search over global search once you know the likely collections.\nUse global search for broad exploration only — ambiguity, unknown source, or discovery pass.\nKeep retrieval iterative: run multiple focused queries instead of one long query.\nInclude source attribution from returned results in final answers.\nCall out uncertainty when evidence is partial, conflicting, or missing.\nIf credits are low or errors mention billing limits, check balance and report constraints.\nChoose MCP tools when available; fall back to REST API when MCP binding fails or when you need features not exposed via MCP (e.g., pagination, collection metadata).\nMCP Tools Reference\nStatic tools (always available)\nTool\tParameters\tDescription\ndiscover_collections()\tnone\tList all accessible knowledge bases with descriptions, stats, available operations, and usage examples.\nsearch(query, top_k?)\tquery (required), top_k (1-20, default 5)\tSearch across ALL accessible collections at once.\nsearch_collection(collection_name, query, top_k?, custom_tags?, filters?)\tcollection_name (required), query (required), top_k (1-20, default 5), custom_tags (list of strings), filters (object)\tSearch a specific collection by name or slug.\ncheck_balance()\tnone\tCredits remaining and estimated USD value.\nDynamic tools (per-collection, returned in manifest)\n\nThe Gateway generates these tools for each collection you have access to. The {slug} is the collection's URL-safe name (e.g., employee_handbook, k8s_troubleshooting).\n\nTool\tParameters\tDescription\nsearch_{slug}(query, top_k?, version?, custom_tags?, filters?)\tquery (required), top_k (1-20, default 5), version (optional string), custom_tags (list of strings), filters (object)\tSemantic search within the collection.\nget_topic_{slug}(topic)\ttopic (required string)\tRetrieve information about a specific topic from the collection.\nlist_versions_{slug}()\tnone\tList all available documentation versions for the collection.\nMCP Resources\nURI\tDescription\nragora://collections\tLists all accessible collections with metadata, stats, and available operations.\nMCP Prompts\nPrompt\tParameters\tDescription\nsearch_collection_prompt\tcollection_name, query\tPre-built prompt for searching a specific collection.\nsummarize_collection\tcollection_name\tPre-built prompt for summarizing an entire collection.\ncompare_sources\tcollection_names, question\tPre-built prompt for comparing information across multiple collections.\nREST API Reference\n\nUse these endpoints when MCP tool binding is unavailable, or when you need direct HTTP control.\n\nAll endpoints require: Authorization: Bearer <RAGORA_API_KEY>\n\nHealth check\nGET https://api.ragora.app/v1/health\n\n\nResponse: 200 OK with {\"status\": \"ok\"} if the service is up.\n\nList collections\nGET https://api.ragora.app/v1/collections\n\n\nReturns all collections accessible to the authenticated user.\n\nResponse:\n\n{\n  \"collections\": [\n    {\n      \"name\": \"Employee Handbook\",\n      \"slug\": \"employee_handbook\",\n      \"description\": \"Company policies, benefits, and procedures\",\n      \"stats\": {\n        \"document_count\": 45,\n        \"chunk_count\": 1230,\n        \"last_updated\": \"2025-11-15T08:30:00Z\"\n      },\n      \"supported_features\": [\"search\", \"get_topic\", \"versions\", \"filters\"]\n    }\n  ]\n}\n\nSearch across all collections\nPOST https://api.ragora.app/v1/search\n\n\nRequest:\n\n{\n  \"query\": \"vacation policy for remote employees\",\n  \"top_k\": 5\n}\n\n\nResponse:\n\n{\n  \"results\": [\n    {\n      \"content\": \"Remote employees are entitled to 20 days of paid vacation per year...\",\n      \"score\": 0.94,\n      \"source\": {\n        \"collection\": \"employee_handbook\",\n        \"document\": \"benefits-guide.md\",\n        \"chunk_id\": \"ch_abc123\"\n      },\n      \"metadata\": {}\n    }\n  ],\n  \"usage\": {\n    \"cost_usd\": 0.0,\n    \"balance_remaining_usd\": 99.95\n  }\n}\n\nSearch a specific collection\nPOST https://api.ragora.app/v1/collections/{slug}/search\n\n\nRequest:\n\n{\n  \"query\": \"log retention duration and deletion policy\",\n  \"top_k\": 5,\n  \"version\": \"2.0\",\n  \"custom_tags\": [\"compliance\", \"soc2\"],\n  \"filters\": {\n    \"region\": \"US\"\n  }\n}\n\n\nResponse: same structure as global search, but scoped to the named collection.\n\nGet topic from a collection\nPOST https://api.ragora.app/v1/collections/{slug}/topic\n\n\nRequest:\n\n{\n  \"topic\": \"remote work policy\"\n}\n\n\nResponse:\n\n{\n  \"content\": \"Detailed information about the remote work policy...\",\n  \"source\": {\n    \"collection\": \"employee_handbook\",\n    \"document\": \"remote-work.md\"\n  },\n  \"usage\": {\n    \"cost_usd\": 0.0,\n    \"balance_remaining_usd\": 99.95\n  }\n}\n\nList versions for a collection\nGET https://api.ragora.app/v1/collections/{slug}/versions\n\n\nResponse:\n\n{\n  \"versions\": [\n    {\"version\": \"2.0\", \"label\": \"v2.0 (latest)\", \"is_default\": true},\n    {\"version\": \"1.5\", \"label\": \"v1.5\", \"is_default\": false},\n    {\"version\": \"1.0\", \"label\": \"v1.0 (legacy)\", \"is_default\": false}\n  ]\n}\n\nCheck balance\nGET https://api.ragora.app/v1/billing/balance\n\n\nResponse:\n\n{\n  \"credits_remaining\": 9950,\n  \"estimated_usd\": 99.50,\n  \"currency\": \"USD\"\n}\n\nMCP Gateway endpoints (tool proxy)\n\nIf you need to call MCP tools via REST (e.g., dynamic tools like search_employee_handbook):\n\nGet manifest — lists all available MCP tools for your account:\n\nGET https://api.ragora.app/v1/mcp/manifest\n\n\nExecute a tool — call any MCP tool by name:\n\nPOST https://api.ragora.app/v1/mcp/execute\n\n\nRequest:\n\n{\n  \"tool\": \"search_employee_handbook\",\n  \"arguments\": {\n    \"query\": \"vacation policy\",\n    \"top_k\": 5\n  }\n}\n\n\nResponse:\n\n{\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"text\": \"Found 5 results:\\n\\n1. **Vacation Policy** (score: 0.95)\\n   Remote employees are entitled to...\\n   Source: benefits-guide.md\"\n    }\n  ],\n  \"usage\": {\n    \"cost_usd\": 0.0,\n    \"balance_remaining_usd\": 99.95\n  }\n}\n\nError Codes & Status Handling\nHTTP status codes\nStatus\tMeaning\tAgent action\n200\tSuccess\tProcess results normally.\n400\tBad request — malformed query, missing required param\tCheck request format. Fix the query and retry.\n401\tUnauthorized — missing or invalid API key\tStop. Ask the user to provide a valid sk_live_ key.\n403\tForbidden — key is valid but lacks access to this collection\tInform user they need to purchase/subscribe to this collection at the marketplace.\n404\tNot found — collection slug or endpoint doesn't exist\tCheck the slug with discover_collections() or GET /v1/collections.\n422\tValidation error — params are present but invalid (e.g., top_k=50)\tRead the error message, fix the parameter, and retry.\n429\tRate limited — too many requests\tWait and retry with exponential backoff (see Rate Limiting below).\n402\tPayment required — insufficient credits\tCall check_balance(). Tell user to top up at billing page.\n500\tServer error\tRetry once after 2 seconds. If it persists, inform user of a temporary service issue.\n503\tService unavailable\tRetry once after 5 seconds. If it persists, inform user.\nError response format\n{\n  \"error\": {\n    \"code\": \"insufficient_credits\",\n    \"message\": \"Your balance is too low to complete this search. Current balance: $0.05.\",\n    \"details\": {}\n  }\n}\n\nCommon error codes in response body\nCode\tDescription\tAgent action\ninvalid_api_key\tKey format wrong or key revoked\tAsk user for a new key.\nexpired_api_key\tKey has expired\tAsk user to generate a new key at dashboard.\ninsufficient_credits\tNot enough credits for this retrieval\tReport balance and link to billing.\ncollection_not_found\tSlug doesn't match any collection\tRe-run discovery, check spelling.\ncollection_access_denied\tUser hasn't purchased access\tLink user to the marketplace.\nrate_limit_exceeded\tToo many requests in window\tBack off and retry.\ninvalid_query\tQuery is empty or too long\tFix and retry with a shorter, clearer query.\nversion_not_found\tRequested version doesn't exist\tCall list_versions_{slug}() to see valid versions.\nRate Limiting & Retry Strategy\nLimits\nMCP tools: 60 calls per minute per API key.\nREST API: 120 requests per minute per API key.\nRate limit headers are returned on every response:\nX-RateLimit-Limit — max requests in the window.\nX-RateLimit-Remaining — requests left in the current window.\nX-RateLimit-Reset — Unix timestamp when the window resets.\nRetry strategy\n\nWhen you receive a 429 response:\n\nRead the Retry-After header (seconds to wait) if present.\nIf no Retry-After, use exponential backoff: wait 1s, then 2s, then 4s.\nMaximum 3 retries before giving up and informing the user.\nNever retry 401 or 403 — these require user action, not waiting.\nBest practices to avoid rate limits\nBatch your queries logically: 3-5 focused queries per task, not 20 rapid-fire calls.\nUse top_k=10-15 instead of making multiple top_k=3 calls for the same question.\nCache discover_collections() results within a session — collection lists rarely change mid-conversation.\nAuthentication Troubleshooting\nSymptom\tLikely cause\tFix\n401 Unauthorized on every call\tMissing or malformed Authorization header\tEnsure header is exactly Authorization: Bearer sk_live_xxxxx. No extra spaces, no quotes around the token.\n401 but key looks correct\tKey was revoked or regenerated\tAsk user to check active keys at https://app.ragora.app/settings/api-keys.\n401 with invalid_api_key code\tKey format is wrong (e.g., missing sk_live_ prefix)\tVerify format: must start with sk_live_ followed by a UUID.\n401 with expired_api_key code\tKey has an expiration and it passed\tGenerate a new key from the dashboard.\n403 Forbidden\tKey is valid but doesn't have access to the requested collection\tUser needs to purchase or subscribe to the collection.\nMCP tools not appearing\tMCP server not configured or wrong URL\tVerify MCP URL is https://mcp.ragora.app/mcp and header is set. Run health check.\nMCP tools appear but return errors\tKey in MCP config is a placeholder\tReplace sk_live_xxx with the actual key.\nECONNREFUSED or timeout\tNetwork issue or service outage\tCheck https://mcp.ragora.app/health. If down, fall back to REST API or wait.\nCore Workflow\n1. Understand intent\nClassify request type: factual lookup, summary, comparison, extraction, or verification.\nIdentify likely domains/collections from user wording.\n2. Discover scope\nRun discover_collections() (MCP) or GET /v1/collections (API).\nSelect 1-3 collections most relevant to the question.\nIf no relevant collection exists, state that explicitly and stop.\n3. Retrieve evidence\nFirst pass: one targeted query per selected collection.\nSecond pass: refine with specific sub-queries (dates, entities, claims, thresholds).\nTune top_k based on task:\ntop_k=3-5 for direct factual questions.\ntop_k=8-12 for comparisons or comprehensive summaries.\ntop_k=15-20 for exhaustive research or due diligence.\n4. Synthesize\nMerge evidence by claim, not by source order.\nResolve conflicts by preferring direct passages and recency cues in content.\nDistinguish facts from inferences.\n5. Respond\nGive a concise answer first.\nThen provide evidence bullets with collection/source references.\nEnd with gaps, caveats, or suggested follow-up queries when confidence is not high.\nMulti-Step Workflow Examples\nResearch a topic across multiple collections\n\nScenario: User asks \"What is our data retention policy and how does it compare to SOC 2 requirements?\"\n\ndiscover_collections() → find security_handbook, compliance_docs, soc2_guide\nsearch_collection(\"security_handbook\", \"data retention policy duration\", top_k=5)\nsearch_collection(\"compliance_docs\", \"SOC 2 data retention requirements\", top_k=5)\nsearch_collection(\"soc2_guide\", \"retention controls audit evidence\", top_k=5)\nSynthesize: compare internal policy against SOC 2 requirements, note gaps.\nRespond with findings, citing each collection.\nCompare two vendor contracts\n\nScenario: User asks \"Compare the SLA terms between Vendor A and Vendor B.\"\n\ndiscover_collections() → find vendor_a_contract, vendor_b_contract\nsearch_collection(\"vendor_a_contract\", \"SLA uptime guarantees penalties\", top_k=8)\nsearch_collection(\"vendor_b_contract\", \"SLA uptime guarantees penalties\", top_k=8)\nSecond pass for specifics:\nsearch_collection(\"vendor_a_contract\", \"termination notice period remedies\", top_k=5)\nsearch_collection(\"vendor_b_contract\", \"termination notice period remedies\", top_k=5)\nBuild comparison table: uptime %, penalty structure, notice periods, exclusions.\nHighlight key differences and risks.\nDue diligence deep dive\n\nScenario: User asks \"Summarize everything we know about Company X's security posture.\"\n\nsearch(\"Company X security audit penetration test vulnerability\", top_k=15) — broad discovery pass.\nIdentify which collections returned results (e.g., due_diligence_reports, vendor_assessments).\nTargeted follow-up:\nsearch_collection(\"due_diligence_reports\", \"Company X SOC 2 ISO 27001 certifications\", top_k=10)\nsearch_collection(\"vendor_assessments\", \"Company X data encryption access controls\", top_k=10)\nsearch_collection(\"due_diligence_reports\", \"Company X incident history breach\", top_k=5)\nOrganize findings by category: certifications, technical controls, incident history, gaps.\nPresent with confidence levels and note areas with no data.\nVersioned documentation lookup\n\nScenario: User asks \"What changed in the authentication flow between API v1 and v2?\"\n\nlist_versions_api_docs() → returns [\"1.0\", \"2.0\"]\nsearch_api_docs(query=\"authentication flow token exchange\", version=\"1.0\", top_k=5)\nsearch_api_docs(query=\"authentication flow token exchange\", version=\"2.0\", top_k=5)\nDiff the results: what was added, changed, or removed.\nPresent a clear changelog-style summary.\nREST API workflow (no MCP)\n\nScenario: MCP binding is unavailable. User asks \"Find our vacation policy.\"\n\nHealth check:\ncurl -s https://api.ragora.app/v1/health\n\nList collections:\ncurl https://api.ragora.app/v1/collections \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\"\n\nSearch the relevant collection:\ncurl -X POST https://api.ragora.app/v1/collections/employee_handbook/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"vacation policy paid time off\", \"top_k\": 5}'\n\nParse the results array, extract content and source fields, and compose the answer.\nQuery Patterns\n\nUse short, specific queries. Prefer multiple passes over one monolithic query.\n\nBy task type\nTask\tQuery pattern\tExample\nFactual lookup\t\"<entity> <metric/attribute> <time period>\"\t\"ACME Corp revenue 2024 Q3\"\nPolicy/requirements\t\"<policy type> eligibility criteria exceptions\"\t\"parental leave eligibility criteria exceptions\"\nComparison\tRun same query across each collection\t\"pricing limits SLA exclusions\" × 2 collections\nValidation\tFirst \"<claim>\", then \"counterexample exception to <claim>\"\t\"all employees get 20 vacation days\" then \"exceptions to vacation day policy\"\nExtraction\t\"<entity> <specific data point>\"\t\"ACME Corp CEO contact information\"\nTimeline\t\"<entity> <event type> chronological\"\t\"product launches timeline 2023 2024\"\nQuery refinement strategy\nStart broad: \"data retention policy\" — see what's available.\nNarrow by entity: \"customer data retention policy\" — scope to a specific domain.\nNarrow by attribute: \"customer data retention duration deletion schedule\" — get specifics.\nAdd constraints: Use filters and custom_tags if results are noisy.\nTooling Playbook\nDiscover collections\n\nMCP:\n\ndiscover_collections()\n\n\nAPI:\n\ncurl https://api.ragora.app/v1/collections \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\"\n\nBroad search when unsure\n\nMCP:\n\nsearch(query=\"SOC 2 retention policy for customer logs\", top_k=8)\n\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SOC 2 retention policy for customer logs\", \"top_k\": 8}'\n\nTargeted collection search\n\nMCP:\n\nsearch_collection(\n  collection_name=\"security-handbook\",\n  query=\"log retention duration and deletion policy\",\n  top_k=5\n)\n\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/collections/security_handbook/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"log retention duration and deletion policy\", \"top_k\": 5}'\n\nSearch with version\n\nMCP:\n\nsearch_api_docs(\n  query=\"authentication flow changes\",\n  version=\"2.0\",\n  top_k=5\n)\n\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/collections/api_docs/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"authentication flow changes\", \"version\": \"2.0\", \"top_k\": 5}'\n\nGet topic from a collection\n\nMCP:\n\nget_topic_employee_handbook(topic=\"remote work policy\")\n\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/collections/employee_handbook/topic \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"topic\": \"remote work policy\"}'\n\nFiltered search\n\nMCP:\n\nsearch_collection(\n  collection_name=\"contracts\",\n  query=\"termination for convenience notice period\",\n  top_k=10,\n  custom_tags=[\"msa\", \"legal\"],\n  filters={\"region\": \"US\"}\n)\n\n\nAPI:\n\ncurl -X POST https://api.ragora.app/v1/collections/contracts/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"termination for convenience notice period\", \"top_k\": 10, \"custom_tags\": [\"msa\", \"legal\"], \"filters\": {\"region\": \"US\"}}'\n\nCredit check\n\nMCP:\n\ncheck_balance()\n\n\nAPI:\n\ncurl https://api.ragora.app/v1/billing/balance \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\"\n\nCompare across collections\n\nMCP prompt:\n\ncompare_sources(\n  collection_names=[\"vendor-a-docs\", \"vendor-b-docs\"],\n  question=\"What are the SLA differences?\"\n)\n\n\nAPI (manual — run two searches and compare):\n\n# Search vendor A\ncurl -X POST https://api.ragora.app/v1/collections/vendor_a_docs/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SLA uptime guarantees penalties\", \"top_k\": 8}'\n\n# Search vendor B\ncurl -X POST https://api.ragora.app/v1/collections/vendor_b_docs/search \\\n  -H \"Authorization: Bearer $RAGORA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"SLA uptime guarantees penalties\", \"top_k\": 8}'\n\nContext Management\nChoosing top_k\nScenario\tRecommended top_k\tRationale\nSimple factual question\t3-5\tFew precise results keep context small.\nMulti-facet question\t5-8\tNeed coverage across sub-topics.\nComparison across collections\t8-12 per collection\tNeed enough evidence from each side.\nExhaustive research / due diligence\t15-20\tComprehensive coverage at the cost of more context.\nQuick validation of a claim\t2-3\tJust need to confirm or deny.\nManaging context window size\nPrefer targeted searches over global searches. search_collection() returns fewer, more relevant results than search().\nSummarize as you go. After retrieving results, extract the key facts before moving to the next query. Don't accumulate raw results.\nUse multi-pass retrieval. First pass: broad query with top_k=5. Read results. Second pass: specific follow-up queries targeting gaps.\nDrop low-relevance results. If a result has a low relevance score or doesn't relate to the question, ignore it.\nDon't retrieve what you already know. If a previous query already answered part of the question, don't re-query for it.\nWhen results are too large\n\nIf a single query returns more text than is useful:\n\nReduce top_k to 3.\nAdd custom_tags or filters to narrow scope.\nUse a more specific query instead of a broad one.\nFocus on the highest-scoring results and discard the rest.\nWhen results are insufficient\n\nIf a query returns no results or irrelevant results:\n\nBroaden the query: remove specific terms, use synonyms.\nTry global search() instead of collection-specific.\nCheck if the collection exists with discover_collections().\nTry a different collection if multiple are available.\nIf still empty, tell the user that no relevant data was found.\nOutput Formatting Guidelines\nStandard response structure\n**Answer**: <2-6 sentence direct answer>\n\n**Evidence**:\n- <claim> — *<collection_name> / <source_document>*\n- <claim> — *<collection_name> / <source_document>*\n- <claim> — *<collection_name> / <source_document>*\n\n**Caveats**:\n- <what is missing, uncertain, or conflicting>\n\n**Suggested follow-ups** (if applicable):\n- <exact query the user could ask next>\n\nSource citation rules\nAlways cite the collection name and source document for every claim.\nFormat: — *Collection Name / document-name.md*\nIf multiple results support the same claim, cite the highest-scoring one.\nIf results conflict, cite both and note the conflict.\nConfidence indicators\nHigh confidence: multiple results agree, high relevance scores (>0.85), from authoritative collections.\nMedium confidence: single result or moderate scores (0.6-0.85). Note: \"Based on a single source.\"\nLow confidence: low scores (<0.6), tangential results, or inferred conclusions. Note: \"This is inferred and may need verification.\"\nComparison format\n\nWhen comparing across collections, use a table:\n\n| Aspect | Vendor A | Vendor B |\n|--------|----------|----------|\n| Uptime SLA | 99.9% | 99.95% |\n| Penalty | 5% credit per hour | 10% credit per hour |\n| Notice period | 30 days | 60 days |\n\n*Sources: vendor_a_contract/sla.md, vendor_b_contract/sla.md*\n\nFailure Handling\nFailure\tAgent action\nNo results\tBroaden wording, remove overly specific constraints, retry with search(). If still empty, inform user.\nToo many noisy results\tConstrain by collection, add custom_tags/filters, use narrower entity/date terms.\nConflicting evidence\tPresent both sides, note the conflict, cite both sources, and propose a follow-up query to resolve.\nAccess denied (403)\tExplain that collection access may need to be purchased. Link to marketplace.\nCredit errors (402)\tRun check_balance(), report the balance, and link to billing page.\nRate limited (429)\tWait per Retry-After header or use exponential backoff. Max 3 retries.\nServer error (500/503)\tRetry once after 2-5 seconds. If it persists, inform user of a temporary issue.\nMCP connection failure\tFall back to REST API endpoints. Inform user of the switch.\nTimeout\tReduce top_k, simplify the query, and retry.\nInvalid collection slug\tRe-run discover_collections() and check available slugs.\nQuality Bar\nNever fabricate unseen facts — all claims must come from retrieved evidence.\nAlways ground claims in retrieved evidence with source citations.\nPrefer precise wording over broad generalization.\nKeep final responses concise, decision-oriented, and source-backed.\nDistinguish between directly stated facts and inferred conclusions.\nWhen evidence is incomplete, explicitly state what is missing rather than guessing.\nIf a question cannot be answered from available collections, say so directly."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/mregmi/ragora",
    "publisherUrl": "https://clawhub.ai/mregmi/ragora",
    "owner": "mregmi",
    "version": "1.0.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/ragora",
    "downloadUrl": "https://openagent3.xyz/downloads/ragora",
    "agentUrl": "https://openagent3.xyz/skills/ragora/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ragora/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ragora/agent.md"
  }
}