# slideops

Adopt this skill: https://proskills.md/skills/other/glukicov-slideops-skills-slideops

Page: https://proskills.md/skills/other/glukicov-slideops-skills-slideops
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/slideops/SKILL.md
size: 8016
upstream: https://github.com/glukicov/slideops/blob/main/skills/slideops/SKILL.md

````text
---
name: slideops
description: 'Use when the user asks for slides, a slide deck, or a presentation about a code repository, one of its subsystems, a feature, an architecture area, or its recent changes. Triggers include "make slides", "build a slide deck", "create a presentation", "HTML slides for this repo", "overview deck", "team update slides", "slides for our latest changes", or naming a topic and asking for a deck about it. Also use when the user asks whether an existing deck still matches the code, or wants one rechecked, refreshed, or kept in sync automatically: "is this deck still accurate", "check the slides against the code", "did anything we documented change", "refresh the architecture deck", "these docs are stale", "fail the build when the deck stops matching the code", or asks to wire that check into CI, a pull request, or an agent hook. Also use for Markdown documentation instead of slides ("write markdown docs", "a design doc with citations", "docs that know when they go stale"), including PDF export of a doc.'
license: MIT
compatibility: Needs a headless Chrome or Chromium binary (Playwright cache or system install) and Python 3 for the verification pass. Reads the target repository with git. Network access only if you opt into Mermaid diagrams (one npx download) or brand-colour extraction; everything else works offline.
metadata:
  author: Gleb Lukicov
  version: 1.1.2
---

# SlideOps: generate a deck from a repository, and keep it true

This skill has two jobs, and the second one is the point.

**Build**: turn a repository into a deck whose every claim came from the code, not from a
model's impression of the code. **Keep in sync**: make that deck able to prove, months
later, whether it still matches the repository, cheaply enough that nobody has to
remember to care.

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. That turns "is this deck still accurate?" from a question somebody has to
answer by reading into a command that answers itself:

```bash
python3 scripts/check.py docs/slides/ --repo .
```

Standard library only. No model, no network, no tokens, milliseconds to run. Two scripts
ship with this skill and do all of it: [`scripts/cite.py`](scripts/cite.py) writes the
citations while you build, and [`scripts/check.py`](scripts/check.py) reads them back
afterwards. Writing the citations as you go (Step 3) is therefore not optional decoration:
it is the entire reason the deck can be maintained instead of rewritten. See
[`references/freshness.md`](references/freshness.md) for the mechanism and
[`references/automation.md`](references/automation.md) for wiring it into pull requests,
scheduled refreshes, and agent hooks.

## Which job is this?

- The user wants a **new deck**: start at Step 0 below.
- The user wants **Markdown documentation instead of slides** (a doc that lives in the
  repo and renders on GitHub, with the same citations and the same freshness check):
  follow [`references/markdown.md`](references/markdown.md). It reuses this file's
  research, confidentiality, and refresh rules and swaps the build and verify steps;
  [`references/markdown-pdf.md`](references/markdown-pdf.md) covers exporting such a doc
  to PDF. Checking or refreshing an existing `.md` doc is the same `check.py` workflow
  as decks; sweeps pick both up together.
