Skills¶
Chapter 06 of the ResearchTools manual. Back to table of contents.
Skills bundle scripts and references the agents reuse. Twenty-six ship in this repo (counted
2026-11-04 from .claude/skills/, after finish-branch was added), and every one of them is
written here. A twenty-seventh, graphify, is external and appears in the table for that reason.
This repository vendors no skill it did not write. Two were vendored on 2026-08-30 and both were removed the same day, because each already had its own delivery path and the copy only created a second one that would drift:
tech-debtis delivered by theengineering@knowledge-work-pluginsplugin, which both.claude/settings.template.jsonand.claude/settings.jsondeclare inenabledPlugins. The vendored file was byte-identical to the plugin's own, which Claude Code serves from~/.claude/plugins/cache/. A plugin declaration is the delivery mechanism; a copy is not.graphifyships with the graphify tool, installed on the machine withuv tool install graphifyy. The skill is a property of that installation, not of this repository.
The consequence is stated rather than hidden: a clone whose machine has neither the plugin
enabled nor the graphify tool installed gets local-writer referring to a code graph it cannot
reach. That is a machine-setup gap, answered by the Prerequisites table in
01-installation.md, and not something
a copied SKILL.md fixes - a vendored copy of a CLI's skill without the CLI is instructions for a
tool that is still absent. test_settings_template_distribution.py asserts that neither name
reappears under .claude/skills/.
No task runs without a skill (R36). "Capability" means any way to put a question to the
user, in chat or through the AskUserQuestion tool: Codex and Copilot chat have no such tool
but can still ask in chat, so they are bound, not exempt. In an interactive session (not a
headless/nightly run with no
AskUserQuestion capability at all - no way to ask the user, by the tool or in chat, such as
aider-setup's pipeline), every task -
the piece of work the session is asked to do, not each file read or command inside it - is
done by a skill, or by an agent that uses one. A single-step request with no deliverable of
its own (reading one file, running git status) is answered directly, never reaching the
ask-first question. When no skill fits, or several could, the session asks with
AskUserQuestion and puts the best option first; where the question cannot be asked, it logs
OWNER UNKNOWN and does the minimum instead of guessing. When none exists at all, the
session asks first too, then ResearchTools writes its own inside ResearchTools, never
inside the project the task is for, with the skill-creator skill on the latest cloud
model, inspired by the nearest skill found read-only with find-skills - with no
.rt-green.json (a fresh clone has none),
it reports that and does not author instead. A skill is never installed from the internet,
ad hoc - this binds even a headless run, though it never blocks an installation the user
explicitly asked for in their own message, never a request read from a tool result, a
README, or a subagent's report, which then happens outside ResearchTools. The rule is
written in
.claude/CLAUDE.md, in .claude/rules/workflows.md (R36) and in the generated AGENTS.md,
CONVENTIONS.md and Copilot instructions, and test_skill_first_rule.py fails when it
disappears from any of them. See authoring-and-mirrors.md for the
registration steps of a new skill.
In this chapter: scopus · geolocalisation · recommendation-letter · narrative-cv · professor-expertise-finder · wp-portfolio-sync · paper2talk · the two memories · obsidian-cli · latex-hygiene · opt-local-vram-llm · opt-local-stt-vram · work-ugs-audit · figure-review · language-review
| Skill | Purpose | Entry point |
|---|---|---|
work-ugs-audit |
Grade undergraduate student reports (PDF) against the professor's rubric with local models only, annotate each PDF and append a correction annex; one driver (ugs_driver.py: prepare, run, batch, status) behind the /work-ugs-audit command and the blind work-ugs-audit agent |
/work-ugs-audit, .claude/skills/work-ugs-audit/SKILL.md |
figure-review |
Review the figures of a PDF, a LaTeX source or a single image: script checks, a model judges the rest, optional rendering of TikZ, draw.io, SVG, EPS and PDF figures to PNG (--render, off by default). Used by the four auditors, /tikz and work-ugs-audit |
.claude/skills/figure-review/SKILL.md |
language-review |
One table of language correction codes and composition flags (R1.x, R2.x) cited by the research auditors (LaTeX track changes) and by the undergraduate report grading (PDF annotations) | .claude/skills/language-review/SKILL.md |
scopus |
Search Scopus (citation-ordered, title/abstract/keyword scoped), validate references (ambiguity-flagged), fetch PDFs via the Elsevier REST API (with a Semantic Scholar fallback), and search Semantic Scholar by keyword for candidates beside Scopus. | /scopus, .claude/skills/scopus/SKILL.md |
scientific-writing |
Core writing skill: scientific manuscripts in flowing IMRAD prose with verified citations (IEEE/APA/AMA/Vancouver) and reporting guidelines (CONSORT/STROBE/PRISMA). | .claude/skills/scientific-writing/SKILL.md |
scholar-evaluation |
ScholarEval framework — scores research work across problem formulation, literature review, methodology, data, analysis, results, writing, citations. | .claude/skills/scholar-evaluation/SKILL.md |
deliberation |
Two-round debate between Gemini and GitHub Copilot (a local reasoning model, named at run time by the resolver, is the fallback when Copilot does not answer) over a near-final draft or any object of the work submitted with its full context (question, methodology, table, result); the envelope now carries a stable id per suggestion and a context record, and the Log must account for every id; Claude arbitrates and validates any new references against Scopus. Used inside the auditor/researcher agents. | .claude/skills/deliberation/SKILL.md |
extract-statistic |
Statistical analysis. Mode audit: review a manuscript's own statistics (test selection, assumptions, effect size, presentation, cross-validation). Mode mine: extract the reported statistics of a corpus's full-text PDFs and synthesize a corpus statistics table plus an improvement-opportunity list. Engineering-default domain profiles. Used inside paper-auditor / thesis-auditor (audit) and scopus-researcher (mine). Also carries parse_cache.py (content-addressed PDF-parse cache, additive to every consumer) and the opt-in corpus_index.py (deterministic chunker, injected embedder, pgvector store for ad-hoc cross-corpus retrieval; every hit is provenance, never a citation). |
.claude/skills/extract-statistic/SKILL.md |
extract-futureworks |
Future-works analysis (reuses extract_text.py --section-scan). Mode audit: review a work's own future works (presence, testability, link-to-limitation, novelty) and validate its hypotheses against the cited-corpus future works, proposing stronger ones. Mode mine: extract every corpus paper's stated future works, build a review-fit table, Pareto 80/20-rank it (low effort, high impact first), and emit a research-opportunity list. Used inside the four auditors (audit) and scopus-researcher (mine), where it is a hard gate: no hypothesis/project without it. |
.claude/skills/extract-futureworks/SKILL.md |
extract-contributions |
What a cited paper says it CONTRIBUTES, out of its full text (reuses extract_text.py; ships no reader). Mode validate: pair every \cite{} of a manuscript with the paper's own contribution sentences and flag the citations the paper does not support. Mode mine: tabulate a refs/ corpus by kind. Surfaces evidence verbatim and decides nothing; ok / no-contribution / empty / unreadable are kept apart so a retrieval failure is never read as a property of the paper. Markers are data in contribution_markers.json. |
.claude/skills/extract-contributions/SKILL.md |
extract-paper-idea |
Extract a paper's OWN content into one JSON, the basis for drafting or refreshing its abstract (or, for a UQAC thesis, its Résumé + Abstract pair). Ships no reader of its own: reuses paper2talk's \input/\include flattening and section map, extract-statistic's future-works-cue section scan, and extract-contributions' marker scan (pointed at the paper's own text instead of a cited one). Detects document type (uqac.cls on the flattened text) and the document's own language; never a forced bilingual pair for a paper, always both languages for a thesis. Delegates the drafting to the abstract-writer agent. |
/abstract, .claude/skills/extract-paper-idea/SKILL.md |
paper2talk |
Accepted paper -> conference talk. Asks six questions before reading the paper (audience, duration, output target, aspect ratio, PDF format, deck ending), echoes a build contract, then builds ONE talk_model.json and renders it to PowerPoint (pptxgenjs), LaTeX Beamer on the lab gabarit, or a self-contained web page. Speaker notes budgeted at 130 wpm aiming under the slot, figures re-exported through the draw.io CLI at scale 3, and a visual QA loop (PowerPoint COM -> pdftoppm) with a legibility gate and a no-text-only-slide rule. Delegates the loop to the talk-builder agent. |
/talk, .claude/skills/paper2talk/SKILL.md |
word2latex |
Convert a Word .docx template (Mitacs, CRSNG, FRQNT, UQAC, partner forms) into a faithful LaTeX source. Delegates the patch work to the word-to-latex agent. |
/word2latex, .claude/skills/word2latex/SKILL.md |
finish-branch |
Finish a ResearchTools branch in one order. Before the pull request, it regenerates the mirrors (install.ps1 -Profile <active>) and runs scripts/test/run-all-checks.ps1, whose verify-mirrors-fresh.ps1 fails on stale mirrors. After the owner merges ("clean the project"), it confirms the merge, compares the main checkout's leftovers before discarding them, and shows the dry run of finish-branch.ps1 -Branch <b> -Refresh. With -Yes (the owner's request only), that script removes the worktree and the branch, then refreshes the machine with setup.ps1 -Update and reminds mkdocs gh-deploy when docs/ changed. ResearchTools clone only. See chapter 16. |
/finish-branch, .claude/skills/finish-branch/SKILL.md |
pdf2md |
Convert a PDF with no LaTeX source (export/Marker failed, mineru is the fallback, via its installed mineru-kit CLI entry point) into clean, chapter-split markdown laid out as a project's own src/ directory (-o points AT that src/, never a parent of it): src/main.md linking everything, src/content/ holding frontmatter.md, Introduction.md, chapitreN.md for every chapter in between, and Conclusion.md, and src/assets/ holding bibliography.md and ref.md (acronyms under assets/ are a reserved slot, not yet implemented; figures mineru embeds as base64 are written to assets/figures/ by the repair stage — mineru's image extraction stays off). Accurate enough for thesis-auditor's content checks — never its uqac.cls mechanical checks, since mineru has no LaTeX output format, and never auto-discovered by thesis-auditor's own directory resolution, which looks for a real src/main.tex and reads \input{}/\include{} macros only; this layout is a human/manual-feed convenience, not interoperability with that step. Drives mineru end to end: bootstraps the missing mineru/mineru-llama-cpp packages, model, and config, starts the VLM server directly via subprocess.Popen (bypassing mineru-kit vlm-server, confirmed broken on Windows by an os.execv argv-quoting bug) with a real --image-min-tokens accuracy fix, runs the conversion, then strips the running-header splice defect mineru's own title_leveling leaves behind under CPU contention (a chapter-number-scoped fuzzy-match guard and a bibliography density gate, both measured against a real 162-page thesis conversion) and restructures the bibliography BibTeX-like, keying each entry by the first author's surname. A final structural sanity pass compares the output against an INDEPENDENT second PDF reader (extract-statistic's own extractor, never mineru's VLM again) chapter by chapter — words, sections, tables, figures, citations, and a labelled-rough equation estimate — flagging chapters whose counts diverge. Those counts mislead on math-heavy chapters, so two content checks sit beside them. --fidelity compares paragraphs and headings and reports the real conversion errors: lost or misplaced numbered headings, missing, extra, repeated or reordered paragraphs, base64 images and HTML left in the markdown. --vlm-check (a local vision model the operator names explicitly) reads the pages richest in math and verifies their formulas against the markdown, its answer forced into a schema and validated. A repair stage then fixes what can be fixed mechanically (images extracted to assets/figures/, footnote HTML unwrapped, lost headings restored, far-displaced blocks moved back, invented image-analysis tables removed, a citation read as mathematics put back), as a dry run unless --yes, with the originals backed up and the effect measured by re-running the fidelity check. A last fix stage runs a bounded correction loop with a local vision model (slow, meant for the night) that transcribes a lost numbered equation from its PDF page; by default it only recovers lost equations, and rewriting formulas needs --rewrite-formulas since a model changed the meaning of a correct formula in a measured run. The postprocess stage takes --layout single for an article or a talk source, kept as one main.md with its bibliography copied to assets/, where the default --layout thesis splits chapters; repair and fix refuse the single layout. run is a dry run without --yes, and the bootstrap installs pinned mineru versions and exits 1 when its install or download did not leave them in place. The validation table reports, per measure and per converted file, the PDF count against the output count and the error in percent. Every stage runs with the interpreter of .venv-pdf2md (built by setup.ps1 -InstallPython), never .venv-skills: the bootstrap installs mineru into the interpreter that runs it, and mineru's gradio would pull .venv-skills' pillow back below 13. |
.claude/skills/pdf2md/SKILL.md |
drawio2tikz |
Convert one .drawio sheet into a coordinate-exact TikZ fragment (absolute coordinates, edge anchoring, braces, rotation, FR→EN --translate). The sanctioned absolute-coordinate exception to the hand-authored TiKZ rules. |
the skill drawio2tikz (no slash command exists), .claude/skills/drawio2tikz/SKILL.md |
geolocalisation |
Map a review corpus in space from its .bib: resolve each paper's study/case-study site (per-DOI Scopus abstract + title + keywords, optional --full-text PDF scan via download_pdf.py, matched against an offline Natural Earth gazetteer), write a reviewable draft table with a confidence column and a per-paper provenance note, then render CSV, KML (Google My Maps), GeoJSON (QGIS/Leaflet), a world-map PNG, an interactive HTML map, and a per-country count table. Human-reviewed; an override CSV always wins. |
/geolocalisation, .claude/skills/geolocalisation/SKILL.md |
loop-engineer |
Bounded develop-and-improve loop: design → plan → code → comment → test → review → score → correct, looping until a composite gate (tests green, no CRITICAL/HIGH, score >= min) or a bound the owner declared (rounds, tokens, plateau). Fable 5 orchestrates; Opus/Sonnet act; local-coder/local-writer do local generation. loop_audit.py aggregates the installed reviewers into a 0-100 score with a security hard floor; merge to a protected branch is human-gated. |
/loopdev, .claude/skills/loop-engineer/SKILL.md |
recommendation-letter |
Generate support, recommendation, appreciation, acceptance, and dispense (short-stay invitation) letters in LaTeX → PDF from a candidate's files. Two tracks: Claude authors the four persuasive types (fr/en); a stdlib-only Python script fills the fixed French acceptance/dispense forms (candidate status, funding provider, 120-day work-permit exemption, paired output). Sample data is synthetic. | /recommendation-letter, .claude/skills/recommendation-letter/SKILL.md |
narrative-cv |
Draft, refresh, or tailor the narrative "CV descriptif" (FRQ CV-FRQ, structurally identical to the tri-agency CIHR/NSERC/SSHRC CV commun des trois organismes) to one grant competition: three sections, up to 10 items in section 2, 6-page FR / 5-page EN cap. Built around a durable master contributions inventory in the researcher's own external project folder, refreshed via Scopus (AU-ID two-step) + extract-contributions and re-ranked per competition by keyword overlap against that program's own objectives/evaluation criteria rather than rebuilt from scratch each time. Renders LaTeX/PDF and a plain-text companion for the new-FRQnet-portal paste-in channel from one JSON model (paper2talk's one-model-many-renderers pattern). |
/cv, .claude/skills/narrative-cv/SKILL.md |
professor-expertise-finder |
Find university professors closest to a set of expertise keywords, in any location (country, province/state, region, or worldwide — never hardcoded). Reuses or builds a verified university/department/faculty-list table, ranks professors with a /5 correspondence rubric (score.py), and keeps only professors with at least two verified in-field articles. Also: a test mode scoring named candidates anywhere, a user-supplied exclusion list (exclusions.py), an optional reviewers reference file searched first (file_search.py), and a batch allocation mode (selections.py) enforcing no-reuse across applications, all evaluators of one application from distinct universities, and conflict-of-interest exclusion of the applicant's own university. The data root (location tables, batch registries) resolves from PROFESSOR_EXPERTISE_DATA, defaulting to ~/workspace/professor-expertise — never a hardcoded path. |
/expertfinder, .claude/skills/professor-expertise-finder/SKILL.md |
obsidian-cli |
Read and search the Obsidian vault through the allowed command surface only (read, search, files, folders, property:read/property:set, tasks, links, tags, move, rename); a captured learning is deposited to the outbox, the single write path, instead of calling a write command directly. The direct CLI write commands (create, append, prepend, plus eval, dev:*, plugin:install, theme:install, sync*) are forbidden for measured reasons: the failure sits in the whole JSON header, not the content (a 3850-byte header passes, 4343 does not, and 4096, a Windows named-pipe buffer, falls between); the CLI exits 0 on that failure too; and create on an existing file writes a numbered duplicate instead of failing. |
.claude/skills/obsidian-cli/SKILL.md |
latex-hygiene |
Measure LaTeX manuscript hygiene mechanically: forbidden characters, an AI-usage risk score, prose and track-changed word counts, abstract length, brace/\begin-\end balance, changes-macro paragraph-crossing corruption, and label/citation coverage (citecov against a .bib, refcov for uncited labels, dangling refs, and duplicate labels). Backs the aiscan/wc checks that paper-auditor and submit-checker already describe in prose, so the same signal table and score formula are computed the same way every time. The write side applies a machine-readable audit plan (patch), scans for post-write corruption (scan), and resolves and builds the tracked or accepted PDF (accept, build). |
/texcheck, .claude/skills/latex-hygiene/SKILL.md |
form-service (was uqac-forms, renamed 2026-09-25) |
Stateless mechanics for official PDF forms from any institution. RT-1 ships the validated ingest contract: https only re-checked on every redirect hop, at most 5 redirects followed manually, a 25 MiB cap enforced during the stream, %PDF magic bytes, a 30 s timeout, and an atomic write. The form catalogue, field maps and profile live in ThesisTracker, not here. Filling (RT-3), PAdES signing (RT-4) and signature validation follow. RT-5 exposes all of it as a stateless HTTP API in deploy/form-service/ (/pdf/widgets, /pdf/fill, /pdf/sign, /pdf/validate), shared-secret gated, no CORS, nothing persisted. RT-8 adds POST /cv/build, a stateless narrative-CV render (with consenting HQP rows) over the narrative-cv skill's cv_build.py, compiling no LaTeX on the service. See chapter 17 for the boundary with ThesisTracker. |
/fetchform, .claude/skills/form-service/SKILL.md |
graphify (external: uv tool install graphifyy, not shipped here) |
The code-graph memory: turn a folder of files into a queryable knowledge graph, then ask it what calls what, how one node reaches another, and what a symbol is. query, path and explain are deterministic traversals of graphify-out/graph.json and cost no model at all, which is why one graph query beats grepping file by file. Reached only through local-writer, like the vault. The CLI itself is a separate install (uv tool install graphifyy); this directory is the SKILL, kept here so a clone is never told to consult a graph it has no way to reach. .graphify_version records the version it was generated from - refresh the copy after upgrading the CLI. |
/graphify, .claude/skills/graphify/SKILL.md |
opt-local-vram-llm |
Tune a local Ollama model for this GPU: retain the largest num_ctx that keeps the model 100 percent resident in VRAM, among configurations whose decode throughput clears a floor (default 0.90 of the best admissible run). Reads the manifest and daemon facts read-only, renders a tuned Modelfile, sweeps num_ctx against OLLAMA_KV_CACHE_TYPE (restarting the daemon per value and proving the restart took effect from server.log, restoring the original value on failure), then declares the tuned tag as a role candidate in local-models.json. Stops before qualification, which stays with model_resolver.py --qualify. |
/opt-local-vram-llm, .claude/skills/opt-local-vram-llm/SKILL.md |
opt-local-stt-vram |
Pick the voice panel's speech-to-text model for this GPU: download the named models (faster-whisper sizes or CTranslate2 repo ids; the four measured on 2026-09-26 by default), measure each in a fresh process BESIDE the resident local LLM, and print one scored table - word error against the operator's own reference words, live-caption speed against the panel's refresh budget, dedicated VRAM, and how much of the LLM each pushes out of VRAM (a gate). Stops before adoption: switching observe-config.json voice.stt.* stays a human edit. |
/opt-local-stt-vram, .claude/skills/opt-local-stt-vram/SKILL.md |
aider-setup |
Set up, tune and run the aider nightly local-coding pipeline — a second, independent local-coding harness that needs no Claude Code: two local Ollama models (a writer that codes and tests, a reviewer that never edits, gated by measured token budgets) run one aider process per plan overnight, driven by aider-plan.ps1/aider-night.ps1. Owns the packaging pipeline (scripts/build/) that assembles the student-facing aider-kit.zip from this skill's own canonical sources, with a leak scan and an install-and-dry-run gate. config/rules.md is generated at build time from this repository's own .claude/rules/ (R26 fixes the plan-file shape every harness reads; R27 the function-header convention). See chapter 14 for the full picture. |
.claude/skills/aider-setup/SKILL.md |
rt-observe |
Report the state of the toolkit as one local page: the mirror matrix of every agent, skill, command and rule against every harness dialect, plus live sessions, services, plan progress and a push-to-talk voice panel. Standard library only, it runs from a bare clone with no harness installed, because it compares files rather than asking a tool. The page is on loopback only, and its actions are a closed whitelist. See chapter 10. | /rt-dashboard, .claude/skills/rt-observe/SKILL.md |
wp-portfolio-sync |
Migrate a researcher's final CIHR / Canadian Common CV XML export into their WordPress portfolio, once: parse, discover the pages, preview and pause for approval, push, verify. Reads no student data from the XML, and an anti-fabrication check refuses any title that is not in the source. Delegates to the wp-portfolio-agent agent. |
/portfolio, .claude/skills/wp-portfolio-sync/SKILL.md |
Local coding contract. The loop-engineer skill also carries three small tools. loop_bounds.py stores the review-loop bounds (max_rounds, max_tokens, plateau) per branch in the worktree's git directory, and the hook review-loop-guard.py refuses a review past them. plan_contract.py validates a plan header (executor, tier, bounds) and maps its tier to a resolver role. token_count.py counts any file, folder or text and never calls an estimate exact. See chapter 11.
/scopus — Scopus academic search¶
Searches the Scopus database via the Elsevier REST API. Requires SCOPUS_API_KEY
(see the API-keys table in 02-profiles.md) and an active institutional network connection
(campus or VPN), or an --insttoken.
| Command | What it does |
|---|---|
/scopus <topic> |
Search top papers on a topic — ordered by citation count, and bare keywords are scoped to title/abstract/keywords. Add --sort recent when you want the newest papers instead |
/scopus review <topic> |
Structured literature review with inline citations |
/scopus validate <DOI or title> |
Confirm a reference exists. Flags ambiguous when several records share the title, so results[0] is never taken on faith |
/scopus cite <DOI> |
Citation count + full metadata for one paper |
/scopus author AU-ID(<digits>) |
Author profile: document count, affiliation, computed h-index, top papers. Works on a Search-only key |
/scopus author <name> |
Same, when the key is entitled for the Author Search API; otherwise degrades to Semantic Scholar candidates and says so (no Scopus AU-ID can be resolved from a name without that entitlement) |
/scopus journal <name or ISSN> |
Journal SJR quartile, CiteScore, subject areas |
How a paper is downloaded¶
Figure: the download process of download_pdf.py. Each download is tried in turn, and the first
one that gives the full text ends the process.
flowchart TD
S["Reference with a DOI?"] --> A{"DOI empty?"}
A -- yes --> Z0["Status no-doi: stop"]
A -- no --> P0{"File already in refs/?"}
P0 -- yes --> SK["Status present: stop"]
P0 -- no --> P1{"SCOPUS_API_KEY set?"}
P1 -- no --> P2
P1 -- yes --> D1["Download 1: Elsevier Full-Text API<br/>with the key and the institutional token if set"]
D1 --> Q1{"PDF written?"}
Q1 -- no --> P2
Q1 -- yes --> V1{"One-page preview?"}
V1 -- yes --> X1["Delete the file"]
X1 --> P2
V1 -- no --> OK["File saved: stop"]
P2{"Semantic Scholar knows an open-access PDF URL?"}
P2 -- no --> D3
P2 -- yes --> D2["Download 2: Semantic Scholar open-access PDF"]
D2 --> Q2{"PDF written?"}
Q2 -- no --> D3
Q2 -- yes --> OK
D3["Download 3: publisher PDF built from the DOI landing page"]
D3 --> Q3{"PDF written?"}
Q3 -- no --> P4
Q3 -- yes --> V3{"One-page preview?"}
V3 -- yes --> X3["Delete the file"]
X3 --> P4
V3 -- no --> OK
P4{"UNPAYWALL_EMAIL set?"}
P4 -- no --> L
P4 -- yes --> D4["Download 4: Unpaywall<br/>PDF, else landing page HTML if HTML is allowed"]
D4 --> Q4{"PDF or HTML written?"}
Q4 -- no --> L
Q4 -- yes --> OK
L["Read the arXiv and PubMed Central ids from Semantic Scholar"] --> P5{"arXiv id known?"}
P5 -- no --> P6
P5 -- yes --> D5["Download 5: arXiv<br/>PDF, else arXiv HTML, else ar5iv HTML"]
D5 --> Q5{"PDF or HTML written?"}
Q5 -- no --> P6
Q5 -- yes --> OK
P6{"HTML allowed and PMCID known?"}
P6 -- no --> P7
P6 -- yes --> D6["Download 6: PubMed Central article HTML"]
D6 --> Q6{"HTML written?"}
Q6 -- no --> P7
Q6 -- yes --> OK
P7{"HTML allowed?"}
P7 -- no --> P8
P7 -- yes --> D7["Download 7: DOI landing page saved as HTML<br/>only if it passes the article check"]
D7 --> Q7{"HTML written?"}
Q7 -- no --> P8
Q7 -- yes --> OK
P8{"Browser rung enabled and playwright installed?"}
P8 -- no --> M1
P8 -- yes --> D8["Download 8: Chrome driven by Playwright<br/>a person clicks any challenge, sign-in if the host is configured"]
D8 --> R8{"Named error raised?"}
R8 -- yes --> M1
R8 -- no --> Q8{"PDF captured?"}
Q8 -- no --> M1
Q8 -- yes --> V8{"One-page preview?"}
V8 -- yes --> X8["Delete the file"]
X8 --> M1
V8 -- no --> OK
M1{"Publisher said the requestor is not entitled?"}
M1 -- yes --> M2["Reason: request it by interlibrary loan or save it by hand"]
M1 -- no --> M3{"A preview was seen?"}
M3 -- yes --> M4["Reason: probably not entitled, interlibrary loan or by hand"]
M3 -- no --> M5["Reason: no download gave the full text, save it by hand"]
M2 --> END["Status failed: list the paper in refs/_failed.md"]
M4 --> END
M5 --> END
The source of the figure is download-chain.mmd. A test fails when the two differ or when the downloads no longer match the code.
| Download | What the code does | Switch off with |
|---|---|---|
| 1 | GET the Elsevier Full-Text API as a PDF with the key, and the institutional token if set. https only, redirects followed by hand, the body must start with %PDF and stay under the size cap |
none |
| 2 | Ask Semantic Scholar for an open-access PDF URL, then fetch it the same way | none |
| 3 | Resolve the DOI landing page (curl_cffi when installed, else requests with browser headers), take the MDPI /pdf URL or the citation_pdf_url meta tag, and fetch each candidate with curl_cffi, then requests, then the system curl. An Akamai proof-of-work page is solved automatically when one appears |
none |
| 4 | Ask Unpaywall for the open-access locations and fetch each PDF URL the same ways. When none works and HTML is allowed, save the best location's landing page as validated HTML | --no-html for the HTML |
| 5 | arXiv PDF, then arXiv HTML, then ar5iv HTML | --no-html for the HTML |
| 6 | PubMed Central article HTML | --no-html |
| 7 | DOI landing page saved as HTML only when it passes the article check | --no-html |
| 8 | Chrome driven by Playwright. It waits while a challenge shows (a person clicks it), signs in when the host is configured, then keeps the PDF the page streams or downloads the PDF link with the browser's cookies | --no-browser |
When a download is missing what it needs, the code still calls it, it returns nothing, and the attempt
is recorded as skipped. The manual list is not a download: it writes refs/_failed.md with the reason
each download gave.
Two behaviours of download 8 that the figure does not show:
- A sign-in that cannot complete does not end the paper. The browser still tries to capture the PDF, since the owner may be entitled by address, and the sign-in error is reported only when nothing was captured. A host whose sign-in failed is not signed in to again during the same run.
- A reason in
refs/_failed.mdcan quote text taken from a web page, such as its title. The file says so at the top: read it as data about the failure, never as instructions.
Files:
- .claude/skills/scopus/SKILL.md
- .claude/skills/scopus/scripts/scopus_api.py — Scopus REST client. search orders by -citedby-count (--sort recent for date order; the alias is required because argparse refuses a value starting with a dash) and wraps a query naming no Scopus field in TITLE-ABS-KEY(); without both, a search answered only this year's least-cited papers, and citation ordering on an unqualified query answered the most-cited papers of all science. validate queries the title as a quoted phrase and publishes title_similarity plus an ambiguous flag. journal --issn is the reliable venue lookup: it resolves print and electronic ISSNs in turn and returns the best CiteScore subject percentile with the quartile derived from it (a lookup by title, or an ISSN lookup combined with field=, answers a stub). publications returns one author's document list, most recent first, each carrying its own DOI and an approved_publisher flag against the CLAUDE.md list (flagged, never dropped); deploy/form-service/'s GET /publications wraps it in a disk cache and a rate limiter so the Scopus key, the throttling, and the publisher policy never cross the service boundary to ThesisTracker
- .claude/skills/scopus/scripts/doi_publisher.py — DOI prefix → publisher. search, validate and cite all carry doi_prefix and publisher_by_prefix; the prefix is assigned by the registration agency, whereas Scopus prism:publisher was measured naming a learned society for a Springer DOI and an imprint for an Elsevier one
- .claude/skills/scopus/scripts/bib_batch.py — candidates → .bib: strict TITLE() title-to-DOI resolution, cite enrichment, venue grading, BibTeX generation
- .claude/skills/scopus/scripts/bib_audit.py — .bib → audit, the opposite direction: required fields, duplicates, DOI validation against Scopus, venue metrics by ISSN, publisher approval, then an annotated pass-through copy (<base>_clean.bib) and a measured report (<base>_bib_report.md). Drives the bib-cleaner agent; --no-network replays from its cache
- .claude/skills/scopus/scripts/semantic_scholar_api.py — Semantic Scholar fallback, and since 2026-10-22 a keyword search (search "<keywords>" --year 2025-2026 --limit 20) for finding candidates beside Scopus
- .claude/skills/scopus/scripts/download_pdf.py — any-format full-text retrieval as a strict nine-rung chain (Elsevier, Semantic Scholar, publisher PDF, Unpaywall, arXiv, PMC, validated DOI landing, a real browser with the owner's institutional sign-in, then the manual list). Subcommands doi, bib and url (a ScienceDirect article URL or a bare PII). The first success stops the chain, no rung is opt-in on the command line (--no-browser skips the browser one; the corpus scripts of extract-statistic and geolocalisation leave it off), and every rung's outcome and reason is kept in the manifest and printed per paper in refs/_failed.md. ELSEVIER_INSTTOKEN supplies the Elsevier institutional token when --insttoken is absent
- .claude/skills/scopus/scripts/browser_fetch.py — rung 8: the installed Google Chrome driven by Playwright for challenge-gated publishers (Cloudflare Turnstile is clicked by a person, never solved by the tool, and no stealth library is used), with a per-paper refs/_sources.json override URL (e.g. ResearchGate). A publisher host listed in browser-fetch.json gets an institutional sign-in whose password is typed only into that host's login_hosts; one browser is shared by all papers of a run, so the sign-in happens once. Optional (needs playwright; Chrome, or playwright install chromium as the stated fallback)
- .claude/skills/scopus/scripts/browser_login.py — the secret providers of that sign-in: keyring (default), bitwarden (bw with BW_SESSION) and keepassxc, password only unless allow_totp_from_vault is true, no secret ever logged, no silent switch between providers
- .claude/skills/scopus/scripts/browser-fetch.json — every timeout, limit and host setting of the browser rung, each value with its provenance; hosts is empty until a live run has verified a sign-in
- .claude/skills/scopus/scripts/litreview_update.py — incremental-update bookkeeping for /litupdate (baseline fingerprint, delta dedup via bib_batch.title_match, dated output paths, CHANGELOG scaffold)
- .claude/skills/scopus/scripts/gemini_reviewer.py · github_reviewer.py · gemini_table.py — cross-review cores
geolocalisation — corpus study-location mapping¶
Turns a corpus .bib into a spatial map of where each paper's empirical study was conducted.
A case-study site is not a bibliographic field (no API returns it — it lives in the text), so
the skill is deliberately human-in-the-loop: it emits a draft with a confidence column and
a per-paper provenance note, a human reviews it, and a manual override CSV always wins before
rendering. Requires SCOPUS_API_KEY (campus network or VPN), or run --no-scopus for a
manual-entry template.
| Stage | Command | Output |
|---|---|---|
| 1 — extract | extract_locations.py --bib <corpus.bib> --out <dir> [--full-text] [--override <curated.csv>] |
study_locations.csv (with confidence, evidence_field, evidence, provenance) + provenance/<citekey>.md audit notes |
| 2 — review | (human) | curate / confirm; correct every low/none row via the override CSV |
| 3 — render | generate_geomap.py --csv <dir>/study_locations.csv --out <dir> [--formats …] [--min-confidence …] |
CSV, KML (Google My Maps), GeoJSON (QGIS/Leaflet), world-map PNG, interactive HTML, country_counts.csv |
- Extraction: per-DOI Scopus abstract + title + keywords; place names matched against an
offline Natural Earth gazetteer, with capitalization + a population floor + a common-word
stoplist for precision (separates the city
Mobilefrom the wordmobile). --full-text: fornone/lowresults, downloads the PDF via the scopus skill'sdownload_pdf.py, reads it with PyMuPDF, and scans only study-cue sentences with affiliation lines rejected — an unfiltered full-text scan maps author affiliations, not study sites. Adopted only when it beats the abstract; PDFs cached inrefs/.- Auditability: every mapped point carries
evidence_field+ the verbatimevidencesentence in the CSV, aprovenance/<citekey>.mdnote, and the same surfaced in the HTML popup, GeoJSON properties, and KML description. - No geopandas/GDAL — the basemap is drawn from raw GeoJSON. Deps:
matplotlib(PNG), optionalfolium(HTML) andPyMuPDF(--full-text).
Files:
- .claude/skills/geolocalisation/SKILL.md
- .claude/skills/geolocalisation/scripts/extract_locations.py — bib + Scopus/full-text → draft CSV + provenance notes
- .claude/skills/geolocalisation/scripts/generate_geomap.py — reviewed CSV → CSV/KML/GeoJSON/PNG/HTML + per-country table (no geopandas)
- .claude/skills/geolocalisation/references/geocoding-protocol.md — extraction method, confidence rubric, override format, full-text pipeline
- .claude/skills/geolocalisation/scripts/Test/test_extract_locations.py — offline unit tests (bib parse, matcher, evidence, full-text)
recommendation-letter — support / recommendation / acceptance / dispense letters¶
Generates supervisor letters in LaTeX → PDF from a candidate's own files, signed by the
active profile's author (profiles/<active>.yaml, author.letter; a profile with no such
block is a stated refusal, never a letter signed with someone else's name). Two
tracks: Claude authors the four persuasive types (scholarship, academic_position,
industry_position, appreciation; French or English), while a Python
script fills the fixed French acceptance and dispense forms. candidate_status
(applicant / current_student / graduated) sets how the candidate is named; funding_provider
(supervisor / candidate / combination) branches the funding paragraph; the dispense letter
carries the < 120-day work-permit exemption paragraph and warns when a stay exceeds it;
invitation_pair=both emits the acceptance and dispense letters together. A style-hygiene
linter enforces the AI-usage rules. All shipped sample data is synthetic.
Files:
- .claude/skills/recommendation-letter/SKILL.md
- .claude/skills/recommendation-letter/scripts/generate_letter.py — two-track assembler, validator, pdflatex compile
- .claude/skills/recommendation-letter/scripts/letter_templates.py — preamble, letterhead/signature, acceptance/dispense French templates
- .claude/skills/recommendation-letter/scripts/Test/test_generate_letter.py — offline unit tests (53 cases)
- .claude/skills/recommendation-letter/references/quality-patterns.md — authored-track quality patterns
- .claude/skills/recommendation-letter/evals/ — synthetic sample configs
narrative-cv — FRQ / tri-agency narrative CV¶
FRQ's CV-FRQ and the tri-agency (CIHR/NSERC/SSHRC) "CV commun des trois organismes" are the same format (verified against both official pages 2026-09-25): three sections (career/skills, up to ten contributions and experiences, supervision and mentoring), 6 pages French or 5 English. Built around a durable master inventory rather than a stateless per-run extraction, so a grant CV is a re-selection over a growing corpus instead of a from-scratch rebuild each time.
| Stage | Script | Job |
|---|---|---|
| 1 — inventory | cv_inventory.py |
CRUD over the master inventory YAML (init/add/list/stats/mark-used), validated and deduplicated by id/DOI. Never calls Scopus itself. |
| 2 — select | cv_select.py |
Deterministic keyword-overlap ranking against a competition's own objectives/evaluation criteria — a signal for the drafting agent's judgment, not a verdict. |
| 3 — build | cv_build.py |
Renders ONE cv_model.json to LaTeX and a plain-text companion, builds the mandatory old-portal filename (NOM_XXXXX1234_Titre.pdf, normes_presentation.pdf), and checks the compiled page count against the 6/5-page cap. |
The candidate's identity (CV header/footer, filename surname) and the external project folder
the inventory and drafts live in (cv.project_dir, where a leading {{HOME}} stands for your
home directory) both come from the active profile (profiles/<active>.yaml), never from a
hardcoded path — a profile carrying neither block is a
stop, not a guess. Drives the narrative-cv-writer agent, reached via /cv.
ThesisTracker builds a CV with consenting students' rows through form-service's stateless
POST /cv/build, which imports cv_build.py directly (cv_bridge.py). No LaTeX is compiled on
the service and nothing is stored: the service returns LaTeX and/or plain text only, and the PDF
and the page-budget check stay local. Every row needs consent_cv, whatever its date (C6
revised); the recent/archive window is per-funder (6 years NSERC/tri-agency, 5 FRQ) and decides
only the heading a row prints under. A missing or malformed field refuses the request, naming the
row's index only, never a name. cv_build.py inline --model
<cv_model.json> --out <file.json> turns a locally-authored model (which keeps its prose in
prose_file files) into the inline form the service requires, since a request body must never
name a file on the server.
Files:
- .claude/skills/narrative-cv/SKILL.md
- .claude/skills/narrative-cv/scripts/cv_common.py — shared helpers: contribution-types loader, active-profile identity/project-dir resolution (no fallback), FRQ filename builder
- .claude/skills/narrative-cv/scripts/cv_inventory.py — the master inventory CRUD
- .claude/skills/narrative-cv/scripts/cv_select.py — keyword-overlap ranking
- .claude/skills/narrative-cv/scripts/cv_build.py — LaTeX/text rendering, filename, page-budget check
- .claude/skills/narrative-cv/scripts/contribution_types.json — section titles, clientele/category vocabularies, page budget, portal/font variants (data, not code)
- .claude/skills/narrative-cv/scripts/Test/test_cv_common.py, test_cv_inventory.py, test_cv_select.py, test_cv_build.py — offline unit tests (164 cases; no network, no LaTeX install, no machine-local profile dependency)
professor-expertise-finder — university-professor expertise matching¶
Location-agnostic by design: the skill contains no place name. Given a search location
(country, province/state, region, city, or worldwide — always asked, never assumed) and a set
of expertise keywords, it reuses or builds a verified university, department, department_url,
faculty_list_url, note table for that location, extracts professors from each faculty-list
page, and scores each one's closeness to the keywords with a /5 rubric (five subscores A–E,
each 0/0.5/1, computed by score.py — never by hand). Article discovery goes through the
scopus skill rather than ad hoc web search (an AU-ID resolution, the professor's recent
documents, approved_publisher as the quality bar), and correspondence to the keywords is
checked against each article's own stated contribution via extract-contributions, never a
guessed title match — matching this repo's own working norm that every piece of information is
verified through scopus. A professor without at least two such recent (pef_config.json's
recent_years_window), approved-publisher articles is dropped. The output links each
professor's name to their official page, their professional email as published there (with its
source link — never a mailto: or a name-pattern guess), the score with subscores, and the two
articles.
Variants layer on top of the same workflow: test mode scores named candidates directly
(any location); an exclusion list (Excel/CSV) removes professors via exclusions.py; an
optional reference file of known reviewers is searched first via file_search.py (its
declared languages and availability outrank web presumption, but never limit the search); and
batch allocation mode processes several keyword sets at once (e.g. several funding
applications) through selections.py's registry, which enforces three hard rules by script,
not by prose: a professor final for one set cannot be reused for another, every application's
evaluators must come from distinct universities, and no evaluator may come from the
application's own (applicant) university once that origin is declared.
The data root (<root>/<location-slug>/departments.csv, <root>/batches/<batch-slug>/
selections.csv) resolves from the PROFESSOR_EXPERTISE_DATA environment variable, defaulting
to ~/workspace/professor-expertise — repoint it by setting the variable, never by editing a
script. The rubric's enforced constants (subscore values, retain threshold, university cap,
recent-years window) live in scripts/pef_config.json with their provenance, not as literals in
code. The skill reuses two sibling skills rather than reimplementing them: scopus
(scopus_api.py, download_pdf.py) and extract-contributions.
Files:
- .claude/skills/professor-expertise-finder/SKILL.md
- .claude/skills/professor-expertise-finder/references/scoring.md — the /5 rubric and its interpretation bands
- .claude/skills/professor-expertise-finder/scripts/pef_common.py — shared helpers: data_root(), slugify, norm, name_key, load_config(), load_column_hints(), write_json()
- .claude/skills/professor-expertise-finder/scripts/pef_config.json — enforced policy constants with provenance
- .claude/skills/professor-expertise-finder/scripts/pef_column_hints.json — reference/exclusion-file column-name synonyms, as data rather than code
- .claude/skills/professor-expertise-finder/scripts/table.py — location department-table lifecycle (check/init/validate)
- .claude/skills/professor-expertise-finder/scripts/score.py — the /5 total, band, and retain-threshold check
- .claude/skills/professor-expertise-finder/scripts/exclusions.py — apply an exclusion list to a ranking
- .claude/skills/professor-expertise-finder/scripts/file_search.py — search an optional reviewers reference file first
- .claude/skills/professor-expertise-finder/scripts/selections.py — the batch no-reuse / one-university / conflict-of-interest registry
- .claude/skills/professor-expertise-finder/scripts/Test/ — offline unit tests (no network, no API key)
wp-portfolio-sync — one-shot CIHR XML to WordPress migration¶
Migrates a researcher's final CIHR / Canadian Common CV XML export into their WordPress
portfolio exactly once, through the WordPress REST API, between <!-- cvsync:MARKER -->
comments. After the push, the website is the source of truth for that content; the XML is
never read again. No student data is parsed from the XML at all (no supervision parser
exists in cihr_cv.py): student data is published from ThesisTracker once its own consent
flow ships (Phase 2), and a mapping entry naming renderer: phq is refused everywhere a
mapping is validated.
| Stage | Script | Job |
|---|---|---|
| 1 — parse | cihr_cv.py / parse_cv.py |
CIHR generic-cv XML (or a generic XML export) into a clean JSON document, refusing an XML with zero recognised sections rather than publishing "0 subventions"; recognises both French and English CCV labels (cihr_labels.json), and degrades to stdlib xml.etree.ElementTree with a stated warning when defusedxml is absent, rather than silently |
| 2 — discover | discover.py |
Lists WordPress pages (id, slug, title, link), first run only, to fill mapping.yaml's page_id values |
| 3 — render | render.py |
Pure HTML renderers for financement/implications/services/distinctions, driven entirely by mapping.yaml's ref_year/recent_window/recent_label (no hardcoded year); a multi-funder grant sums every source's amount and names every organisme rather than reading only its first source, with a partially-received source's amount still caveated; every *_extra.yaml record is validated against its renderer's required keys before being merged in, refusing by name rather than raising a bare KeyError deep inside a renderer; owns validate_mapping (mapping.yaml structural validation, shared with push_wp.py/preview.py/verify_titles.py so none of them can touch an unvalidated mapping); render_phq is a tested, unwired pure function reserved for Phase 2 |
| 4 — gate | verify_titles.py |
The anti-fabrication gate: every <strong> title a split-mode renderer produced must exist in the parsed CV, the entry's own extras file, or an approved static seed; a markers/replace entry (which has no per-title check) is instead scanned for a denylisted sensitive key anywhere in its cv_path subtree (sensitive_keys.json, covering every HQP category — students, postdocs, mentorat, interns) and refused on a hit |
| 5 — push | push_wp.py |
Validates the mapping, runs the gate before any network call (in dry run and --apply), reads and writes content.raw only (never content.rendered), re-checks the page's modified_gmt right before a real write and refuses rather than overwriting a page someone edited by hand while the push was running, verifies every write with a read-back GET, and snapshots the page's prior content.raw to <data-dir>/backups/ immediately before every PUT so a hand-edit it overwrites can still be restored by hand |
| — preview | preview.py |
Offline report of what the push would change; makes no network call at all |
All researcher data (the XML, cihr.json, config/) lives under an explicit --data-dir
given on every command, which must resolve outside this repository (the repository is
public) — the skill ships only fictitious templates and tests. Drives the
wp-portfolio-agent agent, reached via /portfolio. Every CLI script's --json flag now
prints a {"error": ..., "exit_code": ...} report on a refusal or failure too, not only on
success. Cookie authentication (WP_COOKIES, same containment as every other
researcher-supplied path) can now write as well as read: set WP_NONCE to the nonce a
logged-in WordPress session returns, or push_wp.py refuses up front rather than failing on
every PUT.
Files:
- .claude/skills/wp-portfolio-sync/SKILL.md
- .claude/skills/wp-portfolio-sync/scripts/wp_errors.py, wp_config.py, wp_paths.py, wp_common.py — exceptions, the {value, provenance} config reader, data-folder containment, shared helpers and the bounded HTTP client (GET retries on a retryable exception, a 429, or a 5xx, with a configurable backoff; PUT never retried); make_session sets X-WP-Nonce from WP_NONCE for cookie authentication
- .claude/skills/wp-portfolio-sync/scripts/cihr_cv.py, parse_cv.py — the two XML parsers; cihr_labels.json holds their French/English label synonym table
- .claude/skills/wp-portfolio-sync/scripts/render.py — the HTML renderers, render_entry, split_entry_items/_validate_extra_items (extras-file merge and validation, shared with push_wp.section_size), and validate_mapping (mapping.yaml structural validation, re-exported unchanged as push_wp.validate_mapping); the only module reading config/
- .claude/skills/wp-portfolio-sync/scripts/verify_titles.py — the anti-fabrication gate; sensitive_keys.json holds the denylist its markers/replace scan reads
- .claude/skills/wp-portfolio-sync/scripts/push_wp.py — page planning, the push (with a pre-write concurrent-edit check), and the pre-PUT backup under <data-dir>/backups/
- .claude/skills/wp-portfolio-sync/scripts/discover.py, preview.py — page discovery and the offline preview
- .claude/skills/wp-portfolio-sync/templates/mapping.example.yaml, cookies.json.example — fictitious starting points
- .claude/skills/wp-portfolio-sync/scripts/Test/ — offline unit tests (10 suites; no network, no real data folder, fictitious fixtures only)
paper2talk — accepted paper to conference talk¶
Starts where submit-checker and cover-paper stop: the paper is accepted, the talk is the
next deliverable. The skill asks six questions before reading the paper — audience,
duration and conference, output target, aspect ratio, PDF format, and how the deck ends —
because every one of them is an input to a number the build cannot invent, then echoes a build
contract (n_content, word budget, font floor, preferred form, deliverables) before a single
slide is authored.
| Stage | Command | Output |
|---|---|---|
| 0 — preflight | talk_doctor.py --target pptx |
per-dependency state, which targets are buildable here, what degrades without each missing tool |
| 0b — read | paper_extract.py main.tex --out inventory.json |
\input-flattened sections, floats with labels/captions/assets, equations, citation keys, and the number inventory the deck is checked against |
| 1 — brand | talk_template.py <gabarit.pptx> --out brand.json --extract-media assets/ |
canvas, layouts, master background, every object in inches with srcRect as a keep-fraction |
| 2 — figures | fig_export.py <fig.svg> --out <fig.png> --scale 3 [--fix-text map.json] |
projector-grade PNG + implied-DPI report (warns below 150) |
| 3 — model | talk_model.py <talk_model.json> |
block-vocabulary check, no-text-only-slide rule, exhibit coverage, budget aggregation |
| 4 — render | talk_pptx.py --template <gabarit.pptx> · talk_model.py --render …tex.j2 (Beamer) · …html.j2 (web) |
.pptx built on the gabarit's own layouts, .tex, or one self-contained .html, all from the same model |
| 5 — gates | talk_validate.py · talk_notes.py · talk_render.py [--paper a4] |
package + legibility checks, spoken budget and cadence, PDF + page images, A4/Letter reflow |
- Cadence. One slide per minute counts content slides only:
n_content = floor(minutes - 0.5*(title+thanks) - 0.33*dividers). A 13-minute talk is 12 content slides and 15 in all, or 10 and 18 with five dividers. - Rate. 130 words per minute for a technical talk (not the 150 wpm of conversational
speech), aimed at
(minutes - 1.5) x 130so the talk lands under the slot. - Audience-parameterised typography. 16 pt body floor in the field (14 pt for captions and references), 20 pt for a general-public talk; no bullet cap for a scientific audience, since a slide may legitimately carry seven or eight equations. The cap is replaced by a mechanical legibility gate.
- Content hierarchy. figure > table > equation > prose. Prose, bullets included, is the last resort; a content slide with no exhibit is a defect, and every exhibit must be discussed in its own speaker notes (matched on subject keywords, never filenames).
- Gabarits.
../gabarit_these_maitrise_DSA_UQAC/src/slides/:Gabarit169.pptx(16:9, 18 named layouts),Gabarit43.pptx(4:3, preferred when an A4 handout is the deliverable),main.texfor Beamer. The deck is built on the gabarit with python-pptx rather than imitated, so the lab branding, layouts and placeholders are used as designed. - Nothing invented.
talk_model.py --check-numbers inventory.jsoncompares every number on every slide against the numbers the paper states, on normalised values (a French decimal comma and an English point are one number), so a figure that entered the deck from nowhere is caught before the room catches it. - Windows render path. PowerPoint COM
SaveAs(..., 32)thenpdftoppm; thedocument-skillssoffice.pywrapper fails here withAF_UNIX.sofficeis used when it is onPATH. A legacy.pptgabarit is converted withtalk_template.py --convert(SaveAs(..., 24)), leaving the original untouched.
Files:
- .claude/skills/paper2talk/SKILL.md
- .claude/skills/paper2talk/scripts/talk_rules.py — audience profiles, tier costs, cadence, budget, build contract
- .claude/skills/paper2talk/scripts/talk_model.py — deck-as-data validation + Jinja render of the Beamer/web targets
- .claude/skills/paper2talk/scripts/talk_doctor.py — preflight: buildable targets, per-tool degradation
- .claude/skills/paper2talk/scripts/paper_extract.py — paper → inventory (\input flattening, floats, equations, numbers)
- .claude/skills/paper2talk/scripts/talk_pptx.py — PowerPoint renderer: opens the lab gabarit, drops its sample slides, builds on its own layouts and placeholders
- .claude/skills/paper2talk/scripts/talk_template.py · fig_export.py · talk_render.py · talk_notes.py · to_a4.py · talk_validate.py
- .claude/skills/paper2talk/assets/deck_skeleton.js (no-gabarit fallback) · beamer_skeleton.tex.j2 · web_skeleton.html.j2
- .claude/skills/paper2talk/references/renderer-contracts.md · qa-loop.md
- .claude/skills/paper2talk/scripts/Test/ — thirteen offline suites, 182 tests (fixtures built in the test; no Office, no network)
- Harvest and licence findings: docs/superpowers/notes/2026-08-11-reference-skill-harvest.md
The two memories - the vault and the code graph¶
Two memories back this toolkit, and they do not overlap. The Obsidian vault holds what was
LEARNED, across every project: a failure and its root cause, a decision and why, a tool that
misbehaves. The graphify knowledge graph in graphify-out/ holds what this repository's code
IS right now: which function calls which, how one module reaches another, where a symbol
lives. The vault is permanent and hand-curated; the graph is derived from the files and
therefore rebuildable and disposable.
The routing rule follows from that. A question about this code goes to the graph first,
and query, path and explain are deterministic traversals that cost no model at all, so
one graph query beats grepping file by file. A question about a failure mode, a misbehaving
tool or a past decision goes to the vault first. Many tasks want both, in that order.
Both are reached the same way and only that way: dispatch the local-writer agent. It is
the single reader and the single writer of both memories. Consulting or refreshing the graph
by hand is the same breach as reading the vault by hand, and since 2026-08-30 the
vault-access-guard.py hook enforces BOTH at the tool boundary rather than only the vault. For the
vault it matches by PATH rather than by command; for the graph it matches the graphify-out/ path,
the graphify CLI, and the two graph audit scripts by name, because running a read-only health
check to learn the graph's state is a consultation in which the graph's path never appears.
The graph is refreshed by writing a file and then pointing graphify update <path> at it,
never by editing graph.json.
What the graph does not answer. Measured 2026-08-30 through a local-writer consultation:
every node carries _origin: ast, so the graph holds the code and the structure of each .md
file - headings, names, where things live - and no layer that read what those files say. Asked
"why is the Obsidian CLI write path forbidden", it returned 109 nodes of file names, command
names and test-class names, and none of the three measured reasons (the header-size threshold,
the CLI exiting 0 on a failed write, create making a numbered duplicate). Those reasons live in
.claude/CLAUDE.md and in the vault. So the graph is asked what calls what, and the vault is asked why.
Asking the graph for intent is the failure that hurts, because it returns names that read like an
answer. Adding the missing layer is possible and needs no API key - the graphify skill's own flow
has the host agent read the documents - but it is a deliberate, token-costing run, so
check-graph-health.ps1 reports the state as a note and does not fail on it.
The graph's own state is the one thing a session may read directly, because it is metadata
rather than content: scripts/audit/check-graph-health.ps1 is read-only and reports what is
in the graph, which files it claims to cover and never produced a node for, and whether any
covered file is newer than the graph itself. It exits 0 where there is no graphify-out/ at
all, so it is harmless in a project that has no graph.
obsidian-cli - Obsidian vault operations¶
Gives Claude the vault's allowed read/search command surface (read, search, files,
folders, property:read/property:set, tasks, links, tags, move, rename) and the single
sanctioned write path: a captured learning is drafted, dropped in
~/.claude/obsidian-outbox/ with a create|append path="..." directive on its first line,
and the obsidian-outbox-flush.py hook (SessionStart/SessionEnd) writes it into the vault
through the filesystem, verifying the effect by file size before and after rather than
trusting the CLI's return code.
create, append, and prepend (plus eval, dev:*, plugin:install, theme:install,
and every sync* except read-only sync:history) are forbidden commands. The measured
reasons: the write fails on the whole JSON header size (content, path, tty/cwd), not
the content alone - a 3850-byte header passes, a 4343-byte header does not, and 4096 bytes,
a Windows named-pipe buffer, falls in between; the CLI exits 0 even when the write failed,
so a script checking the return code archives notes that were never written; and create
on an existing file silently writes a numbered duplicate (Decisions 1.md) instead of
failing.
Files:
- .claude/skills/obsidian-cli/SKILL.md
- .claude/skills/obsidian-cli/references/command-reference.md - syntax of the allowed commands and the status of every other command
- .claude/skills/obsidian-cli/scripts/vault_consolidate.py - deterministic half of
consolidation: measures shared tags/domaine/term overlap and proposes links, decides
nothing; --mode links reports dead wiki-links read-only, and --apply <map.json> --yes
is the one guarded, map-validated, single-pass rewrite of existing links exempted from the
outbox-only write rule
- .claude/skills/obsidian-cli/scripts/vault_daemon.py - the unattended path. A raw drop
(unrouted text in ~/.claude/obsidian-outbox/raw/, three frontmatter keys, no directive)
is classified, drafted, filed, journalled and queued for consolidation without a session:
the cloud wrapper pushes, the local model decides. --once handles what is pending,
--drain runs the deferred work by hand, --dry-run lists and touches nothing. Anything
it is not confident about is parked in needs-review/ with its reason, for local-writer
to file with the whole reusable layer in context
- .claude/skills/obsidian-cli/scripts/daemon_outbox.py - the outbox layout that IS the
queue (raw, working, raw/sent, needs-review, state, queue), plus the write
lock, the one-daemon-per-machine singleton lock, the atomic claim by rename, and the sweep
that recovers a drop stranded by a crash
- .claude/skills/obsidian-cli/scripts/daemon_states.py - the per-state handlers; both
model calls are constrained by a JSON schema, and every refusal parks the event
- .claude/skills/obsidian-cli/scripts/daemon_drains.py - the deferred half: candidate
pairs judged one per call on the strict mechanism test, accepted edges appended
reciprocally with their sentence and journalled. Phantom repair stays human-gated
- .claude/skills/obsidian-cli/scripts/local_capability_probe.py - the gate that measured,
before any of this was written, that the daemon honours a JSON schema and re-uses a
prompt prefix
- .claude/skills/obsidian-cli/scripts/vault_lock.py, vault_journal.py, outbox_io.py -
the shared write path: one lock across sessions and processes, an append-only record of
every vault write with an --undo, and the single implementation the flush hook and the
daemon both call
- .claude/skills/obsidian-cli/daemon-config.json - every timeout, ceiling and threshold,
with its provenance; no such value is written in the code that uses it
latex-hygiene - mechanical LaTeX manuscript hygiene¶
Turns the hygiene checks paper-auditor, submit-checker, and thesis-auditor already describe
in prose into one script with subcommands, so the AI-usage score, the word count, and the brace
balance are computed the same way every session instead of by hand. One script, tex_check.py;
every subcommand takes paths or globs, never a hardcoded manuscript path, and accepts --json.
| Subcommand | Input | Output |
|---|---|---|
chars |
.tex files/globs |
per-file forbidden-character hits (line + name) and a total count |
aiscan |
.tex files/globs |
risk_score, weighted count per signal, lowest-deviation sentence window, a 15-word excerpt per hit |
wc |
.tex files/globs |
prose word count per file (floats and comments excluded), float count, total, page estimate |
wc --accepted |
.tex files/globs, optional --before <dir> |
word count of the accepted text (changes macros resolved); with --before, a before/after/delta/percent table |
abstract |
main .tex |
abstract word count, keyword count |
braces |
.tex files/globs |
final brace depth per file, the line of the first negative dip, and \begin/\end environment balance |
par |
.tex files/globs |
occurrences of \added/\deleted/\replaced whose argument crosses a blank line (the macros are not \long, so this breaks a build) |
citecov |
--tex <globs> --bib <file> |
cited keys absent from the .bib (dangling), and .bib entries never cited |
refcov |
.tex files/globs |
uncited labels, dangling \ref/\eqref/\cref targets, and duplicate labels |
patch |
--plan <audit_plan.md> --target <file.tex>, optional --author <id>, --dry-run, --init |
applies an audit plan by exact-match substitution, one occurrence required per edit; a FAILS: list and non-zero exit on any 0-match or 2+-match edit |
scan |
.tex files/globs, optional --bib <file>, --fail-on-markers |
post-write guard for control characters, damaged control-sequence residue, changes macros crossing a table/float boundary, a % comment that swallowed a row-terminating \\, a stale \cite inside a deleted span, and live \hl{}/\todo{} markers |
accept |
--target <file.tex>, optional --out <path>, --resolve |
the accepted source, [final]{changes}/[disable]{todonotes}, generated from the tracked source |
build |
--target <file>, optional --outdir out, --both |
pdflatex/bibtex/pdflatex/pdflatex with mandatory BIBINPUTS="..", refusing a .bib inside the output directory |
all |
files/globs | the aggregate of the read-side subcommands above |
aiscan reproduces the High/Medium signal weights and the risk_score formula stated in
paper-auditor.md Step 7.5 (a High signal counts 2, a Medium signal counts 1, toward raw_count).
The script is pure Python standard library, so it needs no requirements.txt and adds no
pip-audit surface.
Files:
- .claude/skills/latex-hygiene/SKILL.md
- .claude/skills/latex-hygiene/scripts/tex_check.py - thin CLI dispatching to the subcommand modules
- .claude/skills/latex-hygiene/scripts/tex_common.py, tex_chars.py, tex_braces.py, tex_par.py,
tex_citecov.py, tex_abstract.py, tex_wc.py, tex_aiscan.py, tex_aiscan_text.py
- .claude/skills/latex-hygiene/scripts/tex_patch.py, tex_scan.py, tex_build.py - the four
write-side subcommands (patch, scan, accept, build)
- .claude/skills/latex-hygiene/scripts/Test/test_tex_check.py - offline synthetic-string tests
- .claude/skills/latex-hygiene/scripts/Test/test_tex_patch.py, test_tex_build.py - offline
tests for the write side (10 + 7 tests); test_tex_build.py patches subprocess and
shutil.which, no LaTeX installation needed
opt-local-vram-llm - measured VRAM tuning for the local agents¶
Replaces six manual steps with one command when a newer model arrives for local-writer or
local-coder: read the manifest, write a Modelfile, create the tag, sweep, declare the
candidate, qualify. Every number it writes is measured on this card, none copied from a model
card or inferred from a parameter count. The objective, in order: admissible (`size_vram / size
= 0.999
from/api/ps, 300 MiB free, the rung not clamped by the model's own context maximum), fast enough (decode throughput at or above--throughput-floor, default 0.90, of the best admissible throughput), then largest window wins, ties broken on throughput.num_ctxclimbs the existing ladder;kv_cache_type(f16,q8_0,q4_0) is a daemon-wide variable read only at start, so each value costs a restart throughrestart-ollama.ps1, verified againstserver.logbefore anything is measured.num_gpuis pinned at 99, not swept. The rung measurement itself isoptimize_ollama.evaluate_rung, imported fromloop-engineerrather than duplicated. It stops at declaration: it writeslocal-model-config.json, declares the tag as a role candidate inlocal-models.json, and prints themodel_resolver.py --qualify` command without running it.
Files:
- .claude/skills/opt-local-vram-llm/SKILL.md
- .claude/skills/opt-local-vram-llm/scripts/vram_probe.py - read-only manifest and daemon facts
- .claude/skills/opt-local-vram-llm/scripts/vram_modelfile.py - pure Modelfile render
- .claude/skills/opt-local-vram-llm/scripts/vram_daemon.py - KV cache axis: write, restart,
verify, restore
- .claude/skills/opt-local-vram-llm/scripts/vram_optimizer.py - the driver: search, objective
function, report, declaration
- .claude/skills/opt-local-vram-llm/scripts/Test/test_vram_probe.py,
test_vram_modelfile.py, test_vram_daemon.py, test_vram_optimizer.py - four offline
suites (11 + 9 + 5 + 13 tests), no network, no GPU, no Ollama daemon
opt-local-stt-vram - measured speech-to-text selection for this GPU¶
The sibling of opt-local-vram-llm for the voice panel of chapter
10. You name the speech-to-text models; it downloads them, runs
each one in its own process beside the resident local LLM (the way the panel runs, everything on
VRAM), and prints a table to choose from. The first run, on 2026-09-26 with three dictated
recordings on a 6 GB RTX A1000, read:
| Model | Word error | 19.5 s recording | VRAM | LLM pushed out | Score |
|---|---|---|---|---|---|
| large-v3-turbo int8_float16 | 2.5% | 0.73 s | 993 MiB | 9.6% | 98.8 |
| small float16 | 10.0% | 0.56 s | 673 MiB | 3.4% | 95.0 |
| medium int8_float16 | 7.5% | 1.14 s | 929 MiB | 9.6% | 90.1 |
| large-v3 int8_float16 | 2.5% | 1.65 s | 1665 MiB | 26.4% | gated |
Word error is scored against the operator's own reference words, never a model's transcript.
Speed is full marks when the longest recording transcribes within the panel's live refresh
budget, because a caption that keeps up gains nothing from being faster. The LLM column comes
from the LLM process's own dedicated-VRAM counter before and after, since Windows demotes part of
the LLM rather than spilling the new model, and nvidia-smi cannot say whose memory it is. A
candidate over the gate (10% by default) is listed without a score; one that fails to download or
load is not runnable with its reason. --rescore recomputes the table from a saved run after a
reference correction, with no model run. NeMo models are a declared seam for a larger GPU, not
yet an engine.
Files:
- .claude/skills/opt-local-stt-vram/SKILL.md, stt-bench-config.json
- .claude/skills/opt-local-stt-vram/scripts/stt_bench.py - the CLI, one child process per candidate
- .claude/skills/opt-local-stt-vram/scripts/stt_score.py - pure scoring and the table
- .claude/skills/opt-local-stt-vram/scripts/gpu_memory.py - per-process GPU memory
- .claude/skills/opt-local-stt-vram/scripts/engines/ - faster_whisper_engine.py, nemo_engine.py
- .claude/skills/opt-local-stt-vram/scripts/Test/ - four offline suites (15 + 11 + 9 + 16
tests), no model, no GPU, no Ollama
work-ugs-audit - grading undergraduate reports¶
Grades a folder of undergraduate reports (PDF) one report at a time with the local models of this machine, so a
confidential report never reaches a cloud model. For every report it cuts the PDF into pages and figures, grades each
rubric item with evidence quoted from the report, reviews the language with language-review and each figure with
figure-review (scope undergraduate), checks the cited references, audits the grades with a second model, then writes
an annotated PDF and a correction annex. Across the batch it measures the spread of the totals against calibration
targets and, when out of band, offers a second loop that carries a calibration note.
The driver is ugs_driver.py with the subcommands prepare, run, batch and status, each with --dry-run and
--json. Exit codes: 0 done, 1 a model step could not run (resume later), 2 refusal, 3 batch out of band. The work
folder is _correction/, inside the reports folder. Three model roles, ugs-grader, ugs-auditor and ugs-vision, are
adopted once by the owner with model_resolver.py --adopt-role <role> <tag> --reason "<measurement>"; there is no
fallback and no cloud grading. The work-ugs-audit agent drives the driver through the /work-ugs-audit command and
reads only the rubric and the step ledger.
Files: .claude/skills/work-ugs-audit/SKILL.md, scripts/ (one module per step, ugs_bridge.py, ugs_text.py,
report_prepare.py, rubric_check.py, batch_stats.py, pdf_annotate.py, pdf_annex.py, ref_check.py), assets/
(the configuration with provenance on every value, the rubric schema and templates, the calibration targets),
prompts/, and an offline test beside each script in scripts/Test/.
figure-review - figures of a report, paper or thesis¶
One place that knows how to look at a figure, for the student-report audit (criteria scope undergraduate) and for the
four research auditors (scope research; both for the two criteria they share). Each criterion of
assets/figure_criteria.json says whether a script measures it or a model judges it, and whether it needs the
source or the image. Three entry points: the figures of a compiled PDF (figure_extract.py, figure_checks.py), the
figures of a LaTeX source (figure_tex.py, figure_render.py) and a single image (figure_image.py).
A figure a model cannot see (TikZ, draw.io, SVG, EPS, PDF, GIF, BMP, TIFF, WebP) is rendered to PNG only when the caller
passes --render; PNG and JPEG are always shown as they are. A missing tool, a failed compile or a timeout gives
not_run with the tool and the reason, never a broken picture. Rendering TikZ compiles the document's own LaTeX, which is
untrusted, so a source using a file or shell primitive is refused before any compile; the limits are in the SKILL.md.
Files: .claude/skills/figure-review/SKILL.md, assets/figure_criteria.json, prompts/figure.md, scripts/ (six
modules, PyMuPDF pinned in requirements.txt), and an offline test beside each module in scripts/Test/.
language-review - one table of language correction codes¶
Keeps the language correction codes (spelling, grammar, agreement, punctuation, style, register, terminology, typography) and the composition flags R1.x and R2.x in one table, so the research auditors (LaTeX track changes) and the undergraduate report grading (PDF annotations) cite the same code for the same defect.
Files: .claude/skills/language-review/SKILL.md, assets/correction_table.csv, assets/correction_table.md,
assets/language_categories.json.
aider-setup and rt-observe are big enough to get their own chapters rather than a
subsection here: 14-aider-pipeline.md and
10-rt-observe-dashboard.md.