slideops – skill Tài liệu & Office cho agent AI

Bundled upstream support

Supporting files are included at skill-relative paths. See [UPSTREAM-NOTICE.md](UPSTREAM-NOTICE.md) for their pinned sources, licenses, hashes, and import changes.

SlideOps: slides from a repo, that tell you when they go stale

> Catalog copy, frozen at v1.0.0. The canonical source is

> [glukicov/slideops](https://github.com/glukicov/slideops), which also carries the deck

> template, the two citation scripts, the reference docs, and the companion

> slides-to-pdf skill. For upstream updates consult that repository; this catalog bundles the support files listed in UPSTREAM-NOTICE.md.

Overview

SlideOps has two jobs, and the second one is the point. Build: turn a repository into

an HTML slide deck whose factual claims are grounded in reviewed code, not from a

model's impression of the code. Keep in sync: report drift of cited text later; semantic accuracy still requires review.

The mechanism joining them is a citation. Every quoted snippet records the file, the line

range, and a hash of those source lines at build time, and the deck records the commit it

was built from. "Are these slides still accurate?" becomes a command instead of a

re-read: a standard-library Python script diffs each citation against the current code

and reports CURRENT, MOVED, CHANGED, or MISSING. No model, no network, no tokens,

milliseconds to run.

When to Use This Skill

• Use when the user asks for slides, a slide deck, or a presentation about a code

repository, one of its subsystems, a feature, or its recent changes: "make slides",

"overview deck", "team update slides", "HTML slides for this repo".

• Use when the user asks whether an existing deck still matches the code, or wants one

rechecked, refreshed, or kept in sync: "is this deck still accurate", "check the

slides against the code", "these docs are stale".

• Use when the user wants deck freshness wired into CI, a pull request check, or an

agent hook: "fail the build when the deck stops matching the code".

• Do not use for slide decks about anything other than a codebase (a sales deck, a

lecture); the citation mechanism assumes a git repository as the source of truth.

How It Works

Step 1: Inspect the bundled source

This tree includes the HTML template, citation scripts and three references at paths relative to this SKILL.md; no upstream install is required to inspect them. The companion slides-to-pdf, themes.md, style-guide.md and freshness.md are not bundled. Use an already reviewed installed browser/rendering tool when needed; missing external tools need a separately scoped setup, not a moving installer fallback.

Step 2: Build a deck

The skill walks a fixed pipeline: a two-minute repo scan, one compact intake (topic,

audience, length, theme, scope, extras), an outline checkpoint before any HTML is

written, then slide-by-slide construction from a verified template. Every snippet is

cited as it is written. Run the citation script from inside the repository being

presented, via its installed path (an agent resolves scripts/ against the skill's own

directory automatically; the paths below are for running it yourself after

install.sh):

python3 ~/.agents/skills/slideops/scripts/cite.py app/main.py:40-58 --repo . --snippet   # prints data-src + data-sha256
python3 ~/.agents/skills/slideops/scripts/cite.py --stamp deck.html --repo .             # stamps the build commit

--repo always points at the repository the deck is about, never at the SlideOps

checkout.

Every slide is then rendered with headless Chrome and visually verified before the deck

is considered done.

Step 3: Check it later, for free

From inside the repository being presented, same path convention as Step 2:

python3 ~/.agents/skills/slideops/scripts/check.py docs/slides/ --repo .

Real output, from the demo deck that ships with the skill:

Deck: skill-demo.html
Built: commit=179bbdb date=2026-08-28 repo=slideops

  slide   9  THEMING        skills/slideops/assets/template.html:22-45    CURRENT
  slide  14  MERMAID        skills/slideops/references/diagrams.md:55-59  CURRENT

2 current, 0 stale, 2 cited in total.

MOVED means the hashed source block still exists elsewhere; review surrounding context before deciding whether prose remains true.

CHANGED means the quoted code was edited (read the diff, decide whether the slide's

claim survived). MISSING means the file is gone (the slide is probably obsolete). The

--json flag emits a citation repair brief per stale citation, so an agent can fix

drift without re-reading the repository.

Examples

Example 1: New deck

User: make slides about this repo
Agent: [scans repo, proposes 3-4 concrete topics with a "why now" each,
        asks one compact intake, shows an outline, then builds and
        visually verifies a cited HTML deck at docs/slides/]

Example 2: Freshness check in CI

python3 tools/slideops-check.py docs/slides/ --repo . --exit-zero   # report-only PR annotation

The canonical repo's references/automation.md has the PR-check workflow, advisory hook

variants, and a delegated-refresh recipe. check.py is one dependency-free file, meant

to be vendored into the deck's own repo.

Best Practices

• ✅ Cite with cite.py, never by hand: a hand-computed hash silently reports CHANGED

months later and nobody can tell whether the code moved or the build was sloppy.

• ✅ Repair a drifted deck; do not rebuild it. Fix only the slides whose citations went

stale, then re-stamp.

• ✅ Automate the check for evergreen decks (onboarding, architecture); leave snapshots

(sprint updates, conference talks) frozen deliberately.

• ❌ Do not run check.py against a PDF export: citations live in the HTML, so the PDF

reports "No citations found in this deck".

• ❌ Do not block every commit on the check. Report-only on pull requests first; a docs

gate on the fast path trains people to pass --no-verify.

Limitations

• Needs a headless Chrome or Chromium binary (Playwright cache or system install) for

the visual verification pass, and Python 3 for the citation scripts.

• The bundled template has no external assets; generated decks are offline only after all images/fonts/SVGs are embedded and remote references checked. Optional tooling setup and

brand-color extraction from a live style guide.

• The check verifies quoted snippets against the code; it cannot verify prose claims

that cite nothing.

• Drift detection assumes the deck and the code share a git repository.

Security & Safety Notes

• Ask before cloning the upstream repository, running install.sh, creating skill

symlinks in the user's home directory, downloading an optional npx package, or

writing deck output. Show the exact pinned commit and destination paths first, and

preserve any existing skill entries instead of overwriting them silently.

• The citation scripts are standard-library-only Python: no dependencies, no network,

no tokens.

• The skill declares no allowed-tools, deliberately: the host agent's own permission

model stays in charge, and headless Chrome keeps its sandbox.

• The skill carries an explicit confidentiality rule for deck content: never read or

quote secrets, keys, .env files, production logs, or customer data; redact internal

hostnames and identifiers; and finish with a redaction scan of the rendered slides,

because decks are documents that leave the repository.

• Citation hashes normalize decoded text lines and use a 12-hex prefix; they are drift indicators, not cryptographic authenticity, byte-identity or semantic proof. Empty/unverified citations must not pass a strict freshness gate.
• File writes are limited to the deck output folder (default docs/slides/) plus its

companion README.

Common Pitfalls

• Problem: check.py on an exported PDF reports no citations.

Solution: Run it against the HTML deck; the PDF is a derived artifact from the

companion slides-to-pdf skill.

• Problem: A freshly built deck already reports CHANGED.

Solution: That is a build defect, not a future problem: a snippet was quoted and

then edited, or a hash was hand-computed. Re-cite with cite.py before shipping.

• Problem: Chrome is not found on the verification step.

Solution: The canonical repo's references/verification.md has the cross-platform

discovery recipe (Playwright cache first, then system installs).

Related Skills

• slides-to-pdf (same canonical repo): screenshots every slide at 2x, prints a

page-per-slide PDF, and verifies the result by rendering the PDF back to images.

• @2slides-ppt-generator: API-driven deck generation from text or documents; use it

when the source material is not a code repository.