- The user is asking whether an existing deck is **still accurate**, wants one
  **refreshed**, or wants the check **automated**: go straight to
  [Refreshing an existing deck](#refreshing-an-existing-deck) near the end. Do not rebuild
  a deck from scratch because a few slides drifted.

---

Produces a single self-contained HTML slide deck (no build step, no CDN dependencies):
one 1280×720 slide per screen, click/arrow-key/URL-hash navigation, a progress bar and
slide counter, an Esc-toggled overview grid (deep-linkable as `#overview`), optional
per-slide speaker notes (`<aside class="notes">`, toggled with N, invisible in exports),
and, on request, a paginated PDF export. Every slide is grounded in the real repository:
real code snippets, real commands, real screenshots, real numbers. Nothing is invented
to fill space.

A worked example ships with the skill: [`examples/skill-demo.html`](examples/skill-demo.html)
is a 17-slide deck about this skill, built by this skill, showing the patterns, all four
theme presets on real decks, and an inlined Mermaid diagram.

Two starting points, chosen with the user up front:

- **General overview**: what the project is, how to install/set it up, how to run it,
  its main features, its architecture at a glance. Mirrors a README/onboarding walkthrough.
- **Focused topic**: one subsystem, one recent change, one architecture decision, one
  workflow. Goes deep rather than wide.

---

## Step 0: Orient, then ask

Spend ~2 minutes scanning the repo **before asking anything**, so every question you ask
is concrete and every option you offer actually exists: read the README and the
manifest(s) that define the product (per-app in a monorepo), run `git log --oneline -15`
and glance at the top-level tree and `docs/`, and check whether `docs/slides/` already has
decks (open one: its title slide, theme and build stamp show the local conventions). Do
not start slide research yet; this pass is only to ask good questions. The scan itself may hit stale doc pointers; note them
and move on (Step 1's code-wins rule deals with drift later).

What you find shapes the candidates:

- **Existing decks remove or reframe candidates.** A topic an existing deck already covers
  is off the proposal list, unless meaningful commits have landed since that deck's date,
  in which case offer "update the existing X deck" as its own candidate. Disclose the
  existing decks in one line at the top of the intake.
- **Skip meta noise in "why now".** Recent commits about tooling, docs, or slide decks
  themselves don't justify a deck; reach back to the most recent *product* activity, and
  don't re-justify a candidate with work an existing deck already presents.

Then ask everything in **one compact intake** (use your environment's structured-question
tool if it has one; otherwise a single message with lettered options). Mark the default
in each list, skip any item the user already answered, and never exceed these six:

1. **Topic.** Propose 3-4 concrete candidates you found in the scan, each with a one-line
   "why now" (e.g. "v2.3 shipped last week: a what's-new deck", "the `sync/` subsystem is
   the largest and undocumented: a deep dive", "no onboarding doc exists: a general
   overview"), plus "something else: tell me". Never ask a bare "what should the deck be
   about?": the scan is what makes this question answerable in one click. Mark as default
   the candidate you would genuinely bet the user wants given the repo's core domain and
   its deck history (a core subsystem with zero coverage usually beats a
   recently-changed-but-already-presented area), not mechanically the most recent change.
2. **Audience and venue.** New joiners (onboarding) · team sprint/standup · stakeholder or
   exec review · conference/meetup. This drives jargon level, pacing, and the Sizing row.
3. **Length.** Offer the Sizing table rows as time slots ("5-min lightning ≈ 8-15 slides",
   "20-min deep dive ≈ 12-20", "45-min onboarding ≈ 20-35").
4. **Design.** Theme menu from [`references/themes.md`](references/themes.md): Ledger
   Light (default) · Ledger Dark · midnight · graphite · match a brand (ask for the URL/style
   guide; fetch it for real per [`references/style-guide.md`](references/style-guide.md)
   § Theming, never invent colors from a description). Optionally a font choice
   (themes.md § Font options) if the user signals caring about typography. If the user
   hesitates between themes or asks to see them, show rather than tell: copy the
   template
````

## File: README.md
upstream: https://github.com/glukicov/slideops/blob/main/README.md

````text
<div align="center">

<h2>Generate a deck from your code in minutes. Find out in milliseconds when it stops being true. Then rebuild only the slides that drifted.</h2>

[![CI](https://github.com/glukicov/slideops/actions/workflows/ci.yml/badge.svg)](https://github.com/glukicov/slideops/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/glukicov/slideops?color=7a7f1f)](https://github.com/glukicov/slideops/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.14](https://img.shields.io/badge/python-3.14-blue)](pyproject.toml)
[![Zero dependencies](https://img.shields.io/badge/dependencies-none-success)](.github/workflows/ci.yml)
[![Agent Skill](https://img.shields.io/badge/Claude%20Code-Agent%20Skill-D97757)](https://agentskills.io/specification)
[![skills.sh](https://skills.sh/b/glukicov/slideops)](https://skills.sh/glukicov/slideops)

**[Install](#install) · [Use](#use) · [Features](#features) · [Docs](#documentation) · [Demo deck](https://github.com/glukicov/slideops/releases/latest/download/skill-demo.pdf) · [Why](https://medium.com/@lukicov/your-documentation-is-a-build-artifact-start-treating-it-like-one-ab48df61b1e0)**

</div>

![The same slide rendered in Ledger Light and Ledger Dark, split diagonally](docs/hero.png)

<p align="center"><i>The demo deck is 17 slides about SlideOps, built by SlideOps: open the
<a href="skills/slideops/examples/skill-demo.html">HTML</a> or the
<a href="https://github.com/glukicov/slideops/releases/latest/download/skill-demo.pdf">PDF</a>.</i></p>

Writing documentation isn't the bottleneck any more. Keeping it true is. The deck that said
we run two database migrations still says two, a year after we started running ten 😅.

SlideOps is a pair of [Agent Skills](https://agentskills.io/specification) for Claude Code
and compatible coding agents. It treats a generated document the way you'd treat generated
code: it's built from a source, and it records which source it came from.

The reasoning behind it is written up in
**[Your documentation is a build artifact. Start treating it like one](https://medium.com/@lukicov/your-documentation-is-a-build-artifact-start-treating-it-like-one-ab48df61b1e0)**.

![The demo deck's overview grid](docs/overview.png)

<p align="center"><i>Press Esc in any deck for the overview grid.</i></p>

## Install

### Claude Code

This repo is its own marketplace, so two commands are the whole setup, and it's the only
install that keeps itself up to date. Add the marketplace:

```
/plugin marketplace add glukicov/slideops
```

Then install the plugin from it:

```
/plugin install slideops@slideops
```

### Any agent with the [skills CLI](https://skills.sh)

One line, and it works everywhere:

```bash
npx skills add glukicov/slideops
```

### Codex, Copilot CLI, OpenCode

Or a plain checkout:

```bash
git clone https://github.com/glukicov/slideops && cd slideops
./install.sh
```

All four agents read `SKILL.md` and nothing needs porting between them. For the symlink and
snapshot installs, the per-agent table and how updates reach you, see
**[docs/install.md](docs/install.md)**.

> [!NOTE]
> Third-party marketplaces have **auto-update off by default**. Turn it on once in
> `/plugin` → **Marketplaces**, or new versions only arrive when you run
> `/plugin marketplace update slideops` by hand.

## Use

Open a repository and say:

> [!TIP]
> ### 💬 make slides about this repo

SlideOps scans the repo first, then asks one compact set of questions: which topic (it
proposes concrete candidates it found, each with a "why now"), audience, length, theme and
extras. You get an outline to approve before it writes any HTML.

If you already know what you want, skip the intake:

> [!NOTE]
> ### 💬 deep dive on the auth subsystem, Ledger Dark theme, 15 slides, with a PDF

Prefer a document to a deck? Since v1.1.0 the same mechanism writes Markdown:

> [!TIP]
> ### 💬 write markdown docs for the sync subsystem

You get a single `.md` that renders on GitHub, with every quoted snippet carrying an
invisible citation comment (`<!-- slideops data-src="app/main.py:40-58"
data-sha256="a1b2c3d4e5f6" -->`) above its fence, Mermaid diagrams as native fences, and
the build commit stamped on line 1. The same `check.py` sweep verifies docs and decks
together, and the same `--json` repair brief lets an agent regenerate only the sections
that drifted. PDF export mirrors the deck path with a verified, print-paginated export.

Months later, in the same repository:

> [!IMPORTANT]
> ### 💬 is the architecture deck still accurate?

The agent sweeps the deck folder and triages by status. It re-quotes whatever merely moved,
and flags the slides whose *claim* might no longer hold. It repairs what drifted instead of
regenerating the deck, so the pacing and narrative you signed off on the first time survive.

## Features

- **Freshness checking.** `scripts/check.py` sweeps a whole `docs/slides/` folder and
  reports which slides cite code that has changed, moved or vanished since the deck was
  built, then suggests the fix or hands an agent a JSON repair brief. No model, no network,
  no tokens: standard library Python, and it runs in milliseconds.
- **Markdown docs with the same guarantee.** The `.md` carrier uses HTML comments instead
  of attributes, headings instead of slide numbers, and shares every status, the sweep,
  and the repair brief with decks. The worked example is
  [`skill-demo.md`](skills/slideops/examples/skill-demo.md), checked by this repo's CI.
- **One self-contained file per deck.** No build step, no CDN, works offline, attaches to
  an email.
- **Navigation:** arrow keys, click-to-advance, URL hash deep links, an Esc-toggled
  overview grid, and speaker notes on `N` (never visible in screenshots or exports).
- **13 slide patterns:** title, agenda, section divider, prose + cards, reference table,
  before/after code, annotated snippet (half and full width), flow diagram, lane
  comparison, image + caption, chat bubbles, closing.
- **4 themes, one block each.** Every color derives from a single `:root` token block via
  `color-mix()`, so switching theme is one replacement: **Ledger Light** (default),
  **Ledger Dark**, **Midnight**, **Graphite**. Or point it at a brand's real CSS values and
  map those onto the token roles.

  | Ledger Light (default) | Ledger Dark |
  |:---:|:---:|
  | ![Ledger Light](docs/theme-light.png) | ![Ledger Dark](docs/theme-dark.png) |
  | *Same deck, same markup, same content.* | *One `:root` block apart.* |

- **Mermaid diagrams** pre-rendered to inline SVG at build time and themed from the deck's
  own tokens, so the deck stays dependency-free.
- **Verified PDF export.** The companion skill renders the finished PDF back to images and
  checks the pages, because a PDF can have the right page count and still hand you blank
  images.

## Documentation

| Page | What's in it |
|---|---|
| 📦&nbsp;**[Install](docs/install.md)** | Every install path, all four agents, updating, requirements, what gets installed |
| 🔎&nbsp;**[Freshness](docs/freshness.md)** | Citations, the status table, the cost model, where to automate, the accuracy contract, what never reaches a slide |
| 🛠️&nbsp;**[Development](docs/development.md)** | Working on this repository: the gate, CI guards, generated artifacts, releasing |
| 📋&nbsp;**[Changelog](CHANGELOG.md)** | What changed in each release |

Inside the skill, `skills/slideops/references/` holds the specifications the agent reads:
freshness, automation, style, themes, diagrams and verification.

## Credits

Prior art worth knowing: [frontend-slides](https://github.com/zarazhangrui/frontend-slides)
for visual-first theme selection, and
[presentation-skills](https://github.com/ktundwal/presentation-skills) for pioneering the
render-then-look visual QA loop that SlideOps also relies on. What SlideOps adds is the
*Ops* half: content grounded in a repository, and a cheap way to ask later whether it
````
