Miniflux

Browse, read, and manage Miniflux feed articles. Use when Claude needs to work with RSS/atom feeds via Miniflux - listing unread/new articles, reading article content, marking articles as read, and managing feeds/categories. Provides CLI access with flexible output formats (headlines, summaries, full content).

Security Scan

The skill's functionality (Miniflux CLI) largely matches its description, but there are inconsistencies around declared required credentials and persistence of secrets that the user should understand before installing.

Purpose & Capability

Name/description match the code: the script implements list/get/mark/feeds/categories/stats/refresh/search functionality against a Miniflux server. Requiring the 'uv' runner and the miniflux Python client is coherent for this purpose. However, the registry metadata declares no required environment variables or primary credential even though the CLI requires MINIFLUX_URL and MINIFLUX_API_KEY (or CLI flags) to function — that mismatch is unexpected.

Instruction Scope

SKILL.md and the CLI instruct the agent to call the user's Miniflux server (URL set by env/flags) and to save credentials to a local config file (~/.local/share/miniflux/config.json). The instructions do not request other system files or unrelated secrets. The only scope creep is the implicit instruction to persist the API key to disk (config file) and the mention of delegating very large-article summarization to a 'subagent' (vague).

Install Mechanism

The registry has no install spec (instruction-only), which is low-risk. The script uses 'uv' to run and declares a dependency on the 'miniflux' Python package; that implies runtime dependency installation from PyPI when executed via uv. This is expected but is a moderate-risk surface compared with pure instruction-only skills because it will pull packages at runtime from PyPI.

Credentials

The skill requires MINIFLUX_URL and MINIFLUX_API_KEY to operate (the script will exit without them), but the registry metadata lists no required env vars or primary credential. Additionally, the script saves the API key to a config file in the user's home directory (XDG_DATA_HOME or ~/.local/share). Persisting the API key to disk increases exposure and should be explicitly declared and communicated in metadata.

Persistence & Privilege

The skill does write its own config file (~/.local/share/miniflux/config.json) to persist base_url and api_key. It does not request system-wide privileges, nor does it modify other skills' configs. 'always' is false and the skill does not request elevated or cross-skill access. Persisting secrets to the user home directory is normal for a CLI but is a permanence/privacy consideration.

What to consider before installing

What to consider before installing: - The CLI will contact whichever Miniflux server you configure and requires MINIFLUX_URL and MINIFLUX_API_KEY (the script will refuse to run without them), but those required env variables are not declared in the registry metadata — treat that as a metadata mismatch. - By default the script saves the API key to ~/.local/share/miniflux/config.json (or $XDG_DATA_HOME/miniflux/config.json). If you do not want the key persisted to disk, pass the key via environment variable at runtime and avoid using the CLI flags that trigger saving, or inspect/modify the script to change this behavior. - The script uses 'uv' to run and will install the 'miniflux' Python package (from PyPI) at runtime. If you have policy concerns about automatic dependency installation, review the script and dependency provenance first or run it in a sandbox. - The package owner/source/homepage are not present in the registry entry; verify the author's identity or review the included code thoroughly before granting access to your Miniflux API key. - If you want to proceed: verify the script contents (already included), ensure the Miniflux API key has the minimum necessary permissions, and consider using ephemeral credentials or a dedicated read-only key. If the publisher updates the registry metadata to declare required env vars and disclose config persistence, my confidence in coherence would rise.

Miniflux Skill

Browse, read, and manage Miniflux RSS/atom feed articles through a CLI.

Quick Start

# List unread articles (brief format)
uv run scripts/miniflux-cli.py list --status=unread --brief

# Get article details
uv run scripts/miniflux-cli.py get 123

# Mark articles as read
uv run scripts/miniflux-cli.py mark-read 123 456

# Show article statistics (word count, reading time)
uv run scripts/miniflux-cli.py stats --entry-id=123

Configuration

Configuration precedence (highest to lowest):

1. CLI flags: --url, --api-key
2. Environment variables: MINIFLUX_URL, MINIFLUX_API_KEY
3. Config file: ~/.local/share/miniflux/config.json (auto-created on first run)

Setup

# Option 1: Environment variables (recommended for agents)
export MINIFLUX_URL="https://miniflux.example.org"
export MINIFLUX_API_KEY="your-api-key"

# Option 2: CLI flags (one-time, saves to config)
uv run scripts/miniflux-cli.py --url="https://miniflux.example.org" --api-key="xxx" list

Subcommands

list - List Articles

List articles with optional filtering.

# Unread articles (brief)
uv run scripts/miniflux-cli.py list --status=unread --brief

