Feedship Skill

Version: 1.5

For: Claude Code and OpenClaw compatible agents

Description: Manage information feeds, subscribe to RSS/GitHub sources, and search articles

Setup

Before using this skill, install feedship with ML and cloud extras:

uv tool install 'feedship[ml,cloudflare]' --python 3.12 --force

> Note: cloudflare extra provides scrapling (HTML fetching); ml extra provides

> sentence-transformers + chromadb (semantic search). Both are required for full functionality.

China / Restricted Networks

For environments where PyPI or HuggingFace is not accessible, use mirrors:

# Add to ~/.bashrc for persistence
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
echo 'export PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/' >> ~/.bashrc
source ~/.bashrc

# Install
uv tool install 'feedship[cloudflare,ml]' --force

Upgrade

# From PyPI (if accessible)
uv tool upgrade feedship

# From GitHub (latest commits)
uv tool install 'feedship @ git+https://github.com/yanpeipan/feedship.git' \
  --pip-args='-i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com' \
  --include-deps --force

After installation, verify with: feedship --version

> First-time setup for semantic search: After installing, run feedship fetch --all

> to populate the vector database with article embeddings. Semantic search requires

> embeddings to be generated first (chromadb storage).

Commands

feed

Manage RSS/Atom feeds and GitHub release trackers.

feed add

feedship feed add <url> [options]

Add a new feed by URL with automatic provider detection.

Options:

• --auto-discover/--no-auto-discover — Enable feed auto-discovery (default: enabled)
• --automatic on|off — Automatically add all discovered feeds (default: off)
• --discover-depth N — Discovery crawl depth 1-10 (default: 1)
• --weight FLOAT — Feed weight for semantic search (default: 0.3)

Examples:

feedship feed add "https://example.com"
feedship feed add "https://github.com/python/cpython" --automatic on
feedship feed add "https://example.com" --discover-depth 3

> Tip: URL containing special chars (e.g., YouTube RSS with ?channel_id=) must be quoted:

> feedship feed add "https://www.youtube.com/feeds/videos.xml?channel_id=..."

feed list

feedship feed list [-v]

List all subscribed feeds with status.

Options:

• -v, --verbose — Show detailed output
• --json — Output in JSON format for programmatic consumption

feed remove

feedship feed remove <feed-id>

Remove a subscribed feed by ID.

fetch

feedship fetch [--all|<feed-ids>] [--concurrency N]

Fetch new articles from subscribed feeds.

Options:

• --all — Fetch all subscribed feeds
• --concurrency N — Max concurrent fetches 1-100 (default: 10)

Examples:

feedship fetch --all
feedship fetch abc12345
feedship fetch abc12345 def67890 --concurrency 20

article

Manage and view fetched articles.

article list

feedship article list [options]

Options:

• --limit N — Maximum articles (default: 20)
• --feed-id — Filter by feed ID
• --since — Start date (YYYY-MM-DD)
• --until — End date (YYYY-MM-DD)
• --on — Specific date (can repeat for multiple)
• --json — Output in JSON format for programmatic consumption

article view

feedship article view <article-id>

View full article content and metadata.

article open

feedship article open <article-id>

Open article in system browser.

article related

feedship article related <article-id> [--limit N]

Find semantically related articles.

search

feedship search <query> [options]

Search articles using full-text or semantic search.

Options:

• --limit N — Maximum results (default: 20)
• --feed-id — Filter by feed ID
• --semantic — Use semantic (vector) search instead of keyword
• --rerank — Apply Cross-Encoder reranking
• --since — Start date filter
• --until — End date filter
• --on — Specific date filter
• --json — Output in JSON format for programmatic consumption

Examples:

feedship search "machine learning"
feedship search "python news" --semantic
feedship search "updates" --semantic --rerank

discover

feedship discover <url> [--discover-depth N]

Discover RSS/Atom/RDF feeds on a website without subscribing.

Options:

• --discover-depth N — Crawl depth 1-10 (default: 1)
• --json — Output in JSON format for programmatic consumption

Examples:

feedship discover example.com
feedship discover example.com --discover-depth 3

info

feedship info [options]

Display system information, configuration, and storage status.

Options:

• --json — Output in JSON format for programmatic consumption

Output includes:

• Version information
• Configuration file location
• Database/storage path
• Feed count and article count
• Installed extras (ml, cloudflare)

Examples:

feedship info
feedship info --json

Output Formats

Tables

feed list, article list, search, discover output Rich tables:

• Magenta headers
• Alternating row styles
• Truncated columns with overflow indicators

Panels

article view uses Rich Panel:

• Title: Article title
• Subtitle: Feed name | Date
• Content: Full article text

Progress Bars

fetch uses Rich progress bars showing:

• Current feed being fetched
• New articles count
• Elapsed time

Common Patterns

Initial Setup

# Add a website feed
feedship feed add "https://example.com" --automatic on

# Fetch all feeds
feedship fetch --all

# View recent articles
feedship article list --limit 50

Daily Workflow

# Fetch new articles
feedship fetch --all

# Search for topics
feedship search "machine learning" --semantic

# Read an article
feedship article view abc12345

# Open in browser for full view
feedship article open abc12345

Feed Management

# List feeds
feedship feed list -v

# Remove stale feed
feedship feed remove old123

# Discover new feeds on site
feedship discover news-site.com --discover-depth 2

Scheduled Fetching (OpenClaw Best Practice)

For automated periodic fetching, use platform-specific schedulers:

macOS (LaunchAgent):

<!-- ~/Library/LaunchAgents/com.feedship.fetch.plist -->
<key>ProgramArguments</key><array><string>/usr/local/bin/feedship</string><string>fetch</string><string>--all</string></array>
<key>StartInterval</key><integer>3600</integer>  <!-- every hour -->

Linux (systemd timer):

# ~/.config/systemd/user/feedship.timer
[Timer] OnBootSec=5min OnUnitActiveSec=1h

Cron:

0 * * * * feedship fetch --all >> ~/.feedship/fetch.log 2>&1

OpenClaw Cron (every 30 minutes):

openclaw cron add \
  --name "feedship-fetch" \
  --agent agent \
  --cron "*/30 * * * *" \
  --tz Asia/Shanghai \
  --session isolated \
  --message "uv run --with feedship[ml,cloudflare] feedship fetch --all" \
  --timeout-seconds 1800

Optional Dependencies

ML Extra (pip install feedship[ml])

Required for semantic search and related articles:

• sentence-transformers
• chromadb
• torch

Cloudflare Extra (pip install feedship[cloudflare])

For enhanced web scraping with:

• browserforge
• playwright
• curl-cffi