docs: add structured output guidance for AI agents

README.md

@@ -26,9 +26,11 @@ A terminal-first CLI for Twitter/X: read timelines, bookmarks, and user profiles
 - Tweet detail: view a tweet and its replies
 - List timeline: fetch tweets from a Twitter List
 - User lookup: fetch user profile, tweets, likes, followers, and following
-- JSON output: export any data for scripting
+- JSON output: export any data for scripting and AI agent integration
 - Optional scoring filter: rank tweets by engagement weights
 
+> **AI Agent Tip:** Always use `--json` for structured output instead of parsing the default rich-text display. Use `--max` to limit results.
+
 **Write:**
 - Post: create new tweets and replies
 - Delete: remove your own tweets
@@ -292,7 +294,9 @@ After installation, OpenClaw can call `twitter-cli` commands directly.
 - 推文详情：查看推文及其回复
 - 列表时间线：获取 Twitter List 的推文
 - 用户查询：查看用户资料、推文、点赞、粉丝和关注
-- JSON 输出：便于脚本处理
+- JSON 输出：便于脚本处理和 AI agent 集成
+
+> **AI Agent 提示：** 需要结构化输出时始终使用 `--json`，不要解析默认的富文本显示。用 `--max` 控制返回数量。
 
 **写入:**
 - 发推：发布新推文和回复

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: twitter-cli
-description: CLI skill for Twitter/X to read timelines, bookmarks, user posts, and profiles from the terminal without API keys
+description: CLI skill for Twitter/X with JSON output for AI agents — read timelines, bookmarks, user posts, and profiles from the terminal without API keys
 author: jackwener
 version: "1.0.0"
 tags:
@@ -15,6 +15,15 @@ tags:
 
 Use this skill when the user wants to read or interact with Twitter/X content from terminal without API keys.
 
+## Agent Defaults
+
+When you need machine-readable output:
+
+1. **Always use `--json`** for structured output. Do not parse the default rich-text table output.
+2. Use `--max` to keep result sets small and token-efficient.
+3. Use `-o <file>` to save large results to a file instead of printing to stdout.
+4. Prefer specific commands over broad ones. Example: use `twitter user-posts elonmusk --max 5 --json` instead of fetching full timelines.
+
 ## Prerequisites
 
 ```bash
@@ -98,7 +107,10 @@ twitter bookmark 1234567890                          # Bookmark
 twitter unbookmark 1234567890                        # Unbookmark
 ```
 
-## JSON / Scripting
+## Structured Output
+
+All major query commands support `--json` for machine-readable output.
+AI agents should **always use `--json`** instead of parsing the default rich-text display:
 
 ```bash
 twitter feed --json > tweets.json
@@ -137,14 +149,15 @@ Configure weights and mode in `config.yaml`.
 twitter user-posts elonmusk --max 5 --json
 
 # Search and export for analysis
-twitter search "topic" --json > results.json
+twitter search "topic" --max 20 --json
+twitter search "topic" -o results.json
 
 # Check user profile
 twitter user elonmusk --json
 
-# Daily reading workflow
-twitter feed -t following --filter
-twitter bookmarks --filter
+# Daily reading workflow (structured output)
+twitter feed -t following --max 30 --json
+twitter bookmarks --max 20 --json
 ```
 
 ## Error Handling