# From specific feed with summary
uv run scripts/miniflux-cli.py list --feed=42 --summary

# Search with limit
uv run scripts/miniflux-cli.py list --search="python" --limit=10

# Starred articles
uv run scripts/miniflux-cli.py list --starred

Flags:

• --status={read,unread,removed} - Filter by status
• --feed=ID - Filter by feed ID
• --category=ID - Filter by category ID
• --starred - Show only starred
• --search=QUERY - Search articles
• --limit=N - Max number of entries
• --offset=N - Skip first N chars in content
• --content-limit=N - Max characters per article
• -b, --brief - Titles only
• -s, --summary - Title + excerpt
• -f, --full - Full content (default)
• --json - JSON output
• --plain - Single-line per entry

get - Get Article by ID

Fetch a single article with content control.

# Full article
uv run scripts/miniflux-cli.py get 123

# First 2000 characters
uv run scripts/miniflux-cli.py get 123 --limit=2000

# Read from character 1000 to 2000 (pagination)
uv run scripts/miniflux-cli.py get 123 --offset=1000 --limit=1000

When content is truncated, shows: [...truncated, total: N chars]

mark-read - Mark as Read

Mark one or more articles as read.

# Single article
uv run scripts/miniflux-cli.py mark-read 123

# Multiple articles
uv run scripts/miniflux-cli.py mark-read 123 456 789

mark-unread - Mark as Unread

Mark one or more articles as unread.

uv run scripts/miniflux-cli.py mark-unread 123

feeds - List Feeds

List all configured feeds.

# Human-readable
uv run scripts/miniflux-cli.py feeds

# JSON format
uv run scripts/miniflux-cli.py feeds --json

categories - List Categories

List all categories.

uv run scripts/miniflux-cli.py categories

stats - Statistics

Show unread counts or article statistics.

# Article statistics (word count, character count, reading time)
uv run scripts/miniflux-cli.py stats --entry-id=123

# Global unread counts per feed
uv run scripts/miniflux-cli.py stats

refresh - Refresh Feeds

Trigger feed refresh.

# Refresh all feeds
uv run scripts/miniflux-cli.py refresh --all

# Refresh specific feed
uv run scripts/miniflux-cli.py refresh --feed=42

search - Search Articles

Convenient alias for list --search.

uv run scripts/miniflux-cli.py search "rust"
uv run scripts/miniflux-cli.py search "ai" --status=unread --brief

Output Formats

• --brief / -b - Quick overview (titles + feed + date)
• --summary / -s - Title + content preview (200 chars)
• --full / -f - Complete article content (default)
• --json - Raw JSON output for machine processing
• --plain - Single-line per entry (tab-separated)

Long Article Handling

For articles with large content (e.g., >5k words):

1. Check statistics first:

   uv run scripts/miniflux-cli.py stats --entry-id=123
   

   Shows word count, character count, reading time.

2. Use pagination to read in chunks:

   # First 5000 chars
   uv run scripts/miniflux-cli.py get 123 --limit=5000
   
   # Next 5000 chars (chars 5000-10000)
   uv run scripts/miniflux-cli.py get 123 --offset=5000 --limit=5000
   

3. For summarization: If article is >5000 words, use a subagent to read and summarize:

   # Get stats to determine word count
   uv run scripts/miniflux-cli.py stats --entry-id=123
   
   # If >5000 words, delegate to subagent for summarization
   

Error Handling

The CLI provides helpful error messages:

• Invalid credentials → Check MINIFLUX_API_KEY
• Article not found → Suggests using list to browse
• Missing config → Shows config file location
• No results → Clear message

Standard Flags

• -v, --version - Show version
• -q, --quiet - Suppress non-error output
• -d, --debug - Enable debug output
• --no-color - Disable colored output
• --url=URL - Miniflux server URL
• --api-key=KEY - Miniflux API key

Examples

Daily Workflow

# Check what's unread
uv run scripts/miniflux-cli.py list --status=unread --brief

# Read interesting articles
uv run scripts/miniflux-cli.py get 456

# Mark as read
uv run scripts/miniflux-cli.py mark-read 456

Research Mode

# Search for specific topics
uv run scripts/miniflux-cli.py search "machine learning" --summary

# Get full article content
uv run scripts/miniflux-cli.py get 789

Batch Processing

# Get all unread as JSON for processing
uv run scripts/miniflux-cli.py list --status=unread --json

# Mark multiple as read
uv run scripts/miniflux-cli.py mark-read 123 456 789

For complete help on any subcommand:

uv run scripts/miniflux-cli.py <subcommand> --help