# Deckset

> Create Deckset markdown presentations and speaker notes from conversation context. Use for explicit Deckset requests, markdown slide decks, or edits to an existing Deckset deck. PowerPoint and Google Slides artifacts belong to the presentations skill.

- Skill: `tkersey/deckset` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add tkersey/deckset`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tkersey/deckset/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tkersey (https://skillmd.com/u/tkersey)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tkersey/deckset

---


# Deckset

## Workflow

1. Refresh/check upstream references first, on every invocation (run from this skill directory):
   - `uv run scripts/refresh_sources.py`
   - Optional: set `GH_TOKEN`/`GITHUB_TOKEN` to avoid GitHub API rate limits
   - Do not pass `--max-age-sec` during normal skill use; the default should check upstream every time.
   - `references/refresh-metadata.json` is an ignored local cache for conditional requests and diagnostics. Do not stage, commit, or require it to be clean.
   - The refresh script must not rewrite tracked reference files for timestamp/provenance-only changes. Treat clean `cache_not_modified` output as a valid refresh.
2. Use the script's JSON output as the refresh status source:
   - capture `docs_source`, `gist_source`, `cheatsheet_source`, and `used_cache_fallback`
   - read `references/refresh-metadata.json` only for local diagnostics if the output indicates fallback or unavailable references
3. Read the conversation and extract:
   - audience
   - objective
   - timebox (talk length) + format (demo, deep dive, status update, pitch)
   - key claims and evidence
   - constraints (must-include points, required sections, theme/footer if specified)
4. Build a narrative spine and a slide outline (titles + 1-line intent) before writing slides.
5. Draft a single Deckset markdown deck.
6. Do not force a provenance stamp into the deck. Add a short presenter note only when refresh status materially affects delivery, such as cache fallback or unavailable references.
7. Run quality gates before returning output.

## Output Contract

- Output exactly one complete Deckset markdown deck by default.
- Include presenter notes using `^` when they improve delivery.
- Defaults:
  - if audience is not specified, assume a mixed technical audience
  - if duration is not specified, target ~10 minutes / ~10 slides (do not force a hard slide count)
- If missing duration/audience would materially change the deck, ask exactly one clarifying question; otherwise apply the defaults.
- Keep styling prompt-driven:
  - do not force a theme/footer/slidenumbers/autoscale unless requested
  - do not force a fixed slide count; size to content
- Prefer `references/deckset-cheatsheet.md` over the HTML docs cache.

## Deckset Rules

- Separate slides with `---`.
- Prefer `#` and `##` headings for slide structure.
- Use `[fit]` only when needed to preserve readability.
- Keep one major idea per slide unless the content is inherently coupled.
- Keep code blocks concise and language-labeled.
- Use incremental build commands only when the user asks for staged reveals.
- Global commands (e.g. `theme:`, `footer:`, `slidenumbers:`) must be at the top of the file with no blank lines between them.
- If you open columns (`[.column]`), always close with `[.end-columns]`.

## Quality Gates

- Fidelity: preserve the conversation's claims and hierarchy.
- Coherence: each slide should have a clear purpose in the narrative.
- Syntax: deck parses as valid markdown with Deckset commands placed correctly.
- Delivery: presenter notes clarify talking points, not duplicate slide text.
- Structure: every slide has a title; one major idea per slide.
- Density: keep slides scannable (<= 6 bullets per slide; move detail into presenter notes).
- Provenance: disclose cache fallback or unavailable references in the response summary; do not require timestamp-only reference mutations or deck notes.

## References

- Cheatsheet (preferred):
  - `references/deckset-cheatsheet.md`
- Full docs cache (fallback):
  - `references/deckset-markdownDocumentation.html`
- Gist example cache:
  - `references/examples/*.md`
- Local refresh metadata (ignored, operational cache only):
  - `references/refresh-metadata.json`

If `used_cache_fallback` is true, disclose that in the response summary.