{
  "schemaVersion": "1.0",
  "item": {
    "slug": "shelv",
    "name": "Openclaw Skill",
    "source": "tencent",
    "type": "skill",
    "category": "效率提升",
    "sourceUrl": "https://clawhub.ai/JoshuaOHanlon/shelv",
    "canonicalUrl": "https://clawhub.ai/JoshuaOHanlon/shelv",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/shelv",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=shelv",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "references/api-reference.md",
      "references/error-handling.md",
      "references/shelf-lifecycle.md",
      "scripts/shelv-hydrate.sh"
    ],
    "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-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-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/shelv"
    },
    "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/shelv",
    "agentPageUrl": "https://openagent3.xyz/skills/shelv/agent",
    "manifestUrl": "https://openagent3.xyz/skills/shelv/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/shelv/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": "Shelv",
        "body": "Shelv converts PDF documents (contracts, books, research papers, regulations) into structured Markdown filesystems. Upload a PDF, wait for processing, then hydrate the result into your workspace as real files you can explore with ls, cat, grep, and find.\n\nAPI base URL: https://api.shelv.dev\nAuth: Authorization: Bearer $SHELV_API_KEY on every request.\n\nGet your API key at shelv.dev → Settings → API Keys."
      },
      {
        "title": "1. Upload a document",
        "body": "Upload a PDF to create a new shelf. Processing runs asynchronously.\n\nSHELF_ID=$({baseDir}/scripts/shelv-upload.sh /path/to/document.pdf --name \"My Document\")\n\nWith options:\n\n# Use a structuring template\nSHELF_ID=$({baseDir}/scripts/shelv-upload.sh document.pdf --name \"Q4 Contract\" --template legal-contract)\n\n# Enable review mode (pause before finalizing)\nSHELF_ID=$({baseDir}/scripts/shelv-upload.sh document.pdf --review)\n\n# Upload and wait for processing to complete\nSHELF_ID=$({baseDir}/scripts/shelv-upload.sh document.pdf --wait)\n\nThe script prints the shelf public ID (e.g. shf_0123456789abcdef01234567) to stdout.\n\nAvailable templates: book, legal-contract, academic-paper. Omit to let Shelv auto-detect structure.\n\nInline alternative (without the script):\n\ncurl -X POST \"https://api.shelv.dev/v1/shelves\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\" \\\n  -F \"file=@document.pdf\" \\\n  -F \"name=My Document\"\n\nResponse (201):\n\n{\n  \"publicId\": \"shf_0123456789abcdef01234567\",\n  \"name\": \"My Document\",\n  \"status\": \"uploading\",\n  \"template\": null,\n  \"reviewMode\": false,\n  \"pageCount\": null,\n  \"createdAt\": \"2025-01-15T10:30:00.000Z\",\n  \"updatedAt\": \"2025-01-15T10:30:00.000Z\"\n}"
      },
      {
        "title": "2. Poll for processing completion",
        "body": "Wait for a shelf to finish processing:\n\n{baseDir}/scripts/shelv-poll-status.sh shf_0123456789abcdef01234567\n\nThe script polls GET /v1/shelves/{id} every 5 seconds and prints the current status. It exits 0 when the shelf reaches ready or review, and exits 1 on failed (with error details) or timeout (10 minutes).\n\nProcessing flow: uploading → parsing → structuring → verifying → ready\n\nIf review mode is enabled, the flow pauses at review instead of ready.\n\nInline alternative:\n\ncurl -s \"https://api.shelv.dev/v1/shelves/$SHELF_ID\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\" | jq '.status'"
      },
      {
        "title": "3. Hydrate a shelf into the workspace",
        "body": "Download and extract the shelf's Markdown filesystem into your workspace:\n\n{baseDir}/scripts/shelv-hydrate.sh shf_0123456789abcdef01234567\n\nThis downloads the archive, verifies its checksum, and extracts it to ~/.openclaw/workspace/shelves/<name>/. The script prints a file listing after extraction.\n\nOverride the directory name:\n\n{baseDir}/scripts/shelv-hydrate.sh shf_0123456789abcdef01234567 --name my-contract\n\nReplace an existing shelf (required if the directory already exists):\n\n{baseDir}/scripts/shelv-hydrate.sh shf_0123456789abcdef01234567 --force\n\nAfter hydration, explore the files:\n\nls ~/.openclaw/workspace/shelves/my-contract/\ncat ~/.openclaw/workspace/shelves/my-contract/README.md\nfind ~/.openclaw/workspace/shelves/my-contract/ -name \"*.md\"\ngrep -r \"force majeure\" ~/.openclaw/workspace/shelves/my-contract/"
      },
      {
        "title": "4. List and browse existing shelves",
        "body": "List all shelves:\n\ncurl -s \"https://api.shelv.dev/v1/shelves?page=1&limit=20\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\" | jq '.data[] | {publicId, name, status}'\n\nGet the file tree (flat JSON map of path → content):\n\ncurl -s \"https://api.shelv.dev/v1/shelves/$SHELF_ID/tree\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\" | jq '.files | keys[]'\n\nResponse shape:\n\n{\n  \"shelfPublicId\": \"shf_0123456789abcdef01234567\",\n  \"name\": \"My Contract\",\n  \"fileCount\": 8,\n  \"files\": {\n    \"README.md\": \"# My Contract\\n...\",\n    \"clauses/force-majeure.md\": \"# Force Majeure\\n...\"\n  }\n}"
      },
      {
        "title": "5. Read individual files without hydration",
        "body": "Read a single file by path (useful for targeted lookups without downloading the full archive):\n\ncurl -s \"https://api.shelv.dev/v1/shelves/$SHELF_ID/files/README.md\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\"\n\ncurl -s \"https://api.shelv.dev/v1/shelves/$SHELF_ID/files/clauses/force-majeure.md\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\"\n\nReturns raw Markdown content (text/markdown)."
      },
      {
        "title": "Workspace Conventions",
        "body": "Hydrated shelves live at:\n\n~/.openclaw/workspace/shelves/{name}/\n\nThe {name} is derived from the shelf's display name (lowercased, spaces and special characters replaced with hyphens). Override with --name when hydrating.\n\nIf a directory already exists at the target path, the script will refuse to overwrite it unless --force is passed.\n\nAfter hydration, use standard Unix tools to explore:\n\n# List all files\nfind ~/.openclaw/workspace/shelves/{name}/ -type f\n\n# Read a specific file\ncat ~/.openclaw/workspace/shelves/{name}/README.md\n\n# Search across all files\ngrep -r \"keyword\" ~/.openclaw/workspace/shelves/{name}/\n\n# Count files\nfind ~/.openclaw/workspace/shelves/{name}/ -type f | wc -l"
      },
      {
        "title": "Async Operations",
        "body": "Shelf processing is asynchronous. After uploading, the shelf progresses through:\n\nuploading → parsing → structuring → verifying → ready\n\nUse the poll script to wait for completion:\n\n{baseDir}/scripts/shelv-poll-status.sh $SHELF_ID\n\nIf the shelf reaches failed, the error message and failed step are printed. You can retry:\n\ncurl -X POST \"https://api.shelv.dev/v1/shelves/$SHELF_ID/retry\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\"\n\nFor review mode shelves, approve to finalize:\n\ncurl -X POST \"https://api.shelv.dev/v1/shelves/$SHELF_ID/approve\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\"\n\nOr regenerate the structure:\n\ncurl -X POST \"https://api.shelv.dev/v1/shelves/$SHELF_ID/regenerate\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\""
      },
      {
        "title": "Status-Gated Endpoint Matrix",
        "body": "Not all endpoints are available in every status. The archive, tree, and file endpoints require ready or review:\n\nEndpointProcessingreviewreadyfailedGET /v1/shelves/{id}YesYesYesYesGET .../treeNoYesYesNoGET .../files/*NoYesYesNoGET .../archive-urlNoYesYesNoPOST .../approveNoYesNoNoPOST .../regenerateNoYesNoNoPOST .../retryNoNoNoYes\n\nA 409 Conflict is returned if you call an endpoint outside its allowed statuses."
      },
      {
        "title": "Rate Limits",
        "body": "ScopeLimitReads (GET)120 requests / minWrites (POST/DELETE)20 requests / minShelf creation10 / hour\n\nOn 429 Too Many Requests, back off and retry after the indicated period."
      },
      {
        "title": "Reference Pointers",
        "body": "For detailed API documentation, error codes, and lifecycle diagrams, see:\n\n{baseDir}/references/api-reference.md — Full endpoint docs and response shapes\n{baseDir}/references/shelf-lifecycle.md — Status flow, review mode, template behavior\n{baseDir}/references/error-handling.md — Error codes, retry strategies"
      }
    ],
    "body": "Shelv\n\nShelv converts PDF documents (contracts, books, research papers, regulations) into structured Markdown filesystems. Upload a PDF, wait for processing, then hydrate the result into your workspace as real files you can explore with ls, cat, grep, and find.\n\nAPI base URL: https://api.shelv.dev Auth: Authorization: Bearer $SHELV_API_KEY on every request.\n\nGet your API key at shelv.dev → Settings → API Keys.\n\nCore Workflows\n1. Upload a document\n\nUpload a PDF to create a new shelf. Processing runs asynchronously.\n\nSHELF_ID=$({baseDir}/scripts/shelv-upload.sh /path/to/document.pdf --name \"My Document\")\n\n\nWith options:\n\n# Use a structuring template\nSHELF_ID=$({baseDir}/scripts/shelv-upload.sh document.pdf --name \"Q4 Contract\" --template legal-contract)\n\n# Enable review mode (pause before finalizing)\nSHELF_ID=$({baseDir}/scripts/shelv-upload.sh document.pdf --review)\n\n# Upload and wait for processing to complete\nSHELF_ID=$({baseDir}/scripts/shelv-upload.sh document.pdf --wait)\n\n\nThe script prints the shelf public ID (e.g. shf_0123456789abcdef01234567) to stdout.\n\nAvailable templates: book, legal-contract, academic-paper. Omit to let Shelv auto-detect structure.\n\nInline alternative (without the script):\n\ncurl -X POST \"https://api.shelv.dev/v1/shelves\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\" \\\n  -F \"file=@document.pdf\" \\\n  -F \"name=My Document\"\n\n\nResponse (201):\n\n{\n  \"publicId\": \"shf_0123456789abcdef01234567\",\n  \"name\": \"My Document\",\n  \"status\": \"uploading\",\n  \"template\": null,\n  \"reviewMode\": false,\n  \"pageCount\": null,\n  \"createdAt\": \"2025-01-15T10:30:00.000Z\",\n  \"updatedAt\": \"2025-01-15T10:30:00.000Z\"\n}\n\n2. Poll for processing completion\n\nWait for a shelf to finish processing:\n\n{baseDir}/scripts/shelv-poll-status.sh shf_0123456789abcdef01234567\n\n\nThe script polls GET /v1/shelves/{id} every 5 seconds and prints the current status. It exits 0 when the shelf reaches ready or review, and exits 1 on failed (with error details) or timeout (10 minutes).\n\nProcessing flow: uploading → parsing → structuring → verifying → ready\n\nIf review mode is enabled, the flow pauses at review instead of ready.\n\nInline alternative:\n\ncurl -s \"https://api.shelv.dev/v1/shelves/$SHELF_ID\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\" | jq '.status'\n\n3. Hydrate a shelf into the workspace\n\nDownload and extract the shelf's Markdown filesystem into your workspace:\n\n{baseDir}/scripts/shelv-hydrate.sh shf_0123456789abcdef01234567\n\n\nThis downloads the archive, verifies its checksum, and extracts it to ~/.openclaw/workspace/shelves/<name>/. The script prints a file listing after extraction.\n\nOverride the directory name:\n\n{baseDir}/scripts/shelv-hydrate.sh shf_0123456789abcdef01234567 --name my-contract\n\n\nReplace an existing shelf (required if the directory already exists):\n\n{baseDir}/scripts/shelv-hydrate.sh shf_0123456789abcdef01234567 --force\n\n\nAfter hydration, explore the files:\n\nls ~/.openclaw/workspace/shelves/my-contract/\ncat ~/.openclaw/workspace/shelves/my-contract/README.md\nfind ~/.openclaw/workspace/shelves/my-contract/ -name \"*.md\"\ngrep -r \"force majeure\" ~/.openclaw/workspace/shelves/my-contract/\n\n4. List and browse existing shelves\n\nList all shelves:\n\ncurl -s \"https://api.shelv.dev/v1/shelves?page=1&limit=20\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\" | jq '.data[] | {publicId, name, status}'\n\n\nGet the file tree (flat JSON map of path → content):\n\ncurl -s \"https://api.shelv.dev/v1/shelves/$SHELF_ID/tree\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\" | jq '.files | keys[]'\n\n\nResponse shape:\n\n{\n  \"shelfPublicId\": \"shf_0123456789abcdef01234567\",\n  \"name\": \"My Contract\",\n  \"fileCount\": 8,\n  \"files\": {\n    \"README.md\": \"# My Contract\\n...\",\n    \"clauses/force-majeure.md\": \"# Force Majeure\\n...\"\n  }\n}\n\n5. Read individual files without hydration\n\nRead a single file by path (useful for targeted lookups without downloading the full archive):\n\ncurl -s \"https://api.shelv.dev/v1/shelves/$SHELF_ID/files/README.md\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\"\n\ncurl -s \"https://api.shelv.dev/v1/shelves/$SHELF_ID/files/clauses/force-majeure.md\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\"\n\n\nReturns raw Markdown content (text/markdown).\n\nWorkspace Conventions\n\nHydrated shelves live at:\n\n~/.openclaw/workspace/shelves/{name}/\n\n\nThe {name} is derived from the shelf's display name (lowercased, spaces and special characters replaced with hyphens). Override with --name when hydrating.\n\nIf a directory already exists at the target path, the script will refuse to overwrite it unless --force is passed.\n\nAfter hydration, use standard Unix tools to explore:\n\n# List all files\nfind ~/.openclaw/workspace/shelves/{name}/ -type f\n\n# Read a specific file\ncat ~/.openclaw/workspace/shelves/{name}/README.md\n\n# Search across all files\ngrep -r \"keyword\" ~/.openclaw/workspace/shelves/{name}/\n\n# Count files\nfind ~/.openclaw/workspace/shelves/{name}/ -type f | wc -l\n\nAsync Operations\n\nShelf processing is asynchronous. After uploading, the shelf progresses through:\n\nuploading → parsing → structuring → verifying → ready\n\n\nUse the poll script to wait for completion:\n\n{baseDir}/scripts/shelv-poll-status.sh $SHELF_ID\n\n\nIf the shelf reaches failed, the error message and failed step are printed. You can retry:\n\ncurl -X POST \"https://api.shelv.dev/v1/shelves/$SHELF_ID/retry\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\"\n\n\nFor review mode shelves, approve to finalize:\n\ncurl -X POST \"https://api.shelv.dev/v1/shelves/$SHELF_ID/approve\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\"\n\n\nOr regenerate the structure:\n\ncurl -X POST \"https://api.shelv.dev/v1/shelves/$SHELF_ID/regenerate\" \\\n  -H \"Authorization: Bearer $SHELV_API_KEY\"\n\nStatus-Gated Endpoint Matrix\n\nNot all endpoints are available in every status. The archive, tree, and file endpoints require ready or review:\n\nEndpoint\tProcessing\treview\tready\tfailed\nGET /v1/shelves/{id}\tYes\tYes\tYes\tYes\nGET .../tree\tNo\tYes\tYes\tNo\nGET .../files/*\tNo\tYes\tYes\tNo\nGET .../archive-url\tNo\tYes\tYes\tNo\nPOST .../approve\tNo\tYes\tNo\tNo\nPOST .../regenerate\tNo\tYes\tNo\tNo\nPOST .../retry\tNo\tNo\tNo\tYes\n\nA 409 Conflict is returned if you call an endpoint outside its allowed statuses.\n\nRate Limits\nScope\tLimit\nReads (GET)\t120 requests / min\nWrites (POST/DELETE)\t20 requests / min\nShelf creation\t10 / hour\n\nOn 429 Too Many Requests, back off and retry after the indicated period.\n\nReference Pointers\n\nFor detailed API documentation, error codes, and lifecycle diagrams, see:\n\n{baseDir}/references/api-reference.md — Full endpoint docs and response shapes\n{baseDir}/references/shelf-lifecycle.md — Status flow, review mode, template behavior\n{baseDir}/references/error-handling.md — Error codes, retry strategies"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/JoshuaOHanlon/shelv",
    "publisherUrl": "https://clawhub.ai/JoshuaOHanlon/shelv",
    "owner": "JoshuaOHanlon",
    "version": "1.0.3",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/shelv",
    "downloadUrl": "https://openagent3.xyz/downloads/shelv",
    "agentUrl": "https://openagent3.xyz/skills/shelv/agent",
    "manifestUrl": "https://openagent3.xyz/skills/shelv/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/shelv/agent.md"
  }
}