docs: update skills for v0.8.0 new features

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "better-reddit-cli"
-version = "0.6.0"
+version = "0.8.1"
 description = "A command-line tool for browsing Reddit without requiring an API key"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -33,7 +33,7 @@ reddit = "reddit_cli:app"
 [tool.towncrier]
 directory = "news"
 filename = "CHANGELOG.md"
-version = "0.6.0"
+version = "0.8.1"
 name = "better-reddit-cli"
 
 [tool.mypy]

skills/reddit-cli/SKILL.md

@@ -49,6 +49,32 @@ reddit subreddit python --rules
 - **Async requests** - fast, non-blocking
 - **Retry logic** - automatic retry on rate limits
 - **Input validation** - clear error messages
+- **Rich terminal output** - colored tables, formatted posts/comments
+- **Multiple export formats** - display, csv, sql, json, xlsx
+- **Shell completion** - bash, zsh, fish, powershell
+- **File caching** - 5-minute cache for faster repeated queries
+
+## Output Formats
+
+All browse/search/Comments commands support `--format`:
+
+| Format | Description |
+|--------|-------------|
+| `display` | Pretty printed terminal output (default) |
+| `csv` | CSV export with headers |
+| `sql` | SQL INSERT statements |
+| `json` | JSON format |
+| `xlsx` | Excel spreadsheet (requires --output) |
+
+## Shell Completion
+
+```bash
+# Install completion for your shell
+reddit completion --shell bash
+reddit completion --shell zsh
+reddit completion --shell fish
+reddit completion --shell powershell
+```
 
 ## Additional Resources
 

skills/reddit-cli/features/browse.md

@@ -2,6 +2,18 @@
 
 Browse posts from any subreddit.
 
+## When to Use
+
+Use `reddit browse` when you:
+- Want to explore posts in a specific subreddit (e.g., r/python, r/programming)
+- Know which subreddit you want to read
+- Need to browse posts sorted by hot/new/top within a community
+- Want to filter by time period (week, month, year)
+
+**Don't use browse when:**
+- You don't know which subreddit to look at → use `reddit search` instead
+- You want to find a specific post → use `reddit search <query>` instead
+
 ## Command
 
 ```bash
@@ -19,6 +31,8 @@ reddit browse <subreddit> [options]
 | `--after` | Get posts after this ID (for pagination) |
 | `--before` | Get posts before this ID (for pagination) |
 | `--search` | Search within the subreddit instead of listing |
+| `--format` | Output format: display, csv, sql, json, xlsx |
+| `--output` | Write to file instead of stdout |
 
 ## Examples
 

skills/reddit-cli/features/comments.md

@@ -2,6 +2,20 @@
 
 View comments for a post or view a specific comment.
 
+## When to Use
+
+Use `reddit comments <post_id>` when you:
+- Want to read the discussion on a specific post
+- Need to see community reactions and opinions
+- Want to find the best comments (sort by top/confidence)
+
+Use `reddit comment <post_id> <comment_id>` when you:
+- Want to reference a specific comment
+- Need to see a comment's replies
+- Are building a discussion thread analysis
+
+**Note:** Comments are fetched with a default sort of "confidence" (best first).
+
 ## Commands
 
 ### View all comments
@@ -26,12 +40,16 @@ reddit comment <post_id> <comment_id> --replies
 |--------|-------------|
 | `--sort` | Sort by: confidence, top, new, old, controversial, qa (default: confidence) |
 | `--depth` | Maximum nesting depth (1 = top-level only) |
+| `--format` | Output format: display, csv, sql, json, xlsx |
+| `--output` | Write to file instead of stdout |
 
 ### Single Comment Options
 
 | Option | Description |
 |--------|-------------|
 | `--replies` | Include nested replies |
+| `--format` | Output format: display, csv, sql, json, xlsx |
+| `--output` | Write to file instead of stdout |
 
 ## Sort Options
 

skills/reddit-cli/features/navigation.md

@@ -2,6 +2,20 @@
 
 Browse Reddit's frontpage and top posts.
 
+## When to Use
+
+Use `reddit frontpage` or `reddit home` when you:
+- Want to see what's trending on Reddit right now
+- Start your Reddit session without a specific topic in mind
+- Want to discover popular content across all of Reddit
+
+Use `reddit best` when you:
+- Want to see the all-time best posts on Reddit
+- Are looking for highly-regarded content worth reading
+- Want a curated "best of" Reddit experience
+
+**Tip:** These are great starting points if you're new to Reddit or just browsing casually.
+
 ## Commands
 
 ### `reddit frontpage`
@@ -36,6 +50,8 @@ reddit best --period year --limit 100
 | `--period` | Time range: day, week, month, year, all |
 | `--after` | Get posts after this ID |
 | `--before` | Get posts before this ID |
+| `--format` | Output format: display, csv, sql, json, xlsx |
+| `--output` | Write to file instead of stdout |
 
 ## Examples
 

skills/reddit-cli/features/post.md

@@ -2,6 +2,19 @@
 
 View a single post by its ID.
 
+## When to Use
+
+Use `reddit post <post_id>` when you:
+- Have a specific post link or ID you want to read
+- Found a post through search or a shared link
+- Want to see full post details before reading comments
+- Need post metadata (score, author, subreddit, URL)
+
+**Common sources of post IDs:**
+- Shared Reddit links (the last part of the URL)
+- Search results
+- Comments that reference other posts
+
 ## Command
 
 ```bash
