workspace
Start (initialize) an Asta workspace for a research project, show the user the agent's work on it and save iterations on the user's behalf. Scaffold rendering and deploy infrastructure (Quarto, GitHub Pages, dev container), create Markdown slide decks alongside papers, show rendered output, and save iterations. Doesn't handle research execution (use `asta-flows`).
How do I install this agent skill?
npx skills add https://github.com/allenai/asta-plugins --skill workspaceIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a comprehensive workspace manager for research projects, developed by allenai. It manages Quarto projects, LaTeX papers, and slide decks, integrating with GitHub and Overleaf. Security analysis found no malicious patterns; all operations are consistent with its documented purpose.
- Socketwarn
1 alert: gptAnomaly
- Snykwarn
Risk: MEDIUM · 1 issue
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Workspace
Manage the writing/docs side of a research project: scaffold infrastructure as needed, show the rendered work, save iterations. For managing the research task graph itself (planning, executing typed tasks), use asta-flows.
assets/DEVELOPER.md is the shared developer guide. Link to it from the project README at the selected asta-plugins ref; do not copy generic instructions into every project. This SKILL.md is the agent-specific procedure.
Your first reply when a workspace starts in a GitHub repo, or gets one, is a short message. Asked to start a workspace in a new or empty repo, to create its repo or to share a workspace that has none, read repo setup and send its message, and nothing else: no plan or questions first. A repo that already holds a project keeps its own setup; check its defaults as Overleaf sync setup does. Asked to pair a paper with Overleaf, likewise send Overleaf sync setup's.
Show the user the rendered work
Give the user a web URL for the rendered work. Two URL sources, pick based on your context:
- Local agent (host, local dev container, or Codespace — the user can reach your port): run
make previewin the background. Pass the URL Quarto prints (localhost on host/dev container; Codespaces-forwarded URL in a Codespace). - Headless agent (no user-reachable port): push the branch (see Save), then
make deployed-urlto fetch the deployed URL from GitHub Pages CI.
Run asta workspace what-changed [ref] and share the page.
Before landing paper changes
Before merging a paper PR or pushing paper edits directly to the default branch
where allowed, check for an open PR labeled asta:overleaf-sync. Let it merge
first so newer co-author edits conflict on your change before it lands. If it
has not caught up, run asta workspace overleaf sync --wait 1800 where the
Overleaf token is available (in the background is fine; act on its final
Sync outcome: line and exit code), then update your branch. Sync the same way
before editing the paper and after merging a paper PR. Resolve a sync conflict on
that PR and rerun its checks; do not bypass it by advancing the .asta/overleaf
pairing record manually.
For scheduling and repository status, read
Overleaf sync; for invited-coauthor
access, setup; for lock recovery,
Interrupted runs.
Save
git add + git commit -m "<concise message>". Don't git push without explicit user approval.
Before opening any workspace PR, both local and headless agents run make check. The pin in .github/workflows/docs.yml works like a lockfile: outside CI and the Overleaf sync runner, make check moves a release pin that is behind the installed asta forward and prints Moved the workspace pin ..., without committing. CI and Overleaf runs keep the committed pin; a headless agent outside those runners uses the same pin update flow as a local agent.
- Commit your work, then run
make check. - If
make checkpassed and moved the pin, commit only that change as its own commit:git commit -m "Move workspace pin to asta-plugins@<release>" -- .github/workflows/docs.yml. - If
make checkfailed after moving the pin, leave the move uncommitted and run it again on the old release, pinned by commit so sync leaves it alone. Resolve the old release's commit withgit ls-remote https://github.com/allenai/asta-plugins.git 'refs/tags/<old release>^{}'; if that exact peeled ref is absent, usegit ls-remote https://github.com/allenai/asta-plugins.git 'refs/tags/<old release>'for a lightweight tag. Require one full 40-hex SHA before replacing the ref indocs.yml, then runmake check. If that passes, the new release broke the build: commit the SHA pin as its own commit and say in the PR that the pin holds the old release and why. If it fails too, the new release isn't the cause:git checkout -- .github/workflows/docs.ymlrestores the old release (no pin commit has been made); fix the build and repeat the check before opening the PR.
For a headless agent (the user only sees results via deployed URL):
- Bootstrap
mainif the repo is empty. Follow repo setup, including its managed settings, private Pages check and initial-history reconciliation. On a repo with no commits, the first branch pushed becomes the default — establishmainbefore pushing a feature or Pages branch. A README created on GitHub has its own history; fetch and merge it into an existing local workspace before pushing, preserving the workspace's files and commits. Never force-push past it. - First save: keep the pin current (above), then
git push -u origin HEAD:<feature-branch>,gh pr create --fill, thenmake deployed-urland report the URL. - Subsequent saves:
git push,make deployed-url. - After explicit merge approval:
gh pr merge,make deployed-url.
Don't merge a PR without explicit user approval.
Overleaf sync refusals
When asta workspace overleaf pull or publish refuses, or a sync PR conflicts, follow the section its message links in workflows/overleaf-recovery.md.
Scaffold components as needed
Add components only when needed; don't proactively offer them, except when you create a workspace's GitHub repo or set up one that exists but is empty (asked to share it, a Codespace, or a remote start in an empty repo). Then apply Asta's managed settings without asking about them: follow workflows/repo-setup.md.
| Component | When to add |
|---|---|
| Quarto build tool | Always — it's the project structure. |
| Version workflow stub | Always for managed rules; enable automatic Pages deploy only when needed. |
| GitHub Pages deploy | When you have no user-reachable port, the user asks for a deployed URL, or the owner accepts the repo defaults. |
| Dev container | User wants to avoid installing host dependencies, or wants browser-only access from another machine. See subsection for the two flows. |
Before writing any file in the steps below, check whether the target path already exists. If it does, ask the user before overwriting, or merge the asset's contents into the existing file.
Quarto build tool
- Copy
assets/_quarto.ymlto project root; fill{{TITLE}}and{{REPO_URL}}(use the canonical GitHub URL, e.g.https://github.com/{owner}/{repo}). - Create
index.qmdwithtitle:frontmatter. - Create empty
references.bib. - Copy
assets/evidence.ymlto the project root (the keyed quote store — keep it even while empty). The Makefile fetches the evidence extension and Asta theme from this repository before each render; keep both managed rather than copying their extension directories. The scaffold opens in dark mode regardless of the reader's system setting and includes a persistent toggle to light. Both modes use the same typography and layout, with pinned section headings on long pages. Preserve a project's owntheme:and CSS; see the developer guide's Site appearance section for customization. See Back claims with supporting evidence below. - Append any lines from
assets/gitignoremissing from the project's.gitignore(create it if absent; don't overwrite existing entries). - Copy
assets/Makefile.managedasMakefile. Shared rules and scripts are fetched byasta workspace syncinto ignored.asta/cache/; do not createscripts/or copy helpers unless the user wants to customize them. A project-ownedworkspace.mkorscripts/<name>takes precedence. Preserve existing project targets when adopting the scaffold. - Add the thin
assets/docs.ymlworkflow stub even for local-only projects: it selects the managed version. For local-only use, or until Pages setup verifies the agreed site visibility, remove itson.pushandon.pull_requestevents and useon.workflow_dispatchso publishing requires manual activation. Keep thejobs.docs.usesline; sync reads it. Preserve an existing version policy (@maincanary,@latestrelease channel, or a fixed release/commit). Do not upgrade or repin it as part of unrelated setup. - Copy
assets/README.md; fill{{TITLE}},{{DESCRIPTION}}and{{ASTA_PLUGINS_REF}}. Use the ref in.github/workflows/docs.ymlfor the guide link. The upstreamlatestbranch tracks the released guide; verify the link for a custom ref. - Run
asta workspace sync --require-scripts, thenmake check. Keep customized copies. Before removing old unmodified helpers, require a successful refresh and validate the project from an empty cache. - Show the user the new site as Show the user the rendered work says (a local agent runs
make previewin the background and gives its URL), so that they see their workspace as it starts rather than being told how to open it. - To keep the paper in step with an Overleaf project, follow
workflows/overleaf-sync.md.
Separate LaTeX paper (optional)
Add this only when the user wants to write LaTeX directly. Quarto-to-PDF remains an on-demand quarto render <page>.qmd --to pdf; do not create or commit its generated .tex, PDF, HTML or viewer pages.
- Copy
assets/paper/main.texandassets/paper/latexmkrcintopaper/(or the chosen paper directory), preserving existing paper sources and engine settings. Fill{{TITLE}}, escaping LaTeX special characters such as&,%,_,#,$, braces and backslashes. When built from the paper directory, the rc searches upward forreferences.bib, stopping at the Git root; add citations as references become available and uncomment the starter's bibliography line. An empty project builds without a reference list. Keep the separate paper's writing independent from the Quarto pages.project.mdbelongs to asta-assistant'sbrainstorm, not this scaffold. - Append missing entries from
assets/paper/gitignoreto.gitignore, replacing{{PAPER_DIR}}with the chosen relative directory (paperby default). Repeat for each paper, including nested directories; escape any Git ignore pattern characters in directory names. The source and rc are committed; build outputs and generated viewers are ignored. A committed custom viewer still wins after its ignore rule is removed. - Use the
-teximage in the dev container. It supplies TeX, LaTeX Workshop and editor defaults; do not copy.vscode/settings.json. Retain the project's chosen version/channel when selecting the image. - The shared rules provide
make paperandmake paper-clean;PAPER_DIR=<directory>selects another paper. Existing projects on older refs can keep their own targets until upgrading to a ref that provides these. Projects can override a target or ejectworkspace.mk. - The managed viewer is
<paper-dir>/html/index.qmd. Add it toproject.renderonly when the project has an explicit render allowlist, and link<paper-dir>/html/index.htmlfrom the site. Keep existing page lists/navbar entries. Shared viewer generation handles the required JavaScript resource; do not commit viewer source. - Run
make paper(withPAPER_DIRfor a non-default directory) andmake check. If the selected released rules do not yet providepaper, use(cd paper && latexmk -synctex=1 -interaction=nonstopmode -halt-on-error -file-line-error -outdir=build main.tex)with the chosen directory, or LaTeX Workshop instead; do not silently change the project's ref or add a copied Make recipe. The shared CI paper preview already works on these older refs. With Pages enabled, verify the PR preview's paper PDF, its paper page and What changed. One TeX image supports multiple papers: discovery findsmain.texwith a neighboringlatexmkrc, including nested directories.
Slide decks (optional)
When the user asks for slides, use Quarto reveal.js via the managed
asta-slides extension. Copy assets/slides/slides.qmd into a deck's own
folder under slides/ (for example slides/findings/slides.qmd), fill its title and write the
talk in Markdown. Keep images, optional SCSS, scripts and Reveal plugins beside
that source. Several deck folders are supported at any depth; slides/<name>/ is the convention.
The build generates a viewer page beside each deck (<deck-dir>/index.qmd, uncommitted, as for papers) that plays it inside the site at 16:9, with expand, Esc, Reveal's navigation keys working without a click into the deck, and a pop-out button that opens slides.html on its own at the current slide; link that page from the sidebar and overview. Append assets/slides/gitignore to .gitignore with {{DECK_DIR}} replaced by the deck's folder (escape Git ignore pattern characters); the build also adds that line when it is missing. Commit a custom index.qmd to override it. A deck can't live in a paper's html/ folder: the build skips it there with a warning.
Use # for section headings, ## for slides, and Reveal's usual fragments for
builds. asta-slides: {section-slides: false} makes # headings name
sections for the headline only, with no divider slide (as Beamer's \section).
.dim-previous optionally dims previous fragments. The extension adds
the Asta theme, 16:9 dimensions, a slide number (and arrows, when Quarto's
controls: auto shows them) inside the slide, and a headline listing every
section with the current one highlighted (section-header: current shows only
the current name). section-header: false hides the line while preserving the
title spacing for a deck's own content. No section headings means no section line. Keep all deck additions in slide units, never vw/vh or window-fixed
positioning. For SCSS variables, independent opt-outs and ejection, see
assets/_extensions/asta-slides/README.md.
Before the first fetch in an existing workspace, append _extensions/asta-slides/
to its .gitignore if missing (preserve existing entries). Remove that entry
only when deliberately committing an ejected extension.
make workspace-assets fetches the extension from the selected workspace ref;
make check renders decks with the site. Preserve existing render and navigation
lists: if either is explicit, add the deck to it. In an explicit sidebar, label
the entry text: "Slides: <title>" with the deck as href, and word links from
other pages as slides (for example "Presentation slides"), so readers know a
link opens a deck rather than a page. An explicit project.render
list needs each deck's <deck-dir>/slides.qmd and <deck-dir>/index.qmd (or globs
covering every deck folder, wherever it is), or a single-file
quarto render slides/<name>/slides.qmd runs outside the project and cannot find
the site-root _extensions/asta-slides. The default automatic sidebar
links decks by title. Each deck publishes as <deck-dir>/slides.html; its PR
preview has the same path, and What changed lists slide-level differences with
links to the changed slides.
Share the rendered slides.html as the standalone page: fonts, scripts and math
are embedded by default. The claude.ai artifact viewer currently refuses its
data: stylesheets, so sharing on that host is outside this feature's scope.
Back claims with supporting evidence
The scaffold fetches a small Quarto extension (_extensions/evidence/) from asta-plugins before each render rather than vendoring a copy that can drift. Managed projects use the ref selected in .github/workflows/docs.yml; change that one ref and run make update-workspace to upgrade. A standalone, ejected Makefile can set ASTA_PLUGINS_REF separately. The extension lets a factual claim in the prose carry the evidence backing it: the claim gets a subtle dotted underline, and hovering (or keyboard-focusing) it reveals a verbatim quote plus a body-style citation. It renders with pure CSS — so it also survives onto the what-changed diff page, where a reviewer can check each claim's backing without leaving the diff.
When you write a claim you looked up, back it: add a keyed entry to evidence.yml with the verbatim quote, its cite key (add the paper to references.bib), an optional native citeproc locator (p. 4, sec. 3.2, abstract, …), and optional provenance:. Provenance must record only observed facts: use the exact CLI subcommand (for example, asta papers snippet-search) as method, use the canonical asta:// URI returned for an indexed Asta document as url, and omit unknown fields rather than inferring a skill or producer name. Then mark the claim in the .qmd:
NatureBench has [90 tasks]{.ev key="naturebench-count"}.
Only ever put a verbatim quotation in quote: — there is no paraphrase mode; state your own wording in the prose. Full field reference and design notes are in _extensions/evidence/README.md.
Structural validation of these entries belongs in deterministic build tooling. Whether a claim needs evidence at all, and whether a quote actually supports the claim as worded, is a judgement call — load the check-claims skill for that, both before you open a PR and when reviewing one.
GitHub Pages deploy
- Use the
.github/workflows/docs.ymlstub added by Quarto build tool; do not copy it a second time. For a site in a subfolder, keep the one stub at the repository root withsite-dirnaming the subfolder; GitHub runs only root workflows, andasta workspace syncand the pin move use that root stub, so add nodocs.ymlunder the subfolder. Keep it manual-only until the Pages visibility check below succeeds, then enableon.pushandon.pull_request. It's a thin stub — the build/deploy/preview machinery lives in this repo's reusable workflow (.github/workflows/workspace-quarto-site.yml), so scaffolded projects pick up fixes without re-copying. Project-specific quality gates go in the project'smake checktarget, which the reusable workflow calls. When adopting an existing project, follow Quarto build tool to merge the stub and aMakefilewith achecktarget; preserve its version policy and existing rules. - Follow GitHub Pages setup before pushing or enabling the workflow: the site is made private and read back before any content reaches it. If it can't be private, or the owner wants it public, stop and ask the owner how to proceed.
- For a repo set up outside
workflows/repo-setup.md: recommend repo protections (default-branch rulesets, required docs checks). Readworkflows/repo-protections.mdand follow it before proposing or applying any.
On every PR the workflow publishes a full rendered preview under
<pages>/pr-preview/pr-<N>/ and a what-changed.html beside it. The latter
highlights rendered additions and removals against the deployed base site and
collapses unchanged sections. The single preview comment links to the changes
first and the full preview second, so reviewers can inspect the affected
content directly.
Dev container
Copy assets/devcontainer.json to .devcontainer/devcontainer.json. If the project has a paper/, change image to the -tex variant (ghcr.io/allenai/asta:latest-tex, or <version>-tex when pinned) so LaTeX Workshop builds with the same TeX packages as the PR preview. The -tex image adds the LaTeX Workshop extension through its dev container metadata, so do not list it in devcontainer.json; one image covers any number of papers. Then pick the flow that matches the user's intent:
- Local container (working on their machine without installs): run
make devto open VS Code attached to the local container. - Codespaces (browser-based access from anywhere): commit, push to a GitHub remote (creating one if needed, with repo setup), then
gh codespace createand give the user the URL. Authenticate withasta auth loginin the codespace terminal (persisted across rebuilds) or the optionalASTA_TOKENCodespaces secret. Port 4848 raises a notification (onAutoForward: notify) and the forwarded preview URL is printed in the attach terminal. Open either link in a separate browser tab.localhost:4848in Simple Browser does not reach a browser-based codespace's forwarded port, and a private forwarded URL may fail in its embedded frame. Local VS Code can use Ports → Preview in Editor.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/allenai/asta-plugins/workspace">View workspace on skillZs</a>