e3cli 1.0.2__tar.gz → 1.0.4__tar.gz

{e3cli-1.0.2 → e3cli-1.0.4}/.github/workflows/release.yml

@@ -41,16 +41,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Calculate tarball sha256
-        id: sha
-        run: |
-          TARBALL_URL="https://github.com/${{ github.repository }}/archive/refs/tags/${{ github.ref_name }}.tar.gz"
-          echo "url=${TARBALL_URL}" >> "$GITHUB_OUTPUT"
-          SHA=$(curl -sL "${TARBALL_URL}" | sha256sum | cut -d' ' -f1)
-          echo "sha256=${SHA}" >> "$GITHUB_OUTPUT"
-          echo "Tarball: ${TARBALL_URL}"
-          echo "SHA256:  ${SHA}"
-
       - name: Clone homebrew tap
         uses: actions/checkout@v4
         with:
@@ -64,29 +54,32 @@ jobs:
 
       - name: Generate formula with all transitive dependencies
         run: |
-          python3 - "${{ github.repository }}" "${{ steps.sha.outputs.url }}" "${{ steps.sha.outputs.sha256 }}" << 'PYSCRIPT'
-          import json, re, sys, urllib.request
+          python3 - "${{ github.repository }}" "${{ github.ref_name }}" << 'PYSCRIPT'
+          import json, re, sys, time, urllib.request
 
-          repo, tarball_url, tarball_sha = sys.argv[1], sys.argv[2], sys.argv[3]
+          repo, ref_name = sys.argv[1], sys.argv[2]
+          e3cli_version = ref_name.lstrip("v")
 
-          def get_info(pkg):
+          def get_info(pkg, version=None):
+              """Fetch package info from PyPI. If version is given, look up that specific
+              release's files; otherwise use the latest. Returns None if the version is
+              not yet indexed or no installable file exists."""
               pkg_normalized = re.sub(r'[-_.]+', '-', pkg).lower()
               try:
                   data = json.loads(urllib.request.urlopen(f"https://pypi.org/pypi/{pkg_normalized}/json").read())
               except Exception:
                   return None
-              ver = data["info"]["version"]
+              ver = version or data["info"]["version"]
               requires = data["info"].get("requires_dist") or []
               deps = []
               for r in requires:
                   if "extra ==" in r:
                       continue
-                  # Extract package name (before any version specifier or marker)
                   m = re.match(r'^([A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?)', r)
                   if m:
                       deps.append(m.group(1).lower())
-              # Prefer pure-Python wheel (py3-none-any) → no compile, much faster brew install.
-              # Fall back to sdist for packages without a universal wheel.
+              # Prefer pure-Python wheel (py3-none-any) → no compile, no build-isolation,
+              # much faster brew install. Fall back to sdist if no universal wheel exists.
               wheel_url = wheel_sha = sdist_url = sdist_sha = ""
               for f in data["releases"].get(ver, []):
                   if f["packagetype"] == "bdist_wheel" and "py3-none-any" in f["filename"]:
@@ -95,7 +88,27 @@ jobs:
                       sdist_url, sdist_sha = f["url"], f["digests"]["sha256"]
               url = wheel_url or sdist_url
               sha = wheel_sha or sdist_sha
-              return {"name": pkg_normalized, "deps": deps, "url": url, "sha256": sha}
+              if not url:
+                  return None
+              return {
+                  "name": pkg_normalized, "deps": deps,
+                  "url": url, "sha256": sha,
+                  "has_wheel": bool(wheel_url),
+              }
+
+          # Resolve e3cli itself from PyPI (the just-uploaded version). Retry until the
+          # wheel appears — PyPI's JSON API may lag a few seconds after twine upload.
+          self_info = None
+          for attempt in range(12):  # 12 × 5s = 60s budget
+              self_info = get_info("e3cli", version=e3cli_version)
+              if self_info and self_info["has_wheel"]:
+                  break
+              print(f"PyPI wheel for e3cli {e3cli_version} not ready (attempt {attempt + 1}/12)…", file=sys.stderr)
+              time.sleep(5)
+          if not self_info:
+              sys.exit(f"FATAL: e3cli {e3cli_version} not found on PyPI after retries")
+          if not self_info["has_wheel"]:
+              print(f"WARNING: no wheel for e3cli {e3cli_version}; formula will use sdist and be slow", file=sys.stderr)
 
           # Resolve ALL transitive dependencies
           seen = set()
