Puzle ReadSAFE

🧠 Curated collection of 1209+ best OpenClaw skills — weekly updated by MyClaw.ai

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: puzle-read-skill
version: 0.1.0-beta
description: >-
  Connect to Puzle Read — an intelligent reading workbench that helps users turn articles
  and documents into searchable personal knowledge. Save web articles (by URL or pre-fetched
  content), upload documents and files to the user's reading library, and search across
  everything they've read to find relevant insights. Use this skill whenever the user wants
  to: save or read web articles, add documents to their reading library, look up something
  from their reading collection, process PDFs or other files for deeper understanding,
  or build knowledge workflows around their readings. This skill also applies when the user
  wants to: save something for later reading ("read it later", "bookmark this", "save this
  article"), get a summary or analysis of an article or document, upload a file (PDF, image,
  audio, etc.) for processing, or organize their reading collection. Also trigger when you
  see imports of `puzle_reading` or `PuzleReadingClient`, or when the user mentions Puzle.
compatibility: requires python3, requests
---

# Puzle Read Skill

Save web articles, documents and files to your personal reading library powered by Puzle.
AI analyzes the full text and enables semantic search across everything you've read.

## First-time Setup (show this on skill install)

When this skill is first activated, immediately greet the user and guide them through setup:

1. **Check if a token is already configured**:
   ```python
   from puzle_reading import PuzleReadingClient
   if PuzleReadingClient.token_is_configured():
       # Token exists, ready to go
   ```
   If yes, tell the user: "Puzle Read Skill is ready! You can send me any URL, file, or text
   and I'll save it to your reading library. You can also search across everything you've read."

2. **If no token is configured**, walk the user through it:
   - Tell the user: "To get started, I need your Puzle token. Here's how to get it:"
   - Send the `get_token.gif` file (located at `<this-skill-directory>/get_token.gif`) to the
     user as an attachment so they can see the visual guide.
     - In OpenClaw: send via channel as a file attachment
     - In other environments: provide the file path for the user to open
   - Tell the user to open **https://read-web-test.puzle.com.cn**, log in, then follow the
     GIF to copy their token and paste it back.
   - Once received, save it with `PuzleReadingClient.save_token(token)` and confirm.

3. **After setup is complete**, briefly explain what the skill can do:
   - "You can now send me any URL, article, PDF, or text and I'll save it to your Puzle
     reading library. I can also summarize articles, search across your readings, and more.
     Just try sending me a link!"

## Prerequisites

The bundled Client SDK lives at `scripts/puzle_reading.py` relative to this skill directory.
It requires the `requests` library.

```python
import sys
sys.path.insert(0, "<this-skill-directory>/scripts")
from puzle_reading import PuzleReadingClient
```

## Token Management

Token is stored in `~/.config/puzle/config.json` with file permission `0o600` (owner read/write only).
The SDK looks for a token in the following priority order:

1. Constructor argument `PuzleReadingClient(token="...")`
2. Environment variable `PUZLE_TOKEN`
3. Config file `~/.config/puzle/config.json`

### User sends a token directly

If the user sends a token in the conversation (typically a long string starting with `eyJ...`),
**save it immediately**:

```python
PuzleReadingClient.save_token(token)
client = PuzleReadingClient()  # auto-loads from config file
```

After saving, tell the user: "Token saved to `~/.config/puzle/config.json`. You won't need to
provide it again in future sessions."

### User does not have a token

Guide them step by step:

1. Tell the user to open Puzle Read: **https://read-web-test.puzle.com.cn** and log in
2. Send the tutorial GIF to the user as an attachment so they can see how to get the token.
   The GIF is located at `get_token.gif` relative to this skill directory.
   - In OpenClaw: send it via the channel as a file attachment
   - In other environments: provide the file path for the user to open
3. The GIF shows: open browser DevTools → Application → Cookies → copy the JWT token value
4. Ask the user to paste the token back to you

Once received, save it using the steps above.

### Token already configured (most common case)

Once a token has been saved, all subsequent calls work automatically — no need to ask the user again:

```python
client = PuzleReadingClient()  # auto-reads from ~/.config/puzle/config.json
```

You can check beforehand:

```python
if not PuzleReadingClient.token_is_configured():
    # Guide the user to provide a token
    ...
```

### Token expired (401 error)

The token is valid for approximately **7 days**. When you receive `PuzleAPIError(code=401)`:
1. Tell the user their token has expired
2. Ask them to obtain a new token from Puzle
3. Save the new token: `PuzleReadingClient.save_token(new_token)`

### Environment variable method (optional)

Users can also configure via environment variable, which takes precedence over the config file:

```bash
export PUZLE_TOKEN="eyJhbG..."
```

## Two Modes of Use

### Mode A: Save for later ("Read It Later")

When the user just wants to **save** content — no need to wait for processing. Create the reading,
give user the web link, done.

```python
result = client.create_reading_from_url("https://example.com/article")
# result.web_url → "https://read.puzle.com.cn/read/42"
# Tell the user: "Saved! You can view it here: {result.web_url}"
```

Use this mode when:
- "save this" / "bookmark" / "read it later" / "store this link"
- "save all of these" — batch-saving multiple links
- User uploads a file but doesn't ask for any analysis — "just store this PDF"
- User shares a link in passing without asking a question about its content
- "keep it for later"

### Mode B: Analyze now (b

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

declared (1 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

<key>k5Ey9KFlkqpj+SDkUw+5ED9lTA3En/qUi0zdrydUCH3kMWTE3Eh65NXnFCaxlY2omY2JHnlEoK7Li7oOEvM7eG5VPdcO/sFlMfoCRdnLYdepJ+uLzYwOWR8W4yQVve/clxVFTVRL4DFleKInGdpAxIbHZT2yi4ADAMENls1N1XSLojRuqXePXDeAT/4Mv4TTx0s

content_hash = hashlib.md5(file_bytes).hexdigest()

Gates applied: no_behavioural_pass.