@@ -35,6 +48,13 @@ Reddit post IDs are prefixed with `t3_`. The CLI accepts both:
 - `t3_abc123def` (full ID)
 - `abc123def` (short ID)
 
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format` | Output format: display, csv, sql, json, xlsx |
+| `--output` | Write to file instead of stdout |
+
 ## Related Commands
 
 | Command | Description |

skills/reddit-cli/features/search.md

@@ -2,6 +2,18 @@
 
 Search for posts across all of Reddit.
 
+## When to Use
+
+Use `reddit search` when you:
+- Don't know which subreddit to look at
+- Want to find posts about a specific topic or keyword
+- Are looking for something across all of Reddit
+- Want to discover communities related to a topic
+
+**Don't use search when:**
+- You already know the subreddit → use `reddit browse <subreddit> --search` instead
+- You want to browse a community's recent posts → use `reddit browse <subreddit>` instead
+
 ## Command
 
 ```bash
@@ -32,6 +44,8 @@ reddit search rust --sort new
 | `--sort` | Sort by: relevance, hot, top, new, comments (default: relevance) |
 | `--limit` | Number of results: 1-100 (default: 25) |
 | `--period` | Time range: hour, day, week, month, year, all |
+| `--format` | Output format: display, csv, sql, json, xlsx |
+| `--output` | Write to file instead of stdout |
 
 ## Search vs Browse
 

skills/reddit-cli/features/subreddit.md

@@ -2,6 +2,21 @@
 
 Get subreddit information and browse subreddit lists.
 
+## When to Use
+
+Use `reddit subreddit <name>` when you:
+- Want to learn about a specific community
+- Need to see subreddit rules before posting
+- Want to check subscriber count or activity level
+
+Use `reddit subreddits` (no argument) when you:
+- Want to discover new communities
+- Are looking for popular subreddits to join
+- Want to find subreddits related to a topic
+- Need to browse Reddit Gold or default subreddits
+
+**Tip:** If you know the topic but not the subreddit name, try `reddit subreddits --search <keyword>`.
+
 ## Commands
 
 ### Get subreddit info
@@ -46,6 +61,8 @@ Displays the subreddit's rules instead of info.
 | `--new` | List newly created subreddits |
 | `--gold` | List Reddit Gold subreddits |
 | `--default` | List default subreddits |
+| `--format` | Output format: display, csv, sql, json, xlsx |
+| `--output` | Write to file instead of stdout |
 
 ## Examples