# ARS v3.6.5.2 — claude.ai Method 4a scope clarification — Implementation Brief

**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

---

## Purpose of this document

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).

---

## §1 — Why the trim direction was abandoned

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.

### 1.1 The 200-char cap is a claude.ai client limit, not a spec limit

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.

### 1.2 Trimming would lose Claude Code / Cowork routing signal

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.

### 1.3 Method 4a's runtime scope is narrower than Claude Code's

claude.ai Custom Skills support multi-file packages with `scripts/` and code execution per Anthropic's [Custom Skills documentation](https://claude.com/docs/skills/how-to) and [How to create custom Skills](https://support.claude.com/en/articles/12512198-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:

- **Claude Code Task / subagent dispatch**. Each ARS skill drives 12-13 specialised agents through Claude Code's Task / Skill tooling. The Anthropic [Use Skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude) doc describes claude.ai skill activation but does not document multi-agent dispatch via Task / subagent on the claude.ai surface.
- **Material Passport cross-session handoffs**. ARS pipelines record state in a Material Passport YAML and resume across Claude Code sessions. claude.ai's containerised code-execution environment is per-session; cross-session passport resume is not part of the documented Method 4a contract.

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.

### 1.4 Method 4b remains valid for claude.ai users

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.

---

## §2 — What v3.6.5.2 ships

### 2.1 SETUP.md Method 4a section rewrite

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:

