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): add known-broken warning banners to Method 3 + Method 4

Browse Source 
Issue #44 (philpav, 2026-04-27): Cowork install does not register
skills, claude.ai install does not work as documented. Codex audit
on docs/SETUP.md found the root causes:

- Method 3 instructions clone the whole repo to .claude/skills/
  academic-research-skills/, burying every internal SKILL.md one
  level too deep — Cowork's discovery (.claude/skills/<skill>/
  SKILL.md) never finds them.
- Method 4 frames claude.ai's GitHub integration as a Skill install
  path, but it actually loads files into Project knowledge (static
  retrieval context), not the Skills system. Real Skill upload needs
  per-skill zip via Settings → Capabilities → Skills, and current
  description fields exceed the 200-char cap and would be rejected.

Banner-first hotfix (Codex second-opinion advice 2026-04-27):
add prominent WARNING banners on both methods immediately so users
stop following broken instructions. Includes the 4-symlink Cowork
workaround inline + cross-machine cp -R caveat. Full SETUP.md
rewrite (v3.6.5.1) and SKILL.md description trim (v3.6.5.2) follow.

This commit only adds banners; it does not yet rewrite the broken
instructions below them. Users following the banner workaround will
succeed; users skipping the banner and reading the original
instructions will still fail (those will be fixed in v3.6.5.1).
This commit is contained in:
Imbad0202
2026-04-27 17:57:27 +08:00
parent 33f39f136b
commit d176578bec
1 changed files with 26 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/SETUP.md
+26
View File
@@ -208,6 +208,25 @@ claude
Use these skills in [Claude Cowork](https://claude.com/product/cowork) — Claude Desktop's agentic workspace.
> [!WARNING]
> **Known broken (2026-04-27) — instructions in this section bury `SKILL.md` files one level too deep, so Cowork's skill discovery (`.claude/skills/<skill-name>/SKILL.md`) does not register them. A doc-correctness patch (v3.6.5.1) is in progress.**
>
> **Workaround until the patch ships** — install each of the four skill folders separately into `.claude/skills/`:
>
> ```bash
> git clone https://github.com/Imbad0202/academic-research-skills.git ~/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
> ```
>
> Restart Cowork and the four skills should register. If you sync `~/.claude/skills` across machines (cloud folders), use `cp -R` instead of `ln -s` — symlinks pointing at absolute paths break on a fresh checkout.
>
> Tracking: [issue #44](https://github.com/Imbad0202/academic-research-skills/issues/44).
**Option A: folder access (quickest)**
1. Clone this repo locally:
@@ -236,6 +255,13 @@ Skills auto-load when relevant — e.g., saying "help me write a paper" triggers
You can use these skills on [claude.ai](https://claude.ai) via the **Project** feature with GitHub integration — no Claude Code installation needed.
> [!WARNING]
> **Known misleading (2026-04-27) — claude.ai's GitHub integration loads files into _Project knowledge_ (static context for retrieval), NOT the Skills system. Skill auto-loading does not happen via this method.** Use this Method 4 only as a fallback knowledge mode (Claude can read the repo content but does not execute the skills as agentic workflows).
>
> **Real Skill upload on claude.ai** requires Settings → Capabilities → Skills, with one zip uploaded per skill. **Note**: the four skill `description` fields in this repo currently exceed the 200-character cap and would be rejected by the upload UI. A separate patch (v3.6.5.2) trims the descriptions and adds zip upload guidance. Until then, prefer Method 1, 2, or 3.
>
> A doc-correctness patch (v3.6.5.1) clarifying both modes is in progress. Tracking: [issue #44](https://github.com/Imbad0202/academic-research-skills/issues/44).
1. Sign in to [claude.ai](https://claude.ai) (requires a paid plan)
2. Create a new Project: **Projects** → **Create Project**
3. Import from GitHub: in the Project, click **Files** → **+** → **GitHub** → select `Imbad0202/academic-research-skills`