manuscript-scaffold - SKILL.md Agent Skill

name: manuscript-scaffold description: Scaffold a LaTeX manuscript directory for a research project — copy the bundled skeleton (main.tex + sections/* + figures/ + references.bib + .gitignore + README), optionally apply a journal-specific documentclass from templates/journal-registry.json, optionally clone an Overleaf project and cache the Git credential helper (token never persisted to tracked files), commit on the default branch, and ask before pushing. Invoked by /start-research phase 6, but also standalone-callable when adding a manuscript dir to an existing project later.

Set up a LaTeX manuscript directory with optional journal-template customization and optional Overleaf Git integration. The heaviest, riskiest sub-flow inside /start-research (filesystem mutation, external archive fetches, credential handling, network push) — extracted into its own skill so the four sub-steps live in dedicated phase files for clarity, easier security review, and safer maintenance. - `/start-research` reaches phase 6 and the user did not opt out of manuscript scaffolding. - A project that was set up with `Manuscript dir` empty later wants to add a manuscript directory without re-running the full `/start-research` interview. - An existing manuscript directory needs to be wired up to a fresh Overleaf project (re-invoke with the new URL — the skill detects existing state and asks before clobbering). - The user wants only journal-template metadata captured in `CLAUDE.md` without creating files (no skeleton, no commit) — that is a `CLAUDE.md` edit, not this skill. - The manuscript dir already has substantive content and the user is not asking to scaffold (phase 1 will stop anyway, but don't invoke if you already know). - The project explicitly opted out of LaTeX (e.g. plain-markdown-only workflow). This skill is LaTeX-shaped. Inputs are resolved by the caller (typically `/start-research`) from the project's `CLAUDE.md` blocks, or passed directly when the skill is invoked standalone.

Input	Required	Source	Used by
`MANUSCRIPT_DIR`	yes	`## Research stack` → `Manuscript dir` (default `paper/`)	all phases
`TARGET_VENUE`	no	`## Project context` → `Target venue`	phase 2 (journal lookup)
`OVERLEAF_GIT_URL`	no	`## Research stack` → `Overleaf git URL`	phase 3 (clone), phase 4 (push target)
`WORKING_TITLE`	no	`## Project context` → `Working title`	phase 3 (README seed)
`CLAUDE_PLUGIN_ROOT`	yes	env var (set by Claude Code)	phase 2 (registry path), phase 3 (skeleton source)

When invoked standalone (not from /start-research), if MANUSCRIPT_DIR is not given, read the project's CLAUDE.md ## Research stack block. If still missing, stop and ask the user.

Phases

Execute in order. Each phase is a separate file — read it, follow it exactly, then return here for the next phase.

Phase 1 — State check. Read phases/01-state-check.md. Decide whether to proceed, stop and ask the user, or skip (existing-content path).
Phase 2 — Journal template lookup. Read phases/02-journal-template.md. Match TARGET_VENUE against the bundled registry; on user-confirmed match, prepare the documentclass / bibstyle rewrite values for phase 3. Skip if no venue.
Phase 3 — Skeleton (with or without Overleaf). Read phases/03-skeleton.md. Branches internally on whether OVERLEAF_GIT_URL was provided.
Phase 4 — Commit and ask before push. Read phases/04-commit-push.md. Always commit locally; only push on explicit user confirmation (default no on empty input).

If phase 1 stops the flow (existing content, user declines), do not run phases 2–4. Report what happened and return control to the caller.

Security invariants (apply across all phases)

No .cls files bundled in this plugin. Phase 2 may swap a \documentclass line in the skeleton copy only; any .cls archives a user opts into fetching go into the user's MANUSCRIPT_DIR, never into the plugin repo.
No silent network calls. Phase 2's URL-fetch fallback runs WebFetch only when the user passes an https:// URL and confirms the SHA256 of the downloaded archive before extraction.
No fuzzy venue matching. Phase 2 matches case-insensitive exact against the registry name and aliases. A near-miss is a miss.
Overleaf token never written to a tracked file. Phase 3 stores the token only in git credential-store (scoped to git.overleaf.com) or ~/.netrc. Never write the token into CLAUDE.md, agent memory, the project repo, or this plugin. When referencing the token in any output, mask all but the last 4 chars.
No auto-push. Phase 4 always asks; default on empty input is no. On push failure, leave the local commit in place and surface the exact retry command.

Return value (for the caller)

After phase 4 (or early stop), return a structured summary in this shape so the caller can fold it into its own report:

Manuscript scaffold: <created | skipped | stopped at phase N>
  Manuscript dir:    <path> (<created | existed empty | existed with content — skipped | overleaf clone>)
  Journal template:  <applied <class> + bibstyle <style> | not applied | no venue>
  Overleaf:          <connected to <masked URL> | local only | not configured>
  Branch / commit:   <branch> @ <short-SHA> (<pushed | push deferred | no remote>)
  Deferred push:     <exact `git -C <dir> push origin <branch>` command, only if push deferred>

The caller (e.g. /start-research phase 6) merges this into its end-of-run report.