skills/imbad0202__academic-research-skills
1
0
Fork 0
mirror of https://github.com/Imbad0202/academic-research-skills.git synced 2026-09-14 13:51:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(SETUP): fix Method 3 (Cowork) — zip upload, not ~/.claude/skills/ (#309)

Browse Source 
Method 3 told users to symlink/copy the four skill folders into
~/.claude/skills/ and enable a toggle under Customize → Skills. That
path is Claude Code's; Cowork does not read it, so the skills never
appeared (reported in discussion #306). PR #307's "verified" root cause
was incorrect.

Verified first-hand against the on-disk skill store: Cowork loads skills
uploaded via Settings → Capabilities → Skills, each as its own zip,
registered by a server-issued skill ID. Uploading deep-research this way
installs cleanly with the full description intact and /deep-research in
the palette.

- Rewrite Method 3 in SETUP.md + SETUP.zh-TW.md: zip-per-skill build +
  Settings upload + use + the orchestration trade-off vs Claude Code.
- Fix a stale line claiming Method 3 keeps orchestration intact.
- Fix QUICKSTART wording that listed Cowork next to ~/.claude/skills/.
- EN/zh-TW H4 structure kept in parity.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Edward Cheng-I Wu
2026-06-03 19:08:23 +08:00
committed by GitHub
parent 8316192358
commit 57507ef7a0
3 changed files with 52 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files
QUICKSTART.md
+1 -1
View File
@@ -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 ln -s ~/academic-research-skills/academic-pipeline .claude/skills/academic-pipeline
``` ```
Each skill must sit at `.claude/skills/<skill-name>/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-name>/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 ## Step 2: Launch
docs/SETUP.md
+26 -56
View File
@@ -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. 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-name>/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 #### Prerequisites
- Claude Desktop latest version on macOS or Windows. Download from Anthropic's [Claude Desktop page](https://claude.ai/download). - 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. - Active internet connection; Cowork tasks call the Anthropic API.
- Keep Claude Desktop open while Cowork tasks run. Cowork runs inside the Desktop process. - 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. - 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 ```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 for s in deep-research academic-paper academic-paper-reviewer academic-pipeline; do
cd ~/.claude/skills (cd "$s" && zip -r "../$s.zip" . -x "*.DS_Store")
ln -s ~/academic-research-skills/deep-research deep-research done
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
``` ```
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 ```text
~/.claude/skills/deep-research/SKILL.md SKILL.md
~/.claude/skills/academic-paper/SKILL.md agents/
~/.claude/skills/academic-paper-reviewer/SKILL.md examples/
~/.claude/skills/academic-pipeline/SKILL.md 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 #### Step 3: Use the skills in a Cowork Task
git clone https://github.com/Imbad0202/academic-research-skills.git ~/academic-research-skills
mkdir -p ~/.claude/skills 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`.
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
```
Expected path shape: #### One trade-off versus Claude Code
```text 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.
~/.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.
### Method 4: Use with claude.ai (web) ### 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:** **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.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). - 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).
docs/SETUP.zh-TW.md
+25 -55
View File
@@ -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。 當你想在 [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-name>/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) 下載。 - macOS 或 Windows 的最新版 Claude Desktop。請從 Anthropic 的 [Claude Desktop page](https://claude.ai/download) 下載。
- 可用的網路連線；Cowork tasks 會呼叫 Anthropic API。 - 可用的網路連線；Cowork tasks 會呼叫 Anthropic API。
- Cowork tasks 執行時，請保持 Claude Desktop 開啟。Cowork 在 Desktop process 內執行。 - 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)。 - 具備 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 ```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 for s in deep-research academic-paper academic-paper-reviewer academic-pipeline; do
cd ~/.claude/skills (cd "$s" && zip -r "../$s.zip" . -x "*.DS_Store")
ln -s ~/academic-research-skills/deep-research deep-research done
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
``` ```
預期路徑形狀： 這會在 repo 根目錄產生四個 zip：`deep-research.zip`、`academic-paper.zip`、`academic-paper-reviewer.zip`、`academic-pipeline.zip`。每個 zip 的頂層結構如下：
```text ```text
~/.claude/skills/deep-research/SKILL.md SKILL.md
~/.claude/skills/academic-paper/SKILL.md agents/
~/.claude/skills/academic-paper-reviewer/SKILL.md examples/
~/.claude/skills/academic-pipeline/SKILL.md 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 #### 步驟 3：在 Cowork Task 中使用
git clone https://github.com/Imbad0202/academic-research-skills.git ~/academic-research-skills
mkdir -p ~/.claude/skills 在 Cowork Task 中輸入 `/` 開啟 command palette 選取 skill，或直接用白話描述意圖（例如「幫我對 X 做深度文獻回顧」），Cowork 會依 skill 的 `description` 自動路由。
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
```
預期路徑形狀： #### 與 Claude Code 的一個取捨
```text 用此方式上傳的每個 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/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。
### 方法四：使用 claude.ai（網頁版） ### 方法四：使用 claude.ai（網頁版）