How do I install the Freshrss skill?

Run npx skillmds@latest add wmy2981/freshrss in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Freshrss safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Freshrss?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Freshrss free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Freshrss?

wmy2981 (@wmy2981) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Freshrss by wmy2981 — Agent Skill

Name: Freshrss
Author: wmy2981

Freshrss

Access and interact with my FreshRSS instance via python scripts. Use for any RSS-related question, including reading articles, searching past content, finding feeds, getting recommendations, managing subscriptions, checking unread counts, marking read/star, or exploring what I follow. Triggers on keywords: RSS, FreshRSS, feed, unread, headlines, articles, subscriptions, starred.

wmy2981 cb7edf9 5 files · 28.0 KB Updated Sep 17, 2026

File contents

FreshRSS

Self-hosted RSS reader accessed via Google Reader compatible API (GReader). All operations go through a single python script.

Execution Rule

Run the user's requested command directly without pre-checking dependencies, environment variables, or configuration. If something is wrong, the script will fail with a clear error — check and fix only then.

Environment Variables

Variable	Description
`FRESHRSS_URL`	Base URL (e.g. `http://127.0.0.1:1180`)
`FRESHRSS_API_USER`	API username
`FRESHRSS_API_PASSWORD`	API password

💡 Environment variables can be configured in ~/.wmyskills/.env (shared across skills) or scripts/.env (takes priority if present). The script loads them automatically.

Usage

python scripts/freshrss.py <command> [options]

Common options for reading commands: --count N (default 20), -v/--verbose (include summary text).

Reading Articles

Recent articles

python scripts/freshrss.py recent --count 10
python scripts/freshrss.py recent --count 5 -v    # with summary

Unread articles

python scripts/freshrss.py unread --count 20

Articles from a specific feed

python scripts/freshrss.py feed --url "https://example.com/rss" --count 10

Articles from a category

python scripts/freshrss.py category --name "Technology" --count 15

Starred articles

python scripts/freshrss.py starred --count 20

Search articles

Title only (fast, default 200 articles scanned, max 1000):

python scripts/freshrss.py search -k "keyword"

Title + content (slower, use --batch to control scan size):

python scripts/freshrss.py search -k "keyword" --deep --batch 500

Feed Management

List all subscriptions

python scripts/freshrss.py list-feeds

List categories

python scripts/freshrss.py list-categories

Unread counts

python scripts/freshrss.py unread-count

Add a feed

python scripts/freshrss.py add-feed --url "https://example.com/feed.xml" --category "News"

Move feed to another category

python scripts/freshrss.py move-feed --feed-id "feed/https://..." --to "NewCat" --from "OldCat"

Remove a feed

python scripts/freshrss.py remove-feed --feed-id "feed/https://..."

Mark article as read

python scripts/freshrss.py mark-read --item-id "tag:google.com,2005:reader/item/..."

Star an article

python scripts/freshrss.py star --item-id "tag:google.com,2005:reader/item/..."

Feed Recommendations

When asked for recommendations:

Run list-feeds to see current subscriptions and categories
Identify themes from feed titles and categories
Use web search to find feeds in similar topics the user doesn't already follow
Present recommendations grouped by interest area

Notes

Auth token is fetched fresh on each invocation (no caching needed)
All output is JSON for easy parsing
Search is client-side filtered since GReader API lacks native search
Feed stream IDs use format feed/https://example.com/rss
Use -v to include article summary in output (works on all reading commands)

---name: freshrssdescription: Access and interact with my FreshRSS instance via python scripts. Use for any RSS-related question, including reading articles, searching past content, finding feeds, getting recommendations, managing subscriptions, checking unread counts, marking read/star, or exploring what I follow. Triggers on keywords: RSS, FreshRSS, feed, unread, headlines, articles, subscriptions, starred.---# FreshRSSSelf-hosted RSS reader accessed via Google Reader compatible API (GReader).All operations go through a single python script.## Execution RuleRun the user's requested command directly without pre-checking dependencies, environment variables, or configuration. If something is wrong, the script will fail with a clear error — check and fix only then.## Environment Variables| Variable | Description ||---|---|| `FRESHRSS_URL` | Base URL (e.g. `http://127.0.0.1:1180`) || `FRESHRSS_API_USER` | API username || `FRESHRSS_API_PASSWORD` | API password |> 💡 Environment variables can be configured in `~/.wmyskills/.env` (shared across skills) or `scripts/.env` (takes priority if present). The script loads them automatically.## Usage```bashpython scripts/freshrss.py <command> [options]```Common options for reading commands: `--count N` (default 20), `-v`/`--verbose` (include summary text).## Reading Articles### Recent articles```bashpython scripts/freshrss.py recent --count 10python scripts/freshrss.py recent --count 5 -v # with summary```### Unread articles```bashpython scripts/freshrss.py unread --count 20```### Articles from a specific feed```bashpython scripts/freshrss.py feed --url "https://example.com/rss" --count 10```### Articles from a category```bashpython scripts/freshrss.py category --name "Technology" --count 15```### Starred articles```bashpython scripts/freshrss.py starred --count 20```### Search articlesTitle only (fast, default 200 articles scanned, max 1000):```bashpython scripts/freshrss.py search -k "keyword"```Title + content (slower, use `--batch` to control scan size):```bashpython scripts/freshrss.py search -k "keyword" --deep --batch 500```## Feed Management### List all subscriptions```bashpython scripts/freshrss.py list-feeds```### List categories```bashpython scripts/freshrss.py list-categories```### Unread counts```bashpython scripts/freshrss.py unread-count```### Add a feed```bashpython scripts/freshrss.py add-feed --url "https://example.com/feed.xml" --category "News"```### Move feed to another category```bashpython scripts/freshrss.py move-feed --feed-id "feed/https://..." --to "NewCat" --from "OldCat"```### Remove a feed```bashpython scripts/freshrss.py remove-feed --feed-id "feed/https://..."```### Mark article as read```bashpython scripts/freshrss.py mark-read --item-id "tag:google.com,2005:reader/item/..."```### Star an article```bashpython scripts/freshrss.py star --item-id "tag:google.com,2005:reader/item/..."```## Feed RecommendationsWhen asked for recommendations:1. Run `list-feeds` to see current subscriptions and categories2. Identify themes from feed titles and categories3. Use web search to find feeds in similar topics the user doesn't already follow4. Present recommendations grouped by interest area## Notes- Auth token is fetched fresh on each invocation (no caching needed)- All output is JSON for easy parsing- Search is client-side filtered since GReader API lacks native search- Feed stream IDs use format `feed/https://example.com/rss`- Use `-v` to include article summary in output (works on all reading commands)

Frequently asked questions