@@ -119,15 +132,16 @@ jobs:
                   if dk not in seen:
                       queue.append(d)
 
-          # Build formula
+          # Build formula — main package URL points to PyPI wheel (NOT GitHub source
+          # tarball). This avoids brew triggering pip's build-isolation flow on install.
           lines = [
               'class E3cli < Formula',
               '  include Language::Python::Virtualenv',
               '',
               '  desc "NYCU E3 Moodle automation CLI — sync courses, download materials, submit assignments"',
               f'  homepage "https://github.com/{repo}"',
-              f'  url "{tarball_url}"',
-              f'  sha256 "{tarball_sha}"',
+              f'  url "{self_info["url"]}"',
+              f'  sha256 "{self_info["sha256"]}"',
               '  license "MIT"',
               '',
               '  depends_on "python@3.12"',

{e3cli-1.0.2 → e3cli-1.0.4}/CLAUDE.md

@@ -54,8 +54,16 @@ e3cli i
 
 # Token expired?
 e3cli login --refresh
+
+# AI agent skill (install SKILL.md into Claude Code / Codex / Gemini / Antigravity CLI)
+e3cli skill status                 # check what's detected / installed
+e3cli skill install                # auto-install for detected agents
+e3cli skill install -t claude      # specific target (claude/codex/gemini/antigravity)
+e3cli skill uninstall              # remove
 ```
 
+> **First run:** if `~/.e3cli/config.toml` doesn't exist, ANY `e3cli <cmd>` launches the interactive setup wizard. The wizard is 6 steps (Moodle URL → semester format → download dir → alias → login → AI agent skill install). After completion, re-run the original command.
+
 ## Workflow: When a New Assignment is Detected
 
 1. `e3cli sync` — pull latest materials and assignment status
@@ -99,6 +107,7 @@ e3cli download --course "artificial intelligence"
 3. **Check deadlines first** — prioritize urgent assignments
 4. **Token expiry** — if commands fail with auth errors, run `e3cli login --refresh`
 5. **Don't read credential files** — use CLI commands, not direct file access
+6. **First-run wizard hangs the agent** — if a command opens an interactive setup wizard (config missing) or `login --refresh` prompt, STOP and tell the user to run `e3cli setup` / `e3cli login --refresh` themselves in their terminal. Both are interactive and will hang an agent session.
 
 ## Data Locations
 

{e3cli-1.0.2 → e3cli-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: e3cli
-Version: 1.0.2
+Version: 1.0.4
 Summary: NYCU E3 Moodle automation CLI — sync courses, download materials, submit assignments.
 Project-URL: Homepage, https://github.com/junlinwk/e3cli
 Project-URL: Repository, https://github.com/junlinwk/e3cli
@@ -52,7 +52,7 @@ Description-Content-Type: text/markdown
   <a href="#commands">Commands</a> &bull;
   <a href="#interactive-mode">Interactive</a> &bull;
   <a href="#security">Security</a> &bull;
-  <a href="#claude-code-integration">Claude Code</a> &bull;
+  <a href="#ai-agent-integration">AI Agents</a> &bull;
   <a href="./README_zh-TW.md">繁體中文</a>
 </p>
 
@@ -78,6 +78,7 @@ Description-Content-Type: text/markdown
 - **Interactive TUI** — Full arrow-key interactive interface (`e3cli i`)
 - **Bilingual** — Full Chinese/English support
 - **Multi-school** — Works with any Moodle instance (configurable semester format)
+- **AI Agent Skill** — Bundled SKILL.md installable into Claude Code / Codex CLI / Gemini CLI / Antigravity CLI (`agy`) (`e3cli skill install`)
 
 ## Supported Platforms
 
@@ -136,6 +137,8 @@ pip install -e ".[dev]"
 
 ## Quick Start
 
+> On first run, **any** `e3cli <something>` command will launch the interactive setup wizard (language, Moodle URL, semester format, alias, login, AI agent skill). After setup, re-run your original command.
+
 ```bash
 # 1. Login (first time — interactive setup wizard will guide you)
 e3cli login --save
@@ -297,12 +300,29 @@ e3cli profile use ntu     # → connects to NTU COOL
 
 ### `e3cli setup`
 
-Re-run the interactive setup wizard (language, Moodle URL, semester format, alias, download directory, login).
+Re-run the interactive setup wizard. Six steps: Moodle URL → semester format → download directory → command alias → login → AI agent skill install.
 
 ```bash
 e3cli setup
 ```
 
+> The setup wizard runs automatically the first time any `e3cli` command is invoked (config file missing).
+
+### `e3cli skill`
+
+Install the bundled SKILL.md so AI coding agents (Claude Code / Codex CLI / Gemini CLI / Antigravity CLI (`agy`)) know how to use e3cli — when to sync, how to read full assignment details, when to ask before submitting.
+
+```bash
+e3cli skill status                # show which agents are detected + installed
+e3cli skill install               # auto-detect ~/.claude / ~/.codex / ~/.gemini / antigravity-cli
+e3cli skill install -t claude     # install for a specific target (claude/codex/gemini/antigravity)
+e3cli skill install -t all        # install for all known agents (even if undetected)
+e3cli skill install --force       # overwrite existing
+e3cli skill uninstall             # remove from all agent dirs
+```
+
+The setup wizard offers this as Step 6; running `e3cli skill install` later is the same operation.
+
 ### `e3cli version`
 
 ```bash
@@ -451,18 +471,31 @@ e3cli uses **PBKDF2-HMAC-SHA256** key derivation with integrity verification to
 
 ---
 
-## Claude Code Integration
+## AI Agent Integration
+
+e3cli ships with a `SKILL.md` that teaches AI coding agents — [Claude Code](https://claude.ai/code), OpenAI Codex CLI, Google Gemini CLI, and Google Antigravity CLI (`agy`, Gemini CLI's successor) — how to use it correctly: sync first, read full assignment details before working, ask before submitting, never read credential files, etc.
+
+### Install the skill
+
+The setup wizard's Step 6 offers this automatically. To install manually:
+
+```bash
+e3cli skill install               # auto-detects ~/.claude / ~/.codex / ~/.gemini / ~/.gemini/antigravity-cli
+e3cli skill status                # see what's detected and installed
+```
+
+Once installed, the agent recognises Moodle-related requests ("Moodle", "NYCU", "E3", "assignment", "作業", "繳交", …) and follows the bundled workflow.
 
-This project includes a `CLAUDE.md` file that teaches [Claude Code](https://claude.ai/code) how to use e3cli as an automated assistant. When Claude Code is invoked in this project directory, it can:
+### What the agent can do
 
 - Sync and check for new assignments (`e3cli sync`)
 - Read assignment descriptions and downloaded materials
 - Help complete assignments (with human oversight)
 - Submit completed work (`e3cli submit`)
 
-See [`CLAUDE.md`](./CLAUDE.md) and [`e3cli/agent_prompt.md`](./e3cli/agent_prompt.md) for the full agent automation guide.
+See [`e3cli/skills/e3cli/SKILL.md`](./e3cli/skills/e3cli/SKILL.md), [`CLAUDE.md`](./CLAUDE.md), and [`e3cli/agent_prompt.md`](./e3cli/agent_prompt.md) for the full agent automation guide.
 
-> **Note:** Claude Code will always ask for confirmation before submitting assignments.
+> **Note:** AI agents will always ask for confirmation before submitting assignments.
 
 ---
 

{e3cli-1.0.2 → e3cli-1.0.4}/README.md

@@ -18,7 +18,7 @@
   <a href="#commands">Commands</a> &bull;
   <a href="#interactive-mode">Interactive</a> &bull;
   <a href="#security">Security</a> &bull;
-  <a href="#claude-code-integration">Claude Code</a> &bull;
+  <a href="#ai-agent-integration">AI Agents</a> &bull;
   <a href="./README_zh-TW.md">繁體中文</a>
 </p>
 
@@ -44,6 +44,7 @@
 - **Interactive TUI** — Full arrow-key interactive interface (`e3cli i`)
 - **Bilingual** — Full Chinese/English support
 - **Multi-school** — Works with any Moodle instance (configurable semester format)
+- **AI Agent Skill** — Bundled SKILL.md installable into Claude Code / Codex CLI / Gemini CLI / Antigravity CLI (`agy`) (`e3cli skill install`)
 
 ## Supported Platforms
 
@@ -102,6 +103,8 @@ pip install -e ".[dev]"
 
 ## Quick Start
 
+> On first run, **any** `e3cli <something>` command will launch the interactive setup wizard (language, Moodle URL, semester format, alias, login, AI agent skill). After setup, re-run your original command.
+
 ```bash
 # 1. Login (first time — interactive setup wizard will guide you)
 e3cli login --save
@@ -263,12 +266,29 @@ e3cli profile use ntu     # → connects to NTU COOL
 
 ### `e3cli setup`
 
-Re-run the interactive setup wizard (language, Moodle URL, semester format, alias, download directory, login).
+Re-run the interactive setup wizard. Six steps: Moodle URL → semester format → download directory → command alias → login → AI agent skill install.
 
 ```bash
 e3cli setup
 ```
 
+> The setup wizard runs automatically the first time any `e3cli` command is invoked (config file missing).
+
+### `e3cli skill`
+
+Install the bundled SKILL.md so AI coding agents (Claude Code / Codex CLI / Gemini CLI / Antigravity CLI (`agy`)) know how to use e3cli — when to sync, how to read full assignment details, when to ask before submitting.
+
+```bash
+e3cli skill status                # show which agents are detected + installed
+e3cli skill install               # auto-detect ~/.claude / ~/.codex / ~/.gemini / antigravity-cli
+e3cli skill install -t claude     # install for a specific target (claude/codex/gemini/antigravity)
+e3cli skill install -t all        # install for all known agents (even if undetected)
+e3cli skill install --force       # overwrite existing
+e3cli skill uninstall             # remove from all agent dirs
+```
+
+The setup wizard offers this as Step 6; running `e3cli skill install` later is the same operation.
+
 ### `e3cli version`
 
 ```bash
@@ -417,18 +437,31 @@ e3cli uses **PBKDF2-HMAC-SHA256** key derivation with integrity verification to
 
 ---
 
-## Claude Code Integration
+## AI Agent Integration
+
+e3cli ships with a `SKILL.md` that teaches AI coding agents — [Claude Code](https://claude.ai/code), OpenAI Codex CLI, Google Gemini CLI, and Google Antigravity CLI (`agy`, Gemini CLI's successor) — how to use it correctly: sync first, read full assignment details before working, ask before submitting, never read credential files, etc.
+
+### Install the skill
+
+The setup wizard's Step 6 offers this automatically. To install manually:
+
+```bash
+e3cli skill install               # auto-detects ~/.claude / ~/.codex / ~/.gemini / ~/.gemini/antigravity-cli
+e3cli skill status                # see what's detected and installed
+```
+
+Once installed, the agent recognises Moodle-related requests ("Moodle", "NYCU", "E3", "assignment", "作業", "繳交", …) and follows the bundled workflow.
 
-This project includes a `CLAUDE.md` file that teaches [Claude Code](https://claude.ai/code) how to use e3cli as an automated assistant. When Claude Code is invoked in this project directory, it can:
+### What the agent can do
 
 - Sync and check for new assignments (`e3cli sync`)
 - Read assignment descriptions and downloaded materials
 - Help complete assignments (with human oversight)
 - Submit completed work (`e3cli submit`)
 
-See [`CLAUDE.md`](./CLAUDE.md) and [`e3cli/agent_prompt.md`](./e3cli/agent_prompt.md) for the full agent automation guide.
+See [`e3cli/skills/e3cli/SKILL.md`](./e3cli/skills/e3cli/SKILL.md), [`CLAUDE.md`](./CLAUDE.md), and [`e3cli/agent_prompt.md`](./e3cli/agent_prompt.md) for the full agent automation guide.
 
-> **Note:** Claude Code will always ask for confirmation before submitting assignments.
+> **Note:** AI agents will always ask for confirmation before submitting assignments.
 
 ---
 

{e3cli-1.0.2 → e3cli-1.0.4}/README_zh-TW.md

@@ -18,7 +18,7 @@
   <a href="#指令說明">指令</a> &bull;
   <a href="#互動模式">互動模式</a> &bull;
   <a href="#安全性">安全性</a> &bull;
-  <a href="#claude-code-整合">Claude Code</a> &bull;
+  <a href="#ai-agent-整合">AI Agent</a> &bull;
   <a href="./README.md">English</a>
 </p>
 
@@ -44,6 +44,7 @@
 - **互動介面** — 完整方向鍵互動介面 (`e3cli i`)
 - **雙語** — 完整中文/英文支援
 - **多校支援** — 支援任何 Moodle 平台（可設定學期格式）
+- **AI Agent Skill** — 內建 SKILL.md，可一鍵安裝到 Claude Code / Codex CLI / Gemini CLI / Antigravity CLI (`agy`)（`e3cli skill install`）
 
 ## 支援平台
 
@@ -102,6 +103,8 @@ pip install -e ".[dev]"
 
 ## 快速開始
 
+> 首次執行時，**任何** `e3cli <指令>` 都會自動啟動互動式設定引導（語言、Moodle 網址、學期格式、別名、登入、AI agent skill）。設定完後請再執行一次原本的指令。
+
 ```bash
 # 1. 登入（首次使用會啟動互動式引導）
 e3cli login --save
@@ -263,12 +266,29 @@ e3cli profile use ntu     # → 連線 NTU COOL
 
 ### `e3cli setup`
 
-重新執行互動式設定引導（語言、Moodle 網址、學期格式、別名、下載目錄、登入）。
+重新執行互動式設定引導。共 6 步驟：Moodle 網址 → 學期格式 → 下載目錄 → 指令別名 → 登入 → AI agent skill 安裝。
 
 ```bash
 e3cli setup
 ```
 
+> 首次執行任何 `e3cli` 指令時（找不到 config 檔），會自動跑這個 wizard。
+
+### `e3cli skill`
+
+安裝內建的 SKILL.md，讓 AI 編程助手（Claude Code / Codex CLI / Gemini CLI / Antigravity CLI `agy`）知道如何正確使用 e3cli — 何時 sync、如何讀取作業完整描述、提交前必先詢問等。
+
+```bash
+e3cli skill status                # 列出偵測到 / 已安裝的 agent
+e3cli skill install               # 自動偵測 ~/.claude / ~/.codex / ~/.gemini / antigravity-cli
+e3cli skill install -t claude     # 安裝到特定目標 (claude/codex/gemini/antigravity)
+e3cli skill install -t all        # 安裝到所有已知 agent（即使未偵測到）
+e3cli skill install --force       # 覆寫既有的
+e3cli skill uninstall             # 從所有 agent 目錄移除
+```
+
+setup wizard 的 Step 6 會自動詢問是否安裝；事後跑 `e3cli skill install` 效果相同。
+
 ### `e3cli version`
 
 ```bash
@@ -417,18 +437,31 @@ e3cli 使用 **PBKDF2-HMAC-SHA256** 金鑰衍生搭配完整性驗證來保護
 
 ---
 
-## Claude Code 整合
+## AI Agent 整合
+
+e3cli 內建一份 `SKILL.md`，教 AI 編程助手 — [Claude Code](https://claude.ai/code)、OpenAI Codex CLI、Google Gemini CLI、以及 Google Antigravity CLI (`agy`，Gemini CLI 的繼任者) — 如何正確使用：先 sync、開工前先讀完整作業描述、提交前必先詢問、不讀帳密檔等。
+
+### 安裝 skill
+
+setup wizard 的 Step 6 會自動詢問。事後手動安裝：
+
+```bash
+e3cli skill install               # 自動偵測 ~/.claude / ~/.codex / ~/.gemini / antigravity-cli
+e3cli skill status                # 查看偵測 / 安裝狀態
+```
+
+裝好後，agent 偵測到 Moodle 相關需求（"Moodle"、"NYCU"、"E3"、"作業"、"繳交" …）就會自動依照內建流程操作。
 
-本專案提供 `CLAUDE.md` 文件，教 [Claude Code](https://claude.ai/code) 如何使用 e3cli 作為自動化助手。當 Claude Code 在此專案目錄下運行時，它可以：
+### Agent 能做的事
 
 - 同步並檢查新作業 (`e3cli sync`)
 - 讀取作業描述與已下載的教材
 - 協助完成作業（需人工審查）
 - 提交完成的作業 (`e3cli submit`)
 
-詳見 [`CLAUDE.md`](./CLAUDE.md) 和 [`e3cli/agent_prompt.md`](./e3cli/agent_prompt.md)。
+詳見 [`e3cli/skills/e3cli/SKILL.md`](./e3cli/skills/e3cli/SKILL.md)、[`CLAUDE.md`](./CLAUDE.md) 與 [`e3cli/agent_prompt.md`](./e3cli/agent_prompt.md)。
 
-> **注意：** Claude Code 在提交作業前一定會先詢問確認。
+> **注意：** AI agent 在提交作業前一定會先詢問確認。
 
 ---
 

{e3cli-1.0.2 → e3cli-1.0.4}/e3cli/__init__.py

@@ -1,3 +1,3 @@
 """E3CLI — NYCU E3 Moodle Automation CLI Tool"""
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"

{e3cli-1.0.2 → e3cli-1.0.4}/e3cli/agent_prompt.md

@@ -14,6 +14,7 @@ e3cli is a CLI tool for interacting with NYCU's E3 Moodle platform. The agent ca
 
 - e3cli must be installed and logged in (`e3cli login --save`)
 - The agent must have shell access to run `e3cli` commands
+- **First-run safety:** if `~/.e3cli/config.toml` does not exist, any `e3cli <cmd>` will launch an interactive setup wizard that **will hang an agent session**. Probe via `test -f ~/.e3cli/config.toml` before running real commands; if missing, tell the user to run `e3cli setup` themselves in their own terminal.
 
 ## Workflow
 
@@ -120,8 +121,11 @@ e3cli sync --quiet
 | `e3cli download --course "X"` | Download course X materials |
 | `e3cli download --all` | Download all materials |
 | `e3cli submit ID file.pdf` | Submit assignment |
-| `e3cli i` | Interactive mode |
-| `e3cli login --refresh` | Refresh expired token |
+| `e3cli i` | Interactive mode (DO NOT run from agent — TUI hangs) |
+| `e3cli login --refresh` | Refresh expired token (interactive — instruct user) |
+| `e3cli setup` | First-run wizard (interactive — instruct user) |
+| `e3cli skill install` | Install bundled SKILL.md into Claude / Codex / Gemini / Antigravity (`agy`) |
+| `e3cli skill status` | List which AI agent dirs are detected + installed |
 
 ## Data Locations
 

{e3cli-1.0.2 → e3cli-1.0.4}/e3cli/cli.py

@@ -58,15 +58,16 @@ _original_app_call = app.__call__
 
 
 def _app_with_first_run(*args, **kwargs):
-    skip_keywords = {"--help", "-h", "version", "setup", "skill", "--show-completion", "--install-completion"}
+    # 只保留 shell completion 相關 — 這兩個是 shell 啟動時 typer 自動呼叫的，
+    # 若擋住會在開新 terminal 時 hang 在互動式 wizard。
+    skip_keywords = {"--show-completion", "--install-completion"}
     if (
         is_first_run()
         and sys.stdin.isatty()
         and not any(arg in skip_keywords for arg in sys.argv[1:])
     ):
         run_setup_wizard()
-        if len(sys.argv) <= 1:
-            return
+        return
     return _original_app_call(*args, **kwargs)
 
 

{e3cli-1.0.2 → e3cli-1.0.4}/e3cli/commands/setup.py

@@ -176,7 +176,7 @@ def run_setup_wizard() -> None:
     console.print()
 
     # Step 1: Moodle URL
-    console.print(f"[bold cyan]Step 1/5[/bold cyan] — {t('setup.step_url')}")
+    console.print(f"[bold cyan]Step 1/6[/bold cyan] — {t('setup.step_url')}")
     if lang == "zh":
         console.print("[dim]輸入你的 Moodle 網址。支援任何學校的 Moodle 平台。[/dim]")
     else:
@@ -212,12 +212,12 @@ def run_setup_wizard() -> None:
     console.print()
 
     # Step 2: Semester format
-    console.print("[bold cyan]Step 2/5[/bold cyan] — ", end="")
+    console.print("[bold cyan]Step 2/6[/bold cyan] — ", end="")
     sem_format = _choose_semester_format(lang)
     console.print()
 
     # Step 3: Download directory
-    console.print(f"[bold cyan]Step 3/5[/bold cyan] — {t('setup.step_dir')}")
+    console.print(f"[bold cyan]Step 3/6[/bold cyan] — {t('setup.step_dir')}")
     console.print(f"[dim]{t('setup.step_dir_hint')}[/dim]")
     default_dir = os.path.expanduser("~/e3-downloads")
     download_dir = typer.prompt(
@@ -228,7 +228,7 @@ def run_setup_wizard() -> None:
     console.print()
 
     # Step 4: Alias
-    console.print("[bold cyan]Step 4/5[/bold cyan] — ", end="")
+    console.print("[bold cyan]Step 4/6[/bold cyan] — ", end="")
     alias = _setup_alias(lang)
     console.print()
 
@@ -255,7 +255,7 @@ alias = "{alias}"
     console.print()
 
     # Step 5: Login
-    console.print(f"[bold cyan]Step 5/5[/bold cyan] — {t('setup.step_login')}")
+    console.print(f"[bold cyan]Step 5/6[/bold cyan] — {t('setup.step_login')}")
     want_login = typer.confirm(t("setup.want_login"), default=True)
 
     if want_login:
@@ -296,6 +296,11 @@ alias = "{alias}"
             console.print(f"[dim]  {t('setup.login_fail_hint')}[/dim]")
     console.print()
 
+    # Step 6: AI agent skill
+    console.print("[bold cyan]Step 6/6[/bold cyan] — ", end="")
+    _offer_skill_install(lang)
+    console.print()
+
     # Done
     console.print(Panel(
         f"[bold green]{t('setup.done_title')}[/bold green]\n\n{t('setup.done_body')}",
@@ -304,6 +309,55 @@ alias = "{alias}"
     ))
 
 
+def _offer_skill_install(lang: str) -> None:
+    """偵測 ~/.claude / ~/.codex / ~/.gemini，有的話問要不要安裝 e3cli skill。"""
+    from e3cli.commands.skill import (
+        _bundled_skill_text,
+        _detected,
+        _install_one,
+        _targets,
+    )
+
+    if lang == "zh":
+        console.print("[bold cyan]AI Agent Skill[/bold cyan]")
+        console.print(
+            "[dim]安裝 SKILL.md 讓 Claude Code / Codex / Gemini CLI 知道如何使用 e3cli[/dim]"
+        )
+    else:
+        console.print("[bold cyan]AI Agent Skill[/bold cyan]")
+        console.print(
+            "[dim]Install SKILL.md so Claude Code / Codex / Gemini CLI know how to use e3cli[/dim]"
+        )
+
+    detected = _detected(_targets())
+    if not detected:
+        if lang == "zh":
+            console.print("[dim]  未偵測到 ~/.claude、~/.codex、~/.gemini — 跳過[/dim]")
+            console.print(
+                "[dim]  日後可執行 [cyan]e3cli skill install[/cyan] 安裝[/dim]"
+            )
+        else:
+            console.print("[dim]  No ~/.claude, ~/.codex, ~/.gemini detected — skipping[/dim]")
+            console.print(
+                "[dim]  Later run [cyan]e3cli skill install[/cyan] to install[/dim]"
+            )
+        return
+
+    names = ", ".join(tg.name for tg in detected)
+    if lang == "zh":
+        prompt = f"  偵測到 {names}，要安裝 e3cli skill 嗎？"
+    else:
+        prompt = f"  Detected: {names}. Install e3cli skill?"
+    if not typer.confirm(prompt, default=True):
+        return
+
+    content = _bundled_skill_text()
+    for tg in detected:
+        ok, msg = _install_one(tg, content, force=False)
+        marker = "[green]  ✓[/green]" if ok else "[yellow]  ·[/yellow]"
+        console.print(f"{marker} [bold]{tg.name}[/bold]: {msg}")
+
+
 @app.callback(invoke_without_command=True)
 def setup():
     """Re-run interactive setup wizard."""

{e3cli-1.0.2 → e3cli-1.0.4}/e3cli/commands/skill.py

@@ -39,6 +39,17 @@ def _targets() -> list[Target]:
             detect_dir=home / ".codex",
             skill_path=home / ".codex" / "skills" / SKILL_NAME / "SKILL.md",
         ),
+        # Antigravity CLI (`agy`) — Gemini CLI's successor. Reads skills from
+        # ~/.gemini/antigravity-cli/skills/. Standard SKILL.md format (our
+        # bundled file already has the YAML frontmatter agy expects).
+        Target(
+            name="antigravity",
+            detect_dir=home / ".gemini" / "antigravity-cli",
+            skill_path=home / ".gemini" / "antigravity-cli" / "skills" / SKILL_NAME / "SKILL.md",
+        ),
+        # Legacy Gemini CLI extension format (kept for backward compat with
+        # users still on the pre-agy Gemini CLI). Uses ~/.gemini/extensions/
+        # with a gemini-extension.json descriptor.
         Target(
             name="gemini",
             detect_dir=home / ".gemini",
@@ -68,7 +79,14 @@ def _bundled_skill_text() -> str:
 
 
 def _detected(targets: list[Target]) -> list[Target]:
-    return [t for t in targets if t.detect_dir.is_dir()]
+    found = [t for t in targets if t.detect_dir.is_dir()]
+    # 若同時偵測到 antigravity (agy) 和 legacy gemini，自動跳過 legacy gemini。
+    # antigravity 的 detect_dir (~/.gemini/antigravity-cli) 是 gemini 的子目錄，
+    # 沒這個排除的話會在新 agy 用戶機器上重複裝。
+    names = {t.name for t in found}
+    if "antigravity" in names and "gemini" in names:
+        found = [t for t in found if t.name != "gemini"]
+    return found
 
 
 def _install_one(target: Target, content: str, force: bool) -> tuple[bool, str]:

{e3cli-1.0.2 → e3cli-1.0.4}/e3cli/skills/e3cli/SKILL.md

@@ -11,14 +11,16 @@ The same `e3cli` binary is invoked from the shell — this skill only tells you
 
 ## Prerequisites — verify first
 
-Before doing real work, confirm the tool is installed and authenticated:
+Before doing real work, confirm the tool is installed, configured, and authenticated:
 
 ```bash
+test -f ~/.e3cli/config.toml && echo "configured" || echo "needs setup"
 e3cli --version    # is it installed?
 e3cli courses      # if this errors with "auth"/"token" → user must run: e3cli login --refresh
 ```
 
-If auth fails, **tell the user to run the login command themselves** — it is interactive and will hang if you run it. Do not attempt to read `~/.e3cli/credentials.enc`, `~/.e3cli/key`, or `~/.e3cli/token`.
+- If config is missing → **STOP**. Any `e3cli <cmd>` will launch an interactive first-run setup wizard that hangs the agent. Tell the user to run `e3cli setup` themselves in their terminal.
+- If auth fails → **tell the user to run the login command themselves** — it is interactive and will hang if you run it. Do not attempt to read `~/.e3cli/credentials.enc`, `~/.e3cli/key`, or `~/.e3cli/token`.
 
 ## Core workflow
 
@@ -80,7 +82,7 @@ e3cli login --profile <name> --url <moodle-url> --save         # add a new schoo
 3. **Prioritize by deadline.** When the user vaguely asks "what should I do", run `e3cli assignments --due-soon 7` first.
 4. **Never read credential files.** `~/.e3cli/credentials.enc`, `~/.e3cli/key`, `~/.e3cli/token` are encrypted/sensitive. Use CLI commands instead.
 5. **Don't run `e3cli i`** (interactive TUI). It needs a real terminal and will hang the agent.
-6. **Don't run `e3cli login` or `e3cli login --refresh` yourself.** They are interactive — instruct the user to run them.
+6. **Don't run `e3cli login`, `e3cli login --refresh`, or `e3cli setup` yourself.** They are interactive — instruct the user to run them.
 
 ## Data locations (reference)
 

{e3cli-1.0.2 → e3cli-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "e3cli"
-version = "1.0.2"
+version = "1.0.4"
 description = "NYCU E3 Moodle automation CLI — sync courses, download materials, submit assignments."
 readme = "README.md"
 license = "MIT"