Date: 2026-04-27
Target release: v3.6.5.1 (patch, doc-only)
Branch: hotfix/v3.6.5.1-setup-doc-correctness
Trigger: GitHub issue #44 (philpav, 2026-04-27) + local Codex audit on docs/SETUP.md
Author: Cheng-I Wu
This brief is the non-negotiable constraint sheet for the SETUP.md rewrite. It is given to Codex (or any drafter) so that the prose it produces respects ARS-specific invariants without re-deriving them. Without this brief, the drafter will likely:
This brief does not write the SETUP.md content itself. It defines what content must achieve, what conventions it must follow, and what is out of bounds.
The drafter MUST follow these. Deviation requires a separate human decision, not a unilateral drafter call.
The repo has exactly four skill folders at the root, each with its own SKILL.md:
academic-research-skills/
├── deep-research/SKILL.md
├── academic-paper/SKILL.md
├── academic-paper-reviewer/SKILL.md
└── academic-pipeline/SKILL.md
There is no root SKILL.md. There is no plan to create one. Any install method that requires a single SKILL.md at the install path must install each skill folder separately, not the whole repo.
The discovery convention all three platforms share is:
<install-root>/<skill-name>/SKILL.md
For Claude Code project skills: <project>/.claude/skills/<skill-name>/SKILL.md.
For Cowork: ~/.claude/skills/<skill-name>/SKILL.md.
For claude.ai upload: each skill is uploaded as one zip, where the zip's top-level entry is <skill-name>/SKILL.md (not <skill-name>/<skill-name>/SKILL.md).
Any install instruction that produces <install-root>/academic-research-skills/<skill-name>/SKILL.md (extra nesting level) is broken — Cowork / Claude Code / claude.ai will not discover the skill.
Sub-method 4a: Real Skill upload via Settings → Capabilities → Skills, one zip per skill. This is the path that gives skill auto-loading and trigger phrase routing. Currently blocked by the 200-char description cap (fixed in v3.6.5.2, NOT v3.6.5.1).
Sub-method 4b: Project + GitHub integration loads files into Project knowledge (static retrieval context). This is NOT a Skill install — Claude can read the files but does not execute them as agentic skills.
The SETUP.md must distinguish these two clearly. 4a is the "real" install; 4b is fallback knowledge mode. Do not conflate.
Imbad0202/academic-research-skills is a public repo with branch protection that blocks direct commits to main (GH013). All changes must go via PR. The drafter does not commit directly. The drafter does not invent its own branch name; the branch is hotfix/v3.6.5.1-setup-doc-correctness (already created by human).
When in doubt about Cowork / claude.ai UI terminology, prefer (in order):
/ and + UI surface): https://support.claude.com/en/articles/13837440-use-plugins-in-claude-coworkProject file limits (per-file 30 MB, count unlimited): https://support.claude.com/en/articles/8241126-upload-files-to-claude
Issue #44 reply (already vetted UI wording, inlined below for self-contained reference):
Cowork install — symlink approach the user already validated:
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."claude.ai distinction (verbatim phrasing the user used): "the GitHub integration loads files into Project knowledge, not Skills. Real Skill upload needs each skill zipped separately via Settings → Capabilities → Skills, and descriptions in this repo currently exceed the 200-char limit so they'd reject."
docs/SETUP.md text — only for parts the audit (§2 below) did not flag as drifted. Do not lift wording from sections F1-F7 covered by this brief.Never invent a UI term. Never paraphrase a UI label as a "more readable" alternative — the literal label is what the user clicks. When Anthropic doc and issue #44 reply disagree on a UI label, Anthropic doc wins (it is the upstream truth as of the doc's last-updated date).
The drafter must NOT modify these as part of v3.6.5.1:
SKILL.md (description, frontmatter, body) — those are v3.6.5.2 scope*/agents/shared/scripts/tests/The drafter MAY modify (within v3.6.5.1 scope) — this list is the complete allowed-edit set:
docs/SETUP.md (primary work)docs/SETUP.zh-TW.md if it exists (mirror EN changes)README.md and README.zh-TW.md install method sections (sweep, only if they mention Cowork or claude.ai install).claude/CLAUDE.md install-related sections (sweep, only if drifted from v3.6.5.1)QUICKSTART.md install-related sections (sweep, only if drifted)CHANGELOG.md (add v3.6.5.1 entry)Sweep vs edit boundary (resolves apparent conflict with §4): the §4 sweep grep MAY scan a broader path (e.g. all of docs/) to find install-method mentions, but the drafter MAY edit only the files in the allowed-edit set above. Hits outside the allowed-edit set are report-only: list them in the validation report for human review, do not auto-edit. Touching files outside the allowed-edit set requires explicit human approval (out of v3.6.5.1 scope).
The drafter does NOT decide:
Source: local Codex audit on docs/SETUP.md 2026-04-27.
docs/SETUP.md:213-229 Method 3 wrong pathProblem: Current Option A says clone repo to .claude/skills/academic-research-skills/. This produces:
.claude/skills/academic-research-skills/deep-research/SKILL.md ← buried, not discovered
instead of the required:
.claude/skills/deep-research/SKILL.md ← Cowork finds this
Same problem in Option B if it follows the same pattern.
Authoritative source: Claude Code Skills paths and discovery convention — https://code.claude.com/docs/en/skills
Fix: Rewrite Option A and Option B to install each of the four skill folders separately into .claude/skills/. Two acceptable approaches:
git clone repo to a stable path (e.g. ~/academic-research-skills), then ln -s <repo>/<skill-name> ~/.claude/skills/<skill-name> for each of the four skills. Must include a caveat: if the user syncs ~/.claude/skills across machines via cloud folders, prefer cp -R because absolute-path symlinks break on a fresh checkout (this is a real ARS lesson from feedback_relative_symlinks_in_repos.md).git clone repo, then cp -R <repo>/<skill-name> ~/.claude/skills/<skill-name> for each of the four skills. Note that updates require re-running cp.The four skill folder names are exact: deep-research, academic-paper, academic-paper-reviewer, academic-pipeline. Use bash code blocks with explicit per-skill commands.
Hard rule on consolidation (resolves apparent conflict with §8 drafter judgement zone): the drafter MAY consolidate Option A and Option B into a single section if it improves readability, BUT every final command must name all four skill folders explicitly. No for skill in ... loop, no parameterised one-liner, no "repeat for each skill" instruction without showing each command. Reason: readers copy-paste in a hurry and skip iteration syntax; explicit four-line blocks have ~zero misuse rate.
docs/SETUP.md:237 Method 4 conceptually wrongProblem: Current text says "use these skills on claude.ai via the Project feature with GitHub integration". This frames GitHub integration as a Skill install path. It is not — GitHub integration loads files into Project knowledge (static retrieval context), not the Skills system. Skill auto-loading and trigger phrase routing do not happen via this method.
Authoritative sources: - Projects (claude.ai static knowledge): https://support.claude.com/en/articles/9517075-what-are-projects - GitHub integration: https://support.claude.com/en/articles/10167454-using-the-github-integration - Custom Skills packaging (zip per skill, ≤200-char description): https://claude.com/docs/skills/how-to
Fix: Restructure Method 4 into two clearly labelled sub-methods. Use neutral framing — neither is "recommended" right now (4a is blocked on v3.6.5.2; 4b is documented-but-limited):
<skill-name>/SKILL.md, matching the name field in the skill's frontmatter). State the current blocker explicitly: the four skill description fields in this repo currently exceed the 200-char cap and would be rejected by the upload UI; the description trim ships in patch v3.6.5.2 immediately after this v3.6.5.1 doc patch. The path is documented here so the install instructions are correct in advance; until v3.6.5.2 ships, prefer Methods 1, 2, or 3.docs/SETUP.md:233 Method 3 prereqs missingProblem: Current line is one sentence: "Requirements: Claude Desktop (latest version) with Cowork enabled; paid plan."
Authoritative source: Cowork getting started + requirements — https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork
Fix: Expand into a **Prerequisites** subsection covering:
docs/SETUP.md:241 Method 4 prereqs missingProblem: Current line is one bullet: "1. Sign in to claude.ai (requires a paid plan)".
Authoritative sources: - GitHub integration (auth, App authorization, Team/Enterprise enablement): https://support.claude.com/en/articles/10167454-using-the-github-integration - Connectors setup: https://support.claude.com/en/articles/10168395-set-up-claude-integrations - Custom Skills packaging (4a): https://claude.com/docs/skills/how-to
Fix: Expand into a **Prerequisites** subsection (apply to both 4a and 4b where relevant) covering:
<skill-name>/SKILL.md; upload via Settings → Capabilities → Skills. Note that zip structure errors and the 200-char description cap will surface as upload-time errors per the Custom Skills doc.docs/SETUP.md:217-218 Cowork UI terminology driftProblem: Current text says: "click Cowork tab (top bar)" and refers to a "working directory". Both wrong against current Cowork UI.
Authoritative sources (use the literal labels from these pages — do not paraphrase): - Cowork access (mode selector wording): https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork - Cowork Projects (left nav, "Use an existing folder", Cowork Project): https://support.claude.com/en/articles/14116274-organize-your-tasks-with-projects-in-claude-cowork
Fix: Use current Cowork UI terms:
Walk the reader through each click using the literal current UI labels from the linked Anthropic pages.
docs/SETUP.md:231 Trigger phrase oversimplifiedProblem: Current text says skills are invoked "via trigger phrases". True but incomplete — Cowork now also surfaces installed plugin Skills via the / command palette and the + (add capability) visual UI. The audit also notes that "trigger phrase" is itself a slight overstatement: Claude uses the skill description to decide relevance, not literal trigger-phrase matching.
Authoritative sources:
- Skills invocation (Claude uses description for relevance, not literal trigger matching): https://code.claude.com/docs/en/skills
- Cowork Skills via plugins (/ and + UI): https://support.claude.com/en/articles/13837440-use-plugins-in-claude-cowork
Fix: List three discovery surfaces and correct the trigger-phrase framing:
description and routes the user request to whichever skill it judges most relevant. The example phrases in the SETUP table are illustrative, not literal triggers./ command palette in Cowork: type / and the four skills appear as completions for explicit invocation.+ capability picker in Cowork: visual UI to add a skill to the current Task.Reader should know that explicit / and + UI exist as a fallback when description-based routing does not pick the desired skill, and that paraphrased intent ("help me draft a paper") works equally well as the example phrases.
docs/SETUP.md:243-255 Method 4 directory table omits scripts/ + capacity outdatedProblem: Current Method 4 directory table omits scripts/, but adapter and validator workflows live there and break without it. The audit also notes the section's capacity rationale references a 200-file cap that conflicts with current Anthropic Project limits (the audit team did not actually find the 200-file claim on line 235-264 — it may already have been removed in an earlier doc rev — but the surrounding capacity guidance is shaky and needs a refresh against current limits).
Authoritative source: Project file limits (per-file 30 MB; file count unlimited subject to total content/context limits) — https://support.claude.com/en/articles/8241126-upload-files-to-claude
Fix:
scripts/ row to the directory table with rationale "literature_corpus[] adapters (folder_scan, zotero, obsidian) + schema validators; required for Material Passport corpus mode and CI-style validation."The hotfix branch already has banners on Method 3 and Method 4 (commit d176578). After the rewrite addresses F1-F7, the banners must come out. Their purpose was harm reduction during the patch interval; once the instructions are correct, the banners are noise.
Drafter responsibility: prepare banner removal as part of the SETUP.md rewrite diff. The drafter does not commit (per §1.4 — public repo, drafter never commits directly). The human maintainer reviews the diff and decides whether banner removal goes in the same commit as the F1-F7 rewrite (atomic) or as a separate commit immediately after (cleaner history). Recommended commit message if separate: "remove banners superseded by v3.6.5.1 SETUP rewrite".
After SETUP.md is fixed, grep the rest of the repo for install-method mentions and align:
grep -rn -E "Cowork|claude\.ai|claude\.com/product/cowork|GitHub integration|\.claude/skills" \
README.md README.zh-TW.md QUICKSTART.md .claude/CLAUDE.md docs/ \
--exclude-dir=design
Any hit inside the §1.6 allowed-edit set that contradicts the v3.6.5.1 SETUP.md must be aligned. Hits outside the allowed-edit set are report-only per §1.6: list them in the validation report for human review, do not auto-edit. Files known to potentially need touch (verify; update only if drifted):
README.md — Quick Start / Installation sectionREADME.zh-TW.md — same as EnglishQUICKSTART.md — if it exists and mentions Cowork or claude.ai.claude/CLAUDE.md — Skills Overview table is unlikely to need changes (no install instructions there), but checkdocs/SETUP.zh-TW.md — mirror EN changes if zh-TW exists (may or may not — check first)Files NOT to touch in v3.6.5.1: anything under */agents/, shared/, scripts/, tests/, individual SKILL.md files.
Validation has two tiers: required (filesystem path-shape) and optional (live discovery). Required must pass before opening PR; optional is documented when environment supports it, otherwise reported as "not validated in this run" without blocking ship.
The drafter / validator MUST NOT pollute the developer's real ~/.claude/skills while validating instructions. Two acceptable approaches:
tmpdir=$(mktemp -d) then run validation steps with HOME=$tmpdir. Filesystem checks resolve against $tmpdir/.claude/skills/. Cleanup is rm -rf $tmpdir when done.mv ~/.claude/skills ~/.claude/skills.backup-pre-v3.6.5.1-validation, run validation, then rm -rf ~/.claude/skills && mv ~/.claude/skills.backup-pre-v3.6.5.1-validation ~/.claude/skills after. Riskier — if the validation step fails partway, the backup might not get restored. Disposable HOME is preferred.Document which approach was used in the validation report.
These steps verify that the corrected SETUP.md instructions produce the right paths on disk. They do NOT require Claude Desktop, Claude Code session, Cowork, or claude.ai access.
For each install method below, run the exact commands from the v3.6.5.1 SETUP.md draft (no edits, no shortcuts) inside the protected environment from §5.0:
<project>/.claude/skills/deep-research/SKILL.md exists at the expected path and is the file from the repo (not a placeholder). Repeat for the other three skills.~/.claude/skills/deep-research/SKILL.md resolves (test with test -f, not ls -L, to follow symlinks). Confirm readlink shows the absolute path back to the cloned repo. Repeat for all four skills.~/.claude/skills/deep-research/SKILL.md exists, is a regular file (not symlink), and content matches <repo>/deep-research/SKILL.md (e.g. diff returns 0). Repeat for all four skills.All three must pass. If any path-shape check fails, the SETUP.md instructions are still wrong and the rewrite is not done.
These steps verify that platforms actually discover the installed skills. Run them only when the corresponding platform is available; otherwise mark as "not validated in this run" in the validation report.
$HOME from §5.0 set as the active HOME for the Claude Desktop session, restart Claude Desktop, switch to Cowork mode, confirm the four skills appear under the + capability picker. (Available only if Claude Desktop is installed and Cowork is enabled on the account.)The validation report is a Markdown block included in the PR description (or attached as a file under examples/v3.6.5.1-validation/ if it is large). Required content:
Open the PR only after steps 1-3 pass. Steps 4-7 results inform reviewers but do not block.
After the SETUP.md draft is complete (and sweep is done):
codex exec --sandbox read-only with a verification task: "Apply the v3.6.5.1 brief constraints; flag any deviation. Output severity-tagged findings."Ship gate (refined from feedback_codex_iterative_spec_review_to_zero.md discipline for the doc-patch context):
Reviewing prose against a brief is what Codex is good at; reviewing prose against vague stylistic preferences is not. Keep the brief as the contract. When Codex raises a P3 that the brief does not actually constrain, accept-with-rationale rather than re-engineering the brief mid-iteration.
When opening the PR, the body should:
eb240b4 for the patch sequencing decisionDo NOT reference internal terminology (e.g. "blast radius", "Codex second-opinion"). PR is public-facing.
These are intentionally left to the drafter's judgement:
These are explicitly delegated; no follow-up question needed.