diff --git a/QUICKSTART.md b/QUICKSTART.md index c2d5a136..81e33cd7 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -20,7 +20,7 @@ ln -s ~/academic-research-skills/academic-paper-reviewer .claude/skills/academic ln -s ~/academic-research-skills/academic-pipeline .claude/skills/academic-pipeline ``` -Each skill must sit at `.claude/skills//SKILL.md` for Claude Code to discover it. See [docs/SETUP.md](docs/SETUP.md) for the copy-based alternative (Option B) and other installation methods (global `~/.claude/skills/`, Cowork, claude.ai). +Each skill must sit at `.claude/skills//SKILL.md` for Claude Code to discover it. See [docs/SETUP.md](docs/SETUP.md) for the copy-based alternative, global `~/.claude/skills/` install, and the other installation methods (Claude Code plugin, Cowork via zip upload, claude.ai). Note that Cowork and claude.ai do not read `~/.claude/skills/` — they install skills through their own settings upload, not this path. ## Step 2: Launch diff --git a/docs/SETUP.md b/docs/SETUP.md index add28653..65d83116 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -258,85 +258,55 @@ claude Use this when you want the four ARS skills available in [Claude Cowork](https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork), Claude Desktop's agentic workspace. -Cowork uses the same skill folder shape: `~/.claude/skills//SKILL.md`. +> **Cowork does not read `~/.claude/skills/`.** That directory belongs to Claude Code (the CLI / IDE), and Cowork does not scan it. Cowork loads skills you upload through **Settings → Capabilities → Skills**, each as its own zip. Symlinking or copying the skill folders into `~/.claude/skills/` will not make them appear in Cowork, no matter how many times you restart. #### Prerequisites - Claude Desktop latest version on macOS or Windows. Download from Anthropic's [Claude Desktop page](https://claude.ai/download). - Active internet connection; Cowork tasks call the Anthropic API. - Keep Claude Desktop open while Cowork tasks run. Cowork runs inside the Desktop process. -- Folder/file permissions that allow Cowork to read and write in the project folder. - A paid plan with Cowork access. See Anthropic's [Cowork requirements](https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork) for current plan availability. -- On Team or Enterprise plans, your organization admin may have disabled Skills, plugins, connectors, or egress. If installed skills do not register after restart, ask your admin to check org-level controls. +- **Code execution / file creation must be enabled** in **Settings → Capabilities**, or the Skills section will not appear. See Anthropic's [Use Skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude). +- On Team or Enterprise plans, your organization admin may have disabled Skills. If the Skills section is missing after enabling code execution, ask your admin to check org-level controls. -#### Option A: symlink install (fastest, single-machine) +#### Step 1: Build one zip per skill -Use symlinks if you work on one machine and want updates by pulling the repo. +Clone the repo, then zip each of the four skill folders individually so that each zip has its own `SKILL.md` at the top level (not nested under an extra folder). The `-x "*.DS_Store"` flag keeps macOS metadata out of the archive. ```bash -git clone https://github.com/Imbad0202/academic-research-skills.git ~/academic-research-skills +git clone https://github.com/Imbad0202/academic-research-skills.git +cd academic-research-skills -mkdir -p ~/.claude/skills -cd ~/.claude/skills -ln -s ~/academic-research-skills/deep-research deep-research -ln -s ~/academic-research-skills/academic-paper academic-paper -ln -s ~/academic-research-skills/academic-paper-reviewer academic-paper-reviewer -ln -s ~/academic-research-skills/academic-pipeline academic-pipeline +for s in deep-research academic-paper academic-paper-reviewer academic-pipeline; do + (cd "$s" && zip -r "../$s.zip" . -x "*.DS_Store") +done ``` -Expected path shape: +This produces four zips in the repo root: `deep-research.zip`, `academic-paper.zip`, `academic-paper-reviewer.zip`, `academic-pipeline.zip`. Each zip's top level looks like: ```text -~/.claude/skills/deep-research/SKILL.md -~/.claude/skills/academic-paper/SKILL.md -~/.claude/skills/academic-paper-reviewer/SKILL.md -~/.claude/skills/academic-pipeline/SKILL.md +SKILL.md +agents/ +examples/ +references/ +templates/ ``` -If you sync `~/.claude/skills` across machines via a cloud folder, use Option B instead. Absolute-path symlinks can break on a fresh checkout or another machine. +#### Step 2: Upload each zip -#### Option B: copy install (cross-machine safe, no auto-update) +1. In Claude Desktop (or claude.ai — uploaded skills sync to the same account), go to **Settings → Capabilities → Skills**. +2. Use the **+** in the Skills panel to upload a skill, and select one of the four zips. Repeat for all four, one at a time. +3. Each skill then appears under **Personal skills**, already enabled, with **Trigger: Slash command + auto**. Re-uploading a skill with the same name replaces the existing one (useful when updating to a new ARS release). -Use copies if you sync `~/.claude/skills` across machines or do not want symlinks. Updates require re-running the four `cp -R` commands. +Verified on Claude Desktop (June 2026): `deep-research.zip` built this way installs cleanly, the full skill description is preserved (no 200-character truncation), and `/deep-research` appears in the Cowork command palette. -```bash -git clone https://github.com/Imbad0202/academic-research-skills.git ~/academic-research-skills +#### Step 3: Use the skills in a Cowork Task -mkdir -p ~/.claude/skills -cp -R ~/academic-research-skills/deep-research ~/.claude/skills/deep-research -cp -R ~/academic-research-skills/academic-paper ~/.claude/skills/academic-paper -cp -R ~/academic-research-skills/academic-paper-reviewer ~/.claude/skills/academic-paper-reviewer -cp -R ~/academic-research-skills/academic-pipeline ~/.claude/skills/academic-pipeline -``` +Type `/` in a Cowork Task to open the command palette and select a skill, or describe your intent in plain language (e.g. "do a deep literature review on X") and Cowork routes by the skill's `description`. -Expected path shape: +#### One trade-off versus Claude Code -```text -~/.claude/skills/deep-research/SKILL.md -~/.claude/skills/academic-paper/SKILL.md -~/.claude/skills/academic-paper-reviewer/SKILL.md -~/.claude/skills/academic-pipeline/SKILL.md -``` - -#### Create or open a Cowork Project - -See Anthropic's [Organize your tasks with Projects in Claude Cowork](https://support.claude.com/en/articles/14116274-organize-your-tasks-with-projects-in-claude-cowork) for the canonical UI walk-through. - -1. Open Claude Desktop. -2. Use the mode selector (**Chat / Cowork**) and switch to **Cowork**. -3. In **Tasks**, use the left navigation panel and choose **Use an existing folder**. -4. Select the local folder you want Cowork to work in. This creates a Cowork Project pointing at that folder. -5. Restart Cowork after installing or updating the skill folders so the four skills register. -6. Open **Customize → Skills**, find each of the four skills (`deep-research`, `academic-paper`, `academic-paper-reviewer`, `academic-pipeline`) under **Personal skills**, and turn on the toggle in the top-right of each skill's detail panel (it reads **Enabled** when on). A registered skill that is not enabled here will not appear in the `/` command palette and Claude will not invoke it. - -#### How Cowork invokes the skills - -Claude uses each skill's `description` to judge relevance, as described in Anthropic's [Skills documentation](https://code.claude.com/docs/en/skills). Example phrases such as "help me write a paper" are illustrative, not literal trigger phrases; paraphrased intent works too. - -If description-based routing does not select the skill you want, Cowork also provides explicit UI surfaces described in Anthropic's [Cowork plugins documentation](https://support.claude.com/en/articles/13837440-use-plugins-in-claude-cowork): - -- Once a skill is enabled in **Customize → Skills** (step 6 above), type `/` in a Cowork Task to open the command palette and select it. Skills that are not enabled do not appear here. -- Use the `+` capability picker to add an enabled skill to the current Task. +Uploaded this way, each skill runs on its own as a standalone instruction set. This is a different experience from Claude Code. In Claude Code the four skills work as a coordinated team: `academic-pipeline` chains them (research → write → review → revise) and each skill drives its own group of sub-agents. Cowork's uploaded-skill runtime does not provide that sub-agent orchestration, so the individual skills respond, but the full end-to-end pipeline does not run the way it does in Claude Code. For the full orchestrated experience, install ARS in Claude Code via Method 0 (plugin) or Method 1 (project skills) above. ### Method 4: Use with claude.ai (web) @@ -389,7 +359,7 @@ Method 4a is claude.ai's standard Custom Skill install path: zip each skill fold **Recommended paths instead:** -- For agentic skill execution on the desktop, use [Method 3 (Cowork)](#method-3-claude-cowork-desktop). All four skills register as Cowork capabilities, with multi-agent orchestration intact. +- For skill execution on the desktop, use [Method 3 (Cowork)](#method-3-claude-cowork-desktop). The four skills upload as standalone Cowork skills; the multi-agent pipeline orchestration is only available in Claude Code (Methods 0–2). - For claude.ai web access to the repo content, use [Method 4b (Project + GitHub integration)](#method-4b-project--github-integration-recommended-for-claudeai). Claude reads the skill bodies, references, and examples, and you can ask questions or draft against them in a normal claude.ai chat. - For Claude Code projects, use [Method 1 (project skills)](#method-1-as-project-skills-recommended) or [Method 2 (standalone)](#method-2-as-a-standalone-project). diff --git a/docs/SETUP.zh-TW.md b/docs/SETUP.zh-TW.md index 7359ee39..18284cea 100644 --- a/docs/SETUP.zh-TW.md +++ b/docs/SETUP.zh-TW.md @@ -258,85 +258,55 @@ claude 當你想在 [Claude Cowork](https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork) 使用四個 ARS skills 時，請用此方式。Cowork 是 Claude Desktop 的 agentic workspace。 -Cowork 使用相同的 skill 資料夾形狀：`~/.claude/skills//SKILL.md`。 +> **Cowork 不會讀取 `~/.claude/skills/`。** 該目錄屬於 Claude Code（CLI / IDE），Cowork 不會掃描它。Cowork 讀取的是你透過 **Settings → Capabilities → Skills** 上傳的 skill，每個 skill 各自打包成一個 zip。把 skill 資料夾 symlink 或複製到 `~/.claude/skills/`，無論重啟幾次都不會讓它們出現在 Cowork。 #### 前置需求 - macOS 或 Windows 的最新版 Claude Desktop。請從 Anthropic 的 [Claude Desktop page](https://claude.ai/download) 下載。 - 可用的網路連線；Cowork tasks 會呼叫 Anthropic API。 - Cowork tasks 執行時，請保持 Claude Desktop 開啟。Cowork 在 Desktop process 內執行。 -- Cowork 對 project folder 需有可讀寫的資料夾與檔案權限。 - 具備 Cowork 存取權的付費方案。目前方案可用性請參考 Anthropic 的 [Cowork requirements](https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork)。 -- Team 或 Enterprise 方案中，組織管理員可能停用了 Skills、plugins、connectors 或 egress。若重啟後已安裝 skills 仍未註冊，請管理員檢查組織層級設定。 +- **必須在 Settings → Capabilities 啟用 code execution / file creation**，否則 Skills 區段不會出現。參見 Anthropic 的 [Use Skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude)。 +- Team 或 Enterprise 方案中，組織管理員可能停用了 Skills。若啟用 code execution 後 Skills 區段仍未出現，請管理員檢查組織層級設定。 -#### 選項 A：symlink 安裝（最快，單機使用） +#### 步驟 1：每個 skill 各打一個 zip -如果你只在一台機器上工作，且希望日後透過 pull repo 更新，請使用 symlinks。 +clone repo 後，把四個 skill 資料夾各自打包成 zip，讓每個 zip 的頂層都是它自己的 `SKILL.md`（不要多包一層資料夾）。`-x "*.DS_Store"` 用來排除 macOS metadata。 ```bash -git clone https://github.com/Imbad0202/academic-research-skills.git ~/academic-research-skills +git clone https://github.com/Imbad0202/academic-research-skills.git +cd academic-research-skills -mkdir -p ~/.claude/skills -cd ~/.claude/skills -ln -s ~/academic-research-skills/deep-research deep-research -ln -s ~/academic-research-skills/academic-paper academic-paper -ln -s ~/academic-research-skills/academic-paper-reviewer academic-paper-reviewer -ln -s ~/academic-research-skills/academic-pipeline academic-pipeline +for s in deep-research academic-paper academic-paper-reviewer academic-pipeline; do + (cd "$s" && zip -r "../$s.zip" . -x "*.DS_Store") +done ``` -預期路徑形狀： +這會在 repo 根目錄產生四個 zip：`deep-research.zip`、`academic-paper.zip`、`academic-paper-reviewer.zip`、`academic-pipeline.zip`。每個 zip 的頂層結構如下： ```text -~/.claude/skills/deep-research/SKILL.md -~/.claude/skills/academic-paper/SKILL.md -~/.claude/skills/academic-paper-reviewer/SKILL.md -~/.claude/skills/academic-pipeline/SKILL.md +SKILL.md +agents/ +examples/ +references/ +templates/ ``` -如果你透過雲端資料夾在多台機器之間同步 `~/.claude/skills`，請改用選項 B。絕對路徑 symlinks 可能在新的 checkout 或另一台機器上失效。 +#### 步驟 2：逐一上傳每個 zip -#### 選項 B：copy 安裝（跨機器安全，不會自動更新） +1. 在 Claude Desktop（或 claude.ai，上傳的 skill 會同步到同一個帳號）中，前往 **Settings → Capabilities → Skills**。 +2. 用 Skills 面板的 **+** 上傳 skill，選擇其中一個 zip。四個 zip 各上傳一次，一次一個。 +3. 每個 skill 上傳後會出現在 **Personal skills** 下，已自動啟用，**Trigger 為 Slash command + auto**。以相同名稱重新上傳會覆蓋既有的 skill（更新到新版 ARS 時很方便）。 -如果你在多台機器之間同步 `~/.claude/skills`，或不想使用 symlinks，請使用 copies。更新時需要重新執行四個 `cp -R` 指令。 +已在 Claude Desktop 驗證（2026 年 6 月）：用此方式打包的 `deep-research.zip` 可乾淨安裝，完整 skill description 保留（不會被截到 200 字元），且 `/deep-research` 會出現在 Cowork command palette。 -```bash -git clone https://github.com/Imbad0202/academic-research-skills.git ~/academic-research-skills +#### 步驟 3：在 Cowork Task 中使用 -mkdir -p ~/.claude/skills -cp -R ~/academic-research-skills/deep-research ~/.claude/skills/deep-research -cp -R ~/academic-research-skills/academic-paper ~/.claude/skills/academic-paper -cp -R ~/academic-research-skills/academic-paper-reviewer ~/.claude/skills/academic-paper-reviewer -cp -R ~/academic-research-skills/academic-pipeline ~/.claude/skills/academic-pipeline -``` +在 Cowork Task 中輸入 `/` 開啟 command palette 選取 skill，或直接用白話描述意圖（例如「幫我對 X 做深度文獻回顧」），Cowork 會依 skill 的 `description` 自動路由。 -預期路徑形狀： +#### 與 Claude Code 的一個取捨 -```text -~/.claude/skills/deep-research/SKILL.md -~/.claude/skills/academic-paper/SKILL.md -~/.claude/skills/academic-paper-reviewer/SKILL.md -~/.claude/skills/academic-pipeline/SKILL.md -``` - -#### 建立或開啟 Cowork Project - -標準 UI 操作流程請參考 Anthropic 的 [Organize your tasks with Projects in Claude Cowork](https://support.claude.com/en/articles/14116274-organize-your-tasks-with-projects-in-claude-cowork)。 - -1. 開啟 Claude Desktop。 -2. 使用模式選擇器（**Chat / Cowork**），切換到 **Cowork**。 -3. 在 **Tasks** 中使用左側導覽面板，選擇 **Use an existing folder**（使用既有資料夾）。 -4. 選取你希望 Cowork 在其中工作的本機資料夾。這會建立一個指向該資料夾的 Cowork Project。 -5. 安裝或更新 skill 資料夾後，請重啟 Cowork，讓四個 skills 註冊。 -6. 開啟 **Customize → Skills**，在 **Personal skills** 下找到四個 skill（`deep-research`、`academic-paper`、`academic-paper-reviewer`、`academic-pipeline`），把每個 skill 詳情面板右上角的 toggle 打開（開啟時會顯示 **Enabled**）。已註冊但未在此啟用的 skill 不會出現在 `/` command palette，Claude 也不會呼叫它。 - -#### Cowork 如何呼叫 skills - -Claude 會使用每個 skill 的 `description` 判斷相關性，方式如 Anthropic 的 [Skills documentation](https://code.claude.com/docs/en/skills) 所述。例如 "help me write a paper" 這類句子只是示例，不是必須逐字輸入的 trigger phrase；改寫後的意圖也能運作。 - -若 description-based routing 沒有選到你想用的 skill，Cowork 也提供 Anthropic 的 [Cowork plugins documentation](https://support.claude.com/en/articles/13837440-use-plugins-in-claude-cowork) 中說明的顯式 UI 入口： - -- 在 **Customize → Skills** 啟用 skill 後（上方步驟 6），在 Cowork Task 中輸入 `/` 開啟 command palette 並選取它。未啟用的 skill 不會出現在這裡。 -- 使用 `+` capability picker，把已啟用的 skill 加入目前 Task。 +用此方式上傳的每個 skill 各自獨立運作，是一份 standalone 的指令集，體驗與 Claude Code 不同。在 Claude Code 中，四個 skill 是協作團隊：`academic-pipeline` 會把它們串起來（research → write → review → revise），每個 skill 各自驅動自己那組 sub-agent。Cowork 的 uploaded-skill runtime 不提供這種 sub-agent orchestration，所以個別 skill 會回應，但完整的 end-to-end pipeline 不會像在 Claude Code 那樣運作。想要完整的協作體驗，請用上方的方法零（plugin）或方法一（project skills）在 Claude Code 安裝 ARS。 ### 方法四：使用 claude.ai（網頁版）