CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

jbaruch/speaker-toolkit

Twelve skills for conference speakers covering rhetoric analysis, talk authoring, deck building and export, CFP submissions, publishing, illustrations, shownotes, screencast production, and vertical shorts, informed by a 113-entry Presentation Patterns taxonomy (83 observable: 64 patterns + 19 antipatterns; 30 unobservable: 21 patterns + 9 antipatterns).

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Medium

Suggest reviewing before use

Overview
Quality
Evals
Security
Files

schemas-config.mdskills/vault-profile/references/

Vault Config & Intent Schemas

Config Fields — Clarification Session Questions

Fields below template_skip_patterns are asked during vault-clarification Step 6 (first session only) when empty. The question column shows what to ask the speaker.

Config fieldQuestion
speaker_name"Name as it appears on slides?"
speaker_handle"Social handle for footers?"
speaker_website"Website for talk resources?"
shownotes.source.type"Where do your shownotes live? Local Jekyll, Hugo, Eleventy, Astro, a remote URL, or no shownotes site?"
shownotes.source.path_or_url"Path (or base URL) to the shownotes site root?"
shownotes.source.talks_subdir"Subdirectory under the site root where talk entries live? (e.g., _talks, content/talks)"
shownotes.url.base"Base URL where the shownotes site is deployed?"
shownotes.url.template"Permalink template for a single talk? (e.g., /talks/{slug}/, /{yyyy}-{mm}-{dd}-{slug}/)"
shownotes.thumbnail_path_template"Where in the site repo does the SSG template expect the talk thumbnail? (e.g., assets/images/thumbnails/{slug}-thumbnail.png)"
shownotes.slug_convention.template"Convention for talk slugs? (e.g., {venue-compact}{yy}-{short-id})"
template_pptx_path"PowerPoint template path?"
presentation_file_convention"File organization? (default: {conference}/{year}/{talk-slug}/)"
publishing_process.export_format"How do you export final decks — PDF, keep .pptx only, or both?"
publishing_process.export_method"How do you produce the PDF? (e.g., PowerPoint AppleScript, LibreOffice CLI, manual)"
publishing_process.qr_code.enabled"Do you put QR codes in your decks? (true or false)" — qr_code is an object: write each answer to its own sub-field, never the parent as prose.
publishing_process.qr_code.target(Only if enabled) "What should the QR link to: the talk's shownotes page (shownotes_url) or another URL (custom_url)?"
publishing_process.qr_code.custom_url(Only if target=custom_url) "Which full https URL?"
publishing_process.qr_code.slide_position(Only if enabled) "Which slides get it: closing, shownotes_slide, or both?"
publishing_process.additional_steps"Any other distribution steps after exporting?"

Full Config Schema

The exclusion value below is one illustrative valid customization, not the canonical owner default.

{
  "config": {
    "schema_version": 3,
    "vault_root": "~/.claude/rhetoric-knowledge-vault",
    "vault_storage_path": "/native/absolute/database-parent (optional; null/absent uses that parent)",
    "pptx_source_dir": "/path/to/Presentations",
    "python_path": "/path/to/python3",
    "template_skip_patterns": ["template"],
    "pptx_directory_exclusions": ["example-tool-cache"],
    "speaker_name": "",
    "speaker_handle": "",
    "speaker_website": "",

    "shownotes": {
      "enabled": true,
      "source": {
        "type": "local_jekyll",
        "path_or_url": "/path/to/shownotes-site-root",
        "talks_subdir": "_talks"
      },
      "url": {
        "base": "https://speaking.example.com",
        "template": "/{slug}/"
      },
      "thumbnail_path_template": "assets/images/thumbnails/{slug}-thumbnail.png",
      "slug_convention": {
        "template": "{venue-compact}{yy}-{short-id}",
        "examples": []
      },
      "ssg_template_pointer": "{source.path_or_url}/_layouts/default.html"
    },

    "template_pptx_path": "",
    "presentation_file_convention": "{pptx_source_dir}/{conference}/{year}/{talk-slug}/",
    "clarification_sessions_completed": 0,
    "clarification_counted_runs": []
  }
}

Clarification session counter

clarification_sessions_completed counts completed clarification sessions (absent means zero); vault-profile requires at least one before generating a profile. clarification_counted_runs lists the run ids of the ledger sessions the counter already includes (absent means none). Only run-obligations.py count-session writes it: holding the obligations ledger's lock under the session's claim, it advances the counter and appends the run id in one write, so a ledger session counts once however often it is re-entered. set_config refuses clarification_counted_runs. A standalone session with no ledger record advances the counter with set_config alone. The owner validates both fields on every read: a non-negative integer, and unique run ids no more numerous than the count. clarification_counted_runs is a config schema v3 field; a v2 config carrying it is refused, and the owner migration restamps a v2 config to v3 unchanged.

PPTX directory exclusions

Config schemas v2 and v3 require pptx_directory_exclusions: a bounded, unique array of literal directory-name components. Matching is case-insensitive and exact at any descendant depth. Values are not paths, substrings, globs, or regular expressions; /, \\, control characters, pattern metacharacters, case-insensitive duplicates, . and .. are invalid. The code-owned owner default is intentionally not reproduced here; use the vault-ingress PPTX scan contract. Do not broaden the code-owned default to plausible authored-content directory names without an explicit speaker-specific customization.

Dual readers accept config schemas v1 and v2 only as read-only compatibility and owner-migration state; they are never current or writable. A v1 config cannot authorize PPTX catalog coverage or an absence conclusion because no current directory-exclusion policy is established until migration succeeds. The vault-ingress migration stamps schema v3: it supplies the canonical defaults to a v1 config whose list is absent, preserves a valid custom list already present on a schema-v1 record exactly, and restamps a v2 config unchanged. A root-schema-v1/config-schema-v1 vault receives only this config upgrade; the root and every unrelated record remain unchanged. Future or malformed config generations fail closed. Consumers never synthesize defaults or rewrite config themselves.

