playbooks

home / skills / tkersey / dotfiles / deckset

deckset skill

/codex/skills/deckset

This skill generates Deckset markdown presentations from conversation context, preserving claims, structure, and presenter notes for cohesive narrative slides.

npx playbooks add skill tkersey/dotfiles --skill deckset

Review the files below or copy the command above to add this skill to your agents.

Files (11)
SKILL.md
3.5 KB
---
name: deckset
description: Generate Deckset markdown presentations from conversation context with high semantic fidelity. Use when requests mention decks, slides, presentations, speaker notes, or Deckset markdown output, especially when converting an existing conversation into a narrative slide flow. This skill refreshes upstream Deckset markdown docs and the configured gist examples on every run before drafting.
---

# Deckset

## Workflow

1. Refresh 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
   - Optional: `--max-age-sec 3600` to reduce network refreshes
2. Read refresh metadata:
   - `references/refresh-metadata.json` -> capture `refreshed_at`, `docs_source`, `gist_source`, `used_cache_fallback`
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. Add a provenance stamp as a presenter note on slide 1:
   - `^ deckset-skill refresh: refreshed_at=<...> docs=<...> gist=<...> cache_fallback=<...>`
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: slide 1 includes the refresh stamp and it matches `references/refresh-metadata.json`.

## References

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

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

Overview

This skill generates Deckset-compatible markdown presentations from a conversation with high semantic fidelity. It refreshes upstream Deckset markdown docs and example gists on every run, then drafts a single coherent deck with presenter notes where helpful. Output is sized to content and follows Deckset syntax rules to ensure parseable slides.

How this skill works

On invocation it first refreshes upstream references; if refresh cannot reach sources the skill falls back to local cache and discloses that. It analyzes the conversation to extract audience, objective, key claims and evidence, constraints, and required talking points. The skill builds a narrative spine—opening context, core argument sequence, implementation or evidence details, and a decision summary or call to action—then renders one Deckset markdown deck and runs quality gates for fidelity, coherence, syntax, and delivery.

When to use it

  • When you need a slide deck drafted directly from a chat or meeting transcript.
  • When requests mention decks, slides, presentations, speaker notes, or Deckset markdown output.
  • When converting an existing conversation into a narrative slide flow.
  • When you want Deckset-specific syntax and presenter notes included.
  • When you need an output that stays faithful to claims and their hierarchy.

Best practices

  • Provide explicit audience and objective early in the conversation for best alignment.
  • List must-cover talking points or constraints to ensure they appear in the deck.
  • Keep each major idea focused—the skill produces one major idea per slide by default.
  • Request staged reveals explicitly if you want incremental-build steps.
  • Review the disclosed refresh status if external references are required for accuracy.

Example use cases

  • Turn a product strategy chat into a persuasive investor update with speaker notes.
  • Convert a technical design discussion into a step-by-step implementation deck.
  • Draft an executive summary deck from meeting minutes with clear call to action.
  • Create training slides from a Q&A session, preserving claims and supporting evidence.
  • Refresh cached examples and docs before generating a style-consistent Deckset deck.

FAQ

Will the skill always refresh external references?

Yes. It attempts to refresh upstream docs and gist examples on every run; if refresh fails it uses the local cache and notes that fallback.

Can I request a specific slide count or theme?

You can request a preferred slide count or theme, but the default is to size slides to content and avoid forcing a theme unless explicitly asked.