diff --git a/skills/messages/SKILL.md b/skills/messages/SKILL.md
index 23b218c..36d45d4 100644
--- a/skills/messages/SKILL.md
+++ b/skills/messages/SKILL.md
@@ -1,11 +1,11 @@
 ---
 name: messages
-description: Fuzzy search and browse Apple Messages/iMessage. Use when user asks to find texts, search messages, look up conversations, find what someone said, who texted recently, or view recent messages.
+description: "Fuzzy search and browse Apple Messages/iMessage — find texts, search by contact or date, view conversation threads, list recent messages, and check who texted. Use when user asks to find texts, search messages, look up conversations, find what someone said, filter messages by sender or date range, who texted recently, or view recent messages."
 ---
 
 # messages
 
-Fuzzy search through Apple Messages using the messages CLI tool.
+Fuzzy search and browse Apple Messages using the `messages` CLI tool.
 
 ## Installation
 
@@ -21,20 +21,9 @@ cd messages && make install
 - Node.js 22+
 - Full Disk Access for terminal (System Settings > Privacy & Security > Full Disk Access)
 
-## Triggers
-
-Use this skill when user asks about:
-- Finding or searching text messages
-- Looking up conversations or chats
-- Finding what someone said in iMessage
-- Searching message history
-- Who texted recently, recent messages, contacts
-
-**Proactive triggers:** "find text", "search messages", "what did X say", "message from", "text about", "iMessage", "look up conversation", "who texted", "recent messages", "recent texts"
-
 ## Browse Commands
 
-For browsing recent messages and conversations (no search query needed):
+Browse recent messages and conversations (no search query needed):
 
 ```bash
 # Show most recent messages (answers "who texted me?")
@@ -55,10 +44,10 @@ messages thread "John" --after 2024-12-01
 
 ## Search Commands
 
-For fuzzy searching through message content:
+Fuzzy search through message content with typo tolerance:
 
 ```bash
-# Rebuild index and search (recommended)
+# Rebuild index and search (recommended for first use or after new messages)
 messages index-and-search "search query"
 
 # Search with filters
@@ -67,33 +56,18 @@ messages search "query" --after 2024-06-01
 messages search "query" --limit 25
 messages search "query" --context 5
 
-# Combine options
+# Combine filters
 messages search "dinner" --from "Mom" --after 2024-01-01 --limit 15
 ```
 
-## Other Commands
+**Filtering tips:** Sender filter supports partial matches (`--from "John"` matches "John Smith") and phone numbers (`--from "+1555"`). Use quotes around multi-word search terms: `"dinner plans"`.
+
+## Utility Commands
 
 ```bash
 # Check index stats (message count, date range, etc.)
 messages stats
 
-# Rebuild index only
+# Rebuild index only (without searching)
 messages index
 ```
-
-## Options Reference
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `--from, -f` | Filter by sender name or phone | `--from "John Smith"` |
-| `--after, -a` | Messages after date | `--after 2024-06-01` |
-| `--limit, -l` | Max results (default: 10) | `--limit 25` |
-| `--context, -c` | Messages before/after match (default: 2) | `--context 5` |
-
-## Tips
-
-- Use quotes around multi-word search terms: `"dinner plans"`
-- Sender filter supports partial matches: `--from "John"` matches "John Smith"
-- Phone numbers can be used in sender filter: `--from "+1555"`
-- Increase `--limit` for broader searches
-- Increase `--context` to see more conversation around matches