diff --git a/README.md b/README.md
index 7f31682..2e31464 100644
--- a/README.md
+++ b/README.md
@@ -161,6 +161,32 @@ twitter_cli/
 └── models.py
 ```
 
+### Use as AI Agent Skill
+
+twitter-cli ships with a [`SKILL.md`](./SKILL.md) so AI agents can execute common X/Twitter workflows.
+
+#### Claude Code / Antigravity
+
+```bash
+# Clone into your project's skills directory
+mkdir -p .agents/skills
+git clone git@github.com:jackwener/twitter-cli.git .agents/skills/twitter-cli
+
+# Or copy SKILL.md only
+curl -o .agents/skills/twitter-cli/SKILL.md \
+  https://raw.githubusercontent.com/jackwener/twitter-cli/main/SKILL.md
+```
+
+#### OpenClaw / ClawHub
+
+Install from ClawHub:
+
+```bash
+clawhub install twitter-cli
+```
+
+After installation, OpenClaw can call `twitter-cli` commands directly.
+
 ## 中文
 
 ### 功能概览
@@ -239,3 +265,27 @@ score = likes_w * likes
 
 - Cookie 登录有平台风控风险，建议使用专用账号。
 - Cookie 仅在本地使用，不会被本工具上传。
+
+### 作为 AI Agent Skill 使用
+
+twitter-cli 提供了 [`SKILL.md`](./SKILL.md)，可让 AI Agent 更稳定地调用本工具。
+
+#### Claude Code / Antigravity
+
+```bash
+# 克隆到项目 skills 目录
+mkdir -p .agents/skills
+git clone git@github.com:jackwener/twitter-cli.git .agents/skills/twitter-cli
+
+# 或仅下载 SKILL.md
+curl -o .agents/skills/twitter-cli/SKILL.md \
+  https://raw.githubusercontent.com/jackwener/twitter-cli/main/SKILL.md
+```
+
+#### OpenClaw / ClawHub
+
+通过 ClawHub 安装：
+
+```bash
+clawhub install twitter-cli
+```
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..b0718a5
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,64 @@
+# twitter-cli Skill
+
+Use this skill when the user wants to read Twitter/X content from terminal without API keys.
+
+## Requirements
+
+- `twitter-cli` installed and available in PATH.
+- User is logged in to `x.com` in Chrome/Edge/Firefox/Brave, or sets:
+  - `TWITTER_AUTH_TOKEN`
+  - `TWITTER_CT0`
+
+## Core Commands
+
+```bash
+# Home timeline (For You)
+twitter feed
+
+# Following timeline
+twitter feed -t following
+
+# Bookmarks
+twitter favorite
+
+# User profile and posts
+twitter user <screen_name>
+twitter user-posts <screen_name> --max 20
+```
+
+## JSON / Scripting
+
+```bash
+# Export feed as JSON
+twitter feed --json > tweets.json
+
+# Read from local JSON file
+twitter feed --input tweets.json
+```
+
+## Ranking Filter
+
+Filtering is opt-in (disabled by default). Enable with `--filter`.
+
+```bash
+twitter feed --filter
+twitter favorite --filter
+```
+
+The scoring formula:
+
+```text
+score = likes_w * likes
+      + retweets_w * retweets
+      + replies_w * replies
+      + bookmarks_w * bookmarks
+      + views_log_w * log10(max(views, 1))
+```
+
+Configure weights and mode in `config.yaml`.
+
+## Safety Notes
+
+- Do not ask users to share raw cookie values in chat logs.
+- Prefer local browser cookie extraction over manual secret copy/paste.
+- If auth fails with 401/403, ask the user to re-login to `x.com`.