Trusted vault storage root

vault_storage_path is an optional assertion about the vault that contains tracking-database.json; it is not a redirect. Absent or JSON null uses the database parent. Every other present value must be a host-native absolute path lexically equal to that parent. Readers do not expand ~, rebase relative, drive-relative (C:vault), or current-drive-rooted (\vault) values, translate foreign path flavors, collapse dot segments, or resolve symlinks to manufacture equality. Empty/blank and invalid locator forms fail closed before evidence freshness or profile cohort construction.

Profile readers never repair this field. Use vault-ingress's expectation-bound owner mutation and rerun preflight before regenerating a profile; the concrete dry-run/apply/re-read sequence is documented in source-identity-preflight.md.

Shownotes Config — Field Reference

shownotes.enabled — false disables the configured shownotes action in presentation-publisher; do not generate or publish a shownotes page. If QR is enabled, set its target to custom_url and supply that URL instead of a shownotes result. The current action order and QR fields live in workflow.md and qr.md.

shownotes.source.type — one of:

TypeTalks live atFrontmatter
local_jekyll{path_or_url}/{talks_subdir}/*.mdJekyll YAML
local_hugo{path_or_url}/{talks_subdir}/*.mdTOML/YAML/JSON front matter
local_eleventy{path_or_url}/{talks_subdir}/*.mdYAML with permalink: per-file
local_astro{path_or_url}/{talks_subdir}/*.md (content collections)YAML
remote_urlread-only; browse {path_or_url} for live entriesn/a — scrape
noneno shownotesn/a

shownotes.source.path_or_url — local filesystem path when type starts with local_, HTTPS URL when type is remote_url, null otherwise.

shownotes.source.talks_subdir — subdirectory under the site root where talk entries live. Common values: _talks (Jekyll collections), content/talks (Hugo), src/content/talks (Astro). null for remote_url / none.

shownotes.url.base — deployed site base URL (no trailing slash).

shownotes.url.template — path component appended to url.base to form the live URL. Template variables:

VariableMeaning
{slug}The talk slug from the Presentation Spec
{yyyy}4-digit year from the talk's date frontmatter field
{mm}2-digit month
{dd}2-digit day
{venue}Slugified venue name
{yy}2-digit year

Presets for common SSGs (starting points — verify against the actual deployed URLs before shipping):

  • Jekyll _talks collection (default permalink): /talks/{slug}/
  • Jekyll with date permalink: /{yyyy}/{mm}/{dd}/{slug}/
  • Hugo default content section: /{talks_subdir}/{slug}/
  • Eleventy (permalink is per-file): use the most common pattern from your entries; if each file overrides it, set url.template to null and let the slug-convention step read the literal URL from per-file permalink:
  • Flat speaker-site with slug convention: /{slug}/

shownotes.thumbnail_path_template — filesystem path (relative to source.path_or_url) where the SSG template expects the talk thumbnail image. The exact convention is encoded in the SSG template file (e.g., Jekyll _layouts/default.html og:image tag) — see ssg_template_pointer. The default for Jekyll-based shownotes in this toolkit is:

assets/images/thumbnails/{slug}-thumbnail.png

Both the nested thumbnails/ subdirectory AND the -thumbnail suffix are mandatory for this convention — flat paths fall back to placeholder-thumbnail.svg on the live site with no warning.

shownotes.slug_convention.template — pattern used to generate new talk slugs. Template variables are derived from talk metadata (venue, date, title). See the phase1-intent.md reference for derivation rules.

shownotes.slug_convention.examples — array of recent slugs that match the current convention; used by presentation-creator Phase 1 to validate against drift (older analyses often encode retired conventions).

shownotes.ssg_template_pointer — path to the SSG template file that encodes the URL and thumbnail-path conventions. Stored so the convention can be re-derived after a site redesign without spelunking through the template tree.

Migration from Legacy Fields

Vaults created before this schema had config.talks_source_dir and config.shownotes_url_pattern as flat fields. Vault-profile regeneration maps them as follows:

Legacy fieldNew location
config.talks_source_dirconfig.shownotes.source.path_or_url + talks_subdir (split on the last path segment)
config.shownotes_url_pattern (flat {slug})config.shownotes.url.base + config.shownotes.url.template (template defaults to /{slug}/)

If a vault presents only the legacy fields, readers build the shownotes block in memory. vault-ingress owns persistence of the current config shape. Do not leave both shapes populated — one source of truth.

Confirmed Intents Schema

Stored in the confirmed_intents array of the tracking database. Populated during clarification sessions when the speaker confirms a pattern is intentional.

{
  "confirmed_intents": [{
    "schema_version": 1,
    "pattern": "delayed_self_introduction",
    "intent": "deliberate",
    "rule": "Use two-phase intro: brief bio at slide 3, full re-intro mid-talk",
    "note": "Speaker confirmed this is an intentional rhetorical device",
    "confirmed_date": "2026-08-01",
    "source_talk": "2026-08-01-example.md"
  }]
}

Required fields are exact integer schema_version: 1, pattern, intent, rule, and note. The owner also accepts the clarification provenance fields confirmed_date, one of source_talk / legacy talk / source_talks, and retrofit_targets. The plural fields are non-empty unique string arrays. Existing speaker-owned non-empty intent labels remain readable; the three labels in the example are the recommended vocabulary. Unknown fields are not part of the record.

skills

README.md

tile.json