Date: 2026-04-27
Target release: v3.6.5.2 (patch, doc-only)
Branch: hotfix/v3.6.5.2-clarify-claude-ai-method-4a-scope
Trigger: GitHub issue #44 (philpav, 2026-04-27) — second half of the issue, originally planned as a SKILL.md description trim under claude.ai's 200-character cap. Repositioned 2026-04-27 after design re-examination.
Author: Cheng-I Wu
This brief is the constraint sheet for v3.6.5.2 in its repositioned form. v3.6.5.2 was originally going to trim four SKILL.md description fields below 200 characters so claude.ai's Custom Skills upload UI would accept them. After examining what claude.ai's Method 4a actually offers for this suite versus what trimming costs the platforms ARS was built for (Claude Code and Cowork), the trim direction was abandoned. v3.6.5.2 instead documents that Method 4a is not a recommended path for this suite, points users at the paths that work, and closes issue #44.
This brief replaces the obsolete 2026-04-27-ars-v3.6.5.2-description-trim-implementation-brief.md (deleted on the branch before this brief was committed).
The earlier plan was: trim each of the four description fields from their current 440-842 characters down to ≤200, add a CI lint to prevent regression. This would unblock claude.ai Custom Skills upload (Method 4a). Three findings stopped that plan.
The Agent Skills specification (https://agentskills.io/specification) allows description up to 1024 characters. Claude Code Skills follows the spec ceiling, with a separate 1,536-character listing budget for combined description + when_to_use (https://code.claude.com/docs/en/skills). Only claude.ai's Custom Skills upload UI enforces 200 (https://claude.com/docs/skills/how-to). Trimming to 200 across the suite means the strictest client dictates what every client sees.
ARS is a Claude Code-native suite. The four current descriptions front-load function, modes, and trigger keywords because Claude reads description to decide which skill to load when the user types a request. The four skills span related territory (research, write, review, orchestrate) and need discriminating language to route correctly. Trimming from 440-842 to 200 across the board removes routing-relevant content that Claude Code and Cowork actually use, in exchange for unblocking a path described in 1.3.
claude.ai Custom Skills support multi-file packages with scripts/ and code execution per Anthropic's Custom Skills documentation and How to create custom Skills, so Method 4a is mechanically capable of hosting skills with executable assets. The gap relevant here is not "no scripts" — it is that ARS depends on Claude Code-specific orchestration features that the Anthropic-documented claude.ai Custom Skill runtime does not include:
Method 4a is therefore expected to surface ARS as the SKILL.md body's instructions plus whatever scripts the runtime can execute in one session, without the multi-agent dispatch and cross-session continuation that produce the suite's actual outputs. This is a forward-looking assessment based on the documented claude.ai runtime scope, not a measured failure — we have not run a live upload to characterise the actual surfacing.
Method 4b (claude.ai Project + GitHub integration) brings the entire repo into Project knowledge for retrieval. It is not a Skill install; Claude reads the files for context and citation. For users who want claude.ai to know ARS rather than execute it, Method 4b works without any description trimming.
Replace the current Method 4a section (which currently says "blocked on v3.6.5.2 description trim, prefer Methods 1-3 until then") with a recommendation against Method 4a for this suite. The replacement should:
zip -r block, the upload step list) so a user who decides to try Method 4a anyway has the instructions. Frame the commands as "if you want to try this path despite the limitations" rather than as the recommended flow.Mirror the §2.1 changes in Traditional Chinese. Match the existing zh-TW translation's voice (no AI-style connectors, no over-use of em dash, no "吾人").
Append above the v3.6.5.1 entry. Cover:
SKILL.md (frontmatter, body, metadata) anywhere.claude/CLAUDE.md (Skills Overview table stays)MODE_REGISTRY.md*/agents/shared/scripts/ (no new lint, no edits to existing lints)tests/ or scripts/adapters/tests/.github/workflows/ changes.claude/CLAUDE.md Version Info stays at 3.6.5)The patch is exclusively docs/SETUP.md, docs/SETUP.zh-TW.md, CHANGELOG.md, and this brief itself.
When SETUP.md prose makes a claim about platform behaviour, cite the upstream doc:
The drafter MAY paraphrase Anthropic's guidance but must cite the source for every factual claim about platform behaviour.
Imbad0202/academic-research-skills is public with branch protection on main blocking direct commits (GH013). The drafter does not commit directly. Branch is hotfix/v3.6.5.2-clarify-claude-ai-method-4a-scope (already created and renamed locally on the maintainer's machine).
PR is public-facing. The PR body must not reference internal terminology (no "blast radius", "Codex round-X", "atomic boundary", "home turf" as repo-internal jargon — though the user-facing rationale can describe Claude Code as the platform the suite was built for, which is plain English).
PII / private-content scan before push: confirm no internal organisation names, internal hostnames, or private project identifiers leaked into the changed text. Should be a non-issue because the patch only touches public-facing docs, but verify.
This patch is doc-only. Validation is light.
For every URL introduced or retained in docs/SETUP.md, docs/SETUP.zh-TW.md, and CHANGELOG.md, run:
for f in docs/SETUP.md docs/SETUP.zh-TW.md CHANGELOG.md; do
grep -oE "https?://[^ )\"]+" "$f"
done | sort -u | while read url; do
curl -sIL -o /dev/null -w "%{http_code} %{url_effective}\n" "$url" --max-time 10
done
Expected: every link returns 200 (or a documented redirect to a 200). Anthropic support article URLs occasionally rewrite; if a redirect lands on a working article, that is fine.
docs/SETUP.md introduces in-document anchor links to #method-1-…, #method-2-…, #method-3-…, #method-4b-…. GitHub computes anchors from heading text by lowercasing, replacing spaces with -, and stripping most punctuation. For each [text](#anchor) in docs/SETUP.md, confirm a matching ## or ### or #### heading exists whose computed slug equals the anchor. docs/SETUP.zh-TW.md deliberately does not use anchor links because Chinese-character slug behaviour is fragile across renderers; this is intentional and not a finding.
Any sentence in docs/SETUP.md, docs/SETUP.zh-TW.md, or CHANGELOG.md that describes claude.ai Custom Skill runtime behaviour (what it can host, what it cannot dispatch, how description is enforced, what plans support it) must either (a) cite a specific Anthropic doc URL whose current content supports the claim, or (b) state explicitly that the claim is forward-looking and based on documented orchestration assumptions rather than measured behaviour. The drafter compiles a small matrix per claim — claim → source URL or "forward-looking, no live validation" — and includes it in the validation report. Claims that fail both (a) and (b) must be cut or rewritten.
The drafter rereads §2.1's replacement Method 4a section and confirms:
Document this self-check as a one-paragraph note in the validation report.
Diff §2.2 zh-TW changes against §2.1 EN changes. Confirm:
If the validator has claude.ai access: try uploading one ARS skill via Method 4a. Expected: rejection with description-too-long error, confirming the upload constraint is real and that the SETUP doc's recommendation is grounded. Mark NOT VALIDATED if no claude.ai access.
Markdown block in PR description:
After SETUP.md + SETUP.zh-TW.md + CHANGELOG.md are drafted (all on the renamed branch, not yet pushed), bundle this brief + the three diffs and run codex review. Same gate as v3.6.5.1:
The patch is small (estimate <200 line-diff total). Codex will likely surface P3 wording on the SETUP.md prose more than structural P1/P2; that is fine.
The PR body should:
Title suggestion: fix(v3.6.5.2): clarify claude.ai Method 4a is not recommended for this Claude Code-native suite. Drafter MAY choose a tighter title; keep "v3.6.5.2" + "Method 4a" + "not recommended" or equivalent semantics.
After v3.6.5.2 PR merges:
aea9d24): SETUP.md / SETUP.zh-TW.md / QUICKSTART.md doc rewrite — Methods 1-4 install paths corrected, Cowork prereqs expanded, Method 4 split into 4a vs 4b clarification.Sequenced for v3.6.5.2 ship, not bundled into the v3.6.5.2 PR. The PR closes the work; the comment closes the user's question.
Intentionally left to the drafter:
These are explicitly delegated; no follow-up question needed.