- State plainly: Method 4a is the standard claude.ai Skill install path, but it is not the recommended path for ARS.
- Give the rationale at one paragraph of depth (mirror §1.2 + §1.3 in user-readable form). Do not link to this brief — the rationale must be self-contained for a reader who arrives via the SETUP doc.
- Point users at alternatives: Method 3 (Cowork) for agentic skill execution on desktop; Method 4b (Project + GitHub) for claude.ai web access without Skill install. Method 1 and Method 2 remain the primary paths for Claude Code projects.
- Keep the install commands present in the section (the `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.
- Drop the inline phrasing "the description trim ships in a follow-up patch (v3.6.5.2)". That sentence was a v3.6.5.1-era forward-promise. v3.6.5.2 is no longer that patch; the sentence is obsolete and misleading.

### 2.2 SETUP.zh-TW.md Method 4a section mirror

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 "吾人").

### 2.3 CHANGELOG.md v3.6.5.2 entry

Append above the v3.6.5.1 entry. Cover:

- What changed: SETUP.md + SETUP.zh-TW.md Method 4a recommendation
- Why: rationale summary (~3 lines)
- Note that no SKILL.md, no agent file, no schema, no script, no test changed
- Reference issue #44 with closure deferred to post-merge consolidated reply

### 2.4 What v3.6.5.2 does NOT change

- No `SKILL.md` (frontmatter, body, metadata) anywhere
- No `.claude/CLAUDE.md` (Skills Overview table stays)
- No `MODE_REGISTRY.md`
- No agent file under `*/agents/`
- No schema under `shared/`
- No script under `scripts/` (no new lint, no edits to existing lints)
- No test under `tests/` or `scripts/adapters/tests/`
- No README badge update
- No `.github/workflows/` changes
- No version bumps anywhere (the four skill semvers stay; the suite semver in `.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.

---

## §3 — Authoritative sources (cite in SETUP.md prose where relevant)

When SETUP.md prose makes a claim about platform behaviour, cite the upstream doc:

- claude.ai 200-char Custom Skills cap: https://claude.com/docs/skills/how-to
- Agent Skills specification (1024-char ceiling, canonical frontmatter fields): https://agentskills.io/specification
- Claude Code Skills (description usage, listing budget, additional fields): https://code.claude.com/docs/en/skills
- Cowork install + Plugins UI: https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork and https://support.claude.com/en/articles/13837440-use-plugins-in-claude-cowork
- claude.ai Projects (knowledge mode): https://support.claude.com/en/articles/9517075-what-are-projects
- GitHub integration: https://support.claude.com/en/articles/10167454-using-the-github-integration

The drafter MAY paraphrase Anthropic's guidance but must cite the source for every factual claim about platform behaviour.

---

## §4 — Public repo + Ruleset constraints

`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 花花 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.

---

## §5 — Validation gate

This patch is doc-only. Validation is light.

### 5.1 Required: link check

For every URL introduced or retained in `docs/SETUP.md`, `docs/SETUP.zh-TW.md`, and `CHANGELOG.md`, run:

```bash
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.

### 5.2 Required: EN anchor link check

`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.

### 5.3 Required: claim-source matrix for Method 4a runtime statements

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.

### 5.4 Required: prose self-check

The drafter rereads §2.1's replacement Method 4a section and confirms:

1. A reader arriving cold (no prior context) understands that Method 4a is technically possible but not recommended.
2. The rationale answers "why not" without requiring the reader to read this brief.
3. The alternative paths (Method 3, Method 4b) are pointed at clearly.
4. The install commands are still present for a user who wants to try Method 4a, including the zip-root packaging constraint.

Document this self-check as a one-paragraph note in the validation report.

### 5.5 Required: zh-TW prose mirror

Diff §2.2 zh-TW changes against §2.1 EN changes. Confirm:

- Same structural sections present
- Same factual claims made (especially the runtime-limitation claims must mirror, not drift)
- Voice is consistent with existing SETUP.zh-TW.md

### 5.6 Optional: live test

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.

### 5.7 Validation report format

Markdown block in PR description:

- §5.1 link check across all three docs: PASS/FAIL per URL
- §5.2 EN anchor link check: PASS/FAIL per anchor
- §5.3 claim-source matrix: each runtime claim with source URL or "forward-looking" note
- §5.4 prose self-check: paragraph per the four sub-questions
- §5.5 zh-TW mirror: PASS/FAIL with diff summary
- §5.6 live upload: PASS/NOT VALIDATED with reason

---

## §6 — Codex review iteration

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:

- Zero P1, zero P2: required
- P3: fix or accept-with-rationale-in-PR

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.

---

## §7 — PR body template

The PR body should:

- Reference issue #44 by URL
- State plainly that v3.6.5.2 is a scope change from "trim descriptions" to "clarify Method 4a recommendation", with one-paragraph rationale
- Show the SETUP.md Method 4a section before/after diff inline (transparency for reviewers)
- Show the SETUP.zh-TW.md mirror diff inline
- Embed the §5 validation report
- State that the PR's merge triggers a consolidated reply on issue #44 closing both v3.6.5.1 and v3.6.5.2

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.

---

## §8 — Issue #44 close protocol (post-merge)

After v3.6.5.2 PR merges:

1. Post one consolidated reply on issue #44 covering:
   - v3.6.5.1 (merged `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.
   - v3.6.5.2 (this PR): Method 4a marked not recommended for this suite, with rationale; Method 4b and Method 3 remain the supported claude.ai-side and Cowork-side paths.
   - Concrete now-working install commands the reporter can copy-paste: Method 3 Option A (symlink) for Cowork, Method 4b (Project + GitHub) for claude.ai web access.
2. Close issue #44 in the same comment.

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.

---

## §9 — Drafter judgement zone

Intentionally left to the drafter:

- Exact wording of the SETUP.md Method 4a recommendation paragraph (within §2.1 + §3 constraints)
- Whether to re-order Method 4a vs Method 4b within the Method 4 supersection (current order is 4a then 4b; flipping to 4b first would emphasise the recommended path; either is acceptable provided the rationale paragraph still calls out the recommendation explicitly)
- Whether to add a one-line "see also" pointer from Method 3 prerequisites to Method 4b for users who explicitly want claude.ai (small UX win, optional)

These are explicitly delegated; no follow-up question needed.
