# readwise-upload

> Upload markdown files or folders to Readwise Reader with metadata extraction and error handling

- Author: Edwin Estrada
- Repository: edwinestrada/claude-code-skills
- Version: 20260124174727
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/edwinestrada/claude-code-skills
- Web: https://mule.run/skillshub/@@edwinestrada/claude-code-skills~readwise-upload:20260124174727

---

---
description: Upload markdown files or folders to Readwise Reader with metadata extraction and error handling
---

# Upload to Readwise Reader

You are tasked with uploading markdown files to Readwise Reader using the Readwise API.

## When Invoked

When the user runs `/readwise-upload <path>`, respond immediately:

```
📤 Uploading to Readwise Reader...
```

Then proceed with the upload process.

## Process Steps

### Step 1: Validate Input

1. Check if the user provided a path argument
2. If no path provided, ask: "Please provide a file or folder path to upload"
3. Validate that the path exists using Read tool (for files) or Glob tool (for directories)

### Step 2: Check Dependencies

The script requires these Python packages:
- `requests`
- `markdown`
- `pyyaml`

If running in a project without these dependencies, install them first:
```bash
uv add requests markdown pyyaml
```

Or if the user prefers standalone usage, they can install globally:
```bash
pip install requests markdown pyyaml
```

### Step 3: Execute Upload Script

1. Use the Bash tool to run the upload script:
   ```bash
   uv run python .claude/skills/readwise-upload/scripts/upload_to_readwise.py <path>
   ```

2. The script will:
   - Read markdown files
   - Extract title from frontmatter, H1 heading, or filename
   - Extract metadata (author, tags, category, published_date)
   - Convert markdown to HTML
   - Upload to Readwise Reader API
   - Display progress and results

### Step 4: Handle Results

**Success Output:**
- Display the script's output directly
- The script shows ✅ for successful uploads
- The script shows ℹ️ for duplicates
- The script shows ❌ for errors

**Error Handling:**

If the script fails with "No Readwise API token":
```
❌ Readwise API token not found.

Set the token in your environment:
  export READWISE_API_TOKEN='your-token-here'

Get your token: https://readwise.io/access_token
```

If the script fails with "Invalid token":
```
❌ Invalid Readwise API token.

Please verify your token:
  https://readwise.io/access_token
```

For other errors, show the script's error output.

## Important Guidelines

1. **Always run with uv**: Use `uv run python` to ensure dependencies are available
2. **Don't modify files**: This skill only reads and uploads, never modifies source files
3. **Respect existing metadata**: Use frontmatter fields if present
4. **Handle batch uploads**: For folders, the script processes all .md files recursively
5. **Show progress**: Let the script's output flow through to the user

## Supported Frontmatter Fields

The script extracts these fields from YAML frontmatter:
- `title`: Document title (overrides H1 and filename)
- `author`: Author name
- `tags`: List of tag strings
- `category`: Readwise category (article, note, etc.)
- `published_date`: Publication date (ISO 8601)
- `summary`: Brief summary

## Examples

**Single file:**
```
/readwise-upload notes/article.md
```

**Folder:**
```
/readwise-upload notes/
```

**Absolute path:**
```
/readwise-upload /Users/username/Documents/notes/file.md
```