# Proposal Publish > Build a PDF (or docx fallback) from a proposal file via pandoc — compact layout, typst-first, with install guidance when tools are missing. Also offers a stripped hand-in export, and hands over to a workspace build script where one exists. Use when the user wants a PDF or something to email, print or hand to their supervisor, wants the proposal out of markdown, has a faculty document template to… - **Type:** Skill - **Install:** `agentstack add skill-hutzelmann-thesis-proposal-skills-proposal-publish` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [hutzelmann](https://agentstack.voostack.com/s/hutzelmann) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [hutzelmann](https://github.com/hutzelmann) - **Source:** https://github.com/hutzelmann/thesis-proposal-skills/tree/main/skills/proposal-publish - **Website:** https://www.skills.sh/hutzelmann/thesis-proposal-skills ## Install ```sh agentstack add skill-hutzelmann-thesis-proposal-skills-proposal-publish ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Proposal Publish Builds a PDF from a proposal file — compact layout, typst first, pandoc as the fallback — and can also produce a stripped hand-in export. **Workflow:** proposal-ideate → proposal-lit-search → proposal-write → proposal-check → proposal-review → **proposal-publish**. Also: proposal-import (start from an existing document), proposal-customize (adapt the rules to a supervisor's requirements), proposal-supervise (supervisor-side feedback on a raw submission), proposal-troubleshoot (diagnose a skill that misbehaved). **Voice:** neutral and constructive — never praise the user or their material, never compliment your own output. Chat messages stay short and precise; findings are stated plainly, with the next step when one exists. Publishing is optional — a proposal markdown file is an acceptable hand-in on its own. Never pressure the user into installing anything; offer the paths and their costs. ## Build Run the build script (stdlib-only, ≥3.11): ``` python3 .claude/skills/proposal-publish/scripts/publish.py # PDF via best available engine python3 .claude/skills/proposal-publish/scripts/publish.py --handout # stripped markdown export instead ``` Paths are relative to the workspace root for a standard project install; the script really lives in `scripts/` next to this SKILL.md, so use that location if the skill is installed elsewhere. If you cannot find it, say the script did not run and name what is therefore unverified — never present your own reading of the file as the script's result. The script resolves the best pipeline automatically: **typst** (preferred) → **LaTeX engine** → **docx** (last resort, no PDF), using the skill's `templates/` (compact layout, `RQ n:` styling, citeproc). Outputs land next to the proposal; the script also ensures the workspace `.gitignore` covers build artifacts (shared rule: whichever skill first creates an ignorable artifact adds the entry). Citations render in two forms, both usable in one document: `[@key]` becomes `[1]`, and `@key` becomes `Smith et al. [1]` — the author name derived from the proposal's own reference entry, so it never has to be typed. The filter chain producing this is order-dependent (`author-intext.lua` → `cite-split.lua` → citeproc → `rq-filter.lua` → `todo-filter.lua`); don't reorder it. `[TODO: …]` markers render as numbered annotations rather than prose — a marker alone on its line becomes a callout block, one inside a sentence becomes a highlight, and a marker carried by the title or subtitle is numbered ahead of the body. There is deliberately no option to render them quietly: the way to a marker-free PDF is to resolve the markers, which `proposal-check` already lists. ## Workspace build script A workspace can replace this pipeline with a build of its own — a faculty title page, a mandated cover sheet, a house style. The script looks for one **beside the proposal**, never in a directory above it, in either form: - a file named `proposal-build` with any suffix, or none; - a `Makefile` or `justfile` declaring a `proposal-build` target. A recipe file without that target is ignored, so an unrelated build system in the workspace changes nothing. When one is found, publish **builds nothing** and exits 3, naming what it found. Run that definition and relay its output. It receives exactly one thing: the proposal's absolute path, in `PROPOSAL_PATH`, and — for a build file — as its first argument. The proposal's directory is the output directory. **Exit 3 is a handover, not a failure.** Nothing went wrong: do not offer a bug report for it. **Never fall back to the built-in pipeline when a workspace build fails.** Report the failure and stop. Producing the default layout for a workspace that asked for a different one is the worst outcome available — it succeeds visibly and is wrong invisibly. `--builtin` exists so the user can ask for the built-in document deliberately, for instance to tell a template problem from a content problem; it is never your recovery move. Two definitions beside one proposal are refused rather than chosen between — relay the refusal. Whenever you report a built document, say which pipeline produced it. `--handout` is never delegated: it is a transform of the proposal source, not a rendered document. A minimal build script, as `proposal-build.sh` beside the proposal: ```sh #!/bin/sh pandoc "$PROPOSAL_PATH" --template faculty.typ -o proposal.pdf echo "built proposal.pdf with the faculty template" ``` The same thing as a `Makefile` target, for a workspace that already has one: ```make proposal-build: pandoc "$(PROPOSAL_PATH)" --template faculty.typ -o proposal.pdf ``` ## When tools are missing The script reports what is missing and what it would unlock. Guide concretely, best first: - **pandoc + typst** (recommended, two single binaries): `winget install --id JohnMacFarlane.Pandoc Typst.Typst` / `brew install pandoc typst` / distro packages. Smallest install, fastest builds. - Existing **TeX Live/MiKTeX** works as the LaTeX fallback — nothing extra needed besides pandoc. - Nothing installable? → `--handout` produces a clean markdown for hand-in, or suggest the user's institution machines / a colleague's setup for the final PDF. Relay the script's messages rather than re-diagnosing; on Windows use `py` if `python3` is absent. ## Hand-in guidance - `--handout` strips abstracts from the references block (supervisor-facing file should not be half bibliography database) — citations and entries stay intact. The handout is a deliverable meant to be kept and sent, so it is deliberately **not** gitignored. - Because it is not gitignored, the handout is the one output a user may have edited by hand. The script refuses to replace an edited one and says so; relay that refusal instead of resolving it — renaming the file or discarding the edits is the user's decision, not yours. `--force` is for when they have decided. - docx output uses pandoc's default styling (acceptable last resort; the compact look exists for the typst and LaTeX tiers). - Remind the user to rename the PDF to include their name before sending (supervisors receive many proposals). - If check hasn't run recently, offer it first — but publishing proceeds on user confirmation regardless (check is advisory). ## When this run fails If this run failed in a way you cannot resolve — a shipped script exited non-zero, a step failed repeatedly with no user edit in between, or the state makes no sense — offer a bug report once, in these words, and do not raise it again in the same session: "Something here looks like a defect in the skill rather than in your proposal — `proposal-troubleshoot` can diagnose it and, if it is one, assemble a report you can send." Ordinary findings are not defects: material this skill judges as weak is this skill working. Collect nothing unless the user accepts. A missing `pandoc` or `typst` is not a defect either — it is a toolchain the user has not installed, and the install guidance above is the answer. Make the offer only when the toolchain is present and the build still fails. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [hutzelmann](https://github.com/hutzelmann) - **Source:** [hutzelmann/thesis-proposal-skills](https://github.com/hutzelmann/thesis-proposal-skills) - **License:** MIT - **Homepage:** https://www.skills.sh/hutzelmann/thesis-proposal-skills Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-hutzelmann-thesis-proposal-skills-proposal-publish - Seller: https://agentstack.voostack.com/s/hutzelmann - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.