| name | presentation |
| description | Create or update docs-as-code presentation material as AsciiDoc reveal.js decks rendered with docs-toolbox. Use when Codex needs to prepare talks, meetup or conference proposals, speaker notes, demo scripts, event-specific artifacts under talks/, or slide decks that must remain repository-native rather than PowerPoint or Google Slides files. |
Presentation Skill
Purpose
Create presentation material as reviewed source artifacts in the repository.
AsciiDoc is the source of truth; reveal.js HTML is generated output. Do not
create .pptx, Google Slides, Keynote, or binary deck files unless the user
explicitly asks for an additional export.
Apply the repository contract hierarchy: user instruction, this skill,
AGENTS.md, then general-semantic-contracts.md. Keep this skill
engine-independent; put runtime-specific metadata under adapters/**.
Core Workflow
- Inspect the repository and read the relevant issue, proposal, documentation,
or source artifacts before writing slides.
- Define the communication job in one sentence: by the end, the audience should
understand, believe, decide, discuss, or do what, and why.
- Choose a narrative arc before drafting slides. Prefer story flow over a
feature inventory.
- Create or update a talk directory below
talks/<event-or-talk-slug>/.
- Keep the deck source in
slides.adoc.
- Add supporting source artifacts as AsciiDoc when useful, such as
proposal.adoc, demo-script.adoc, speaker-brief.adoc, references,
abstracts, or follow-up notes. Keep Markdown for README files and platforms
where Markdown is the local standard.
- Apply "write once, use everywhere": put repeated talk text in reusable,
heading-neutral AsciiDoc fragments and include it with
include::[].
- Add or update
talks/README.md and the repository README.md when a new
public talk entry should be discoverable.
- Render the deck with docs-toolbox through the repository helper when
available.
- Treat generated reveal.js HTML below
build/ as derived output, not reviewed
source content.
Required Reading
../../general-semantic-contracts.md and ../../AGENTS.md before adding or
changing toolkit presentation conventions.references/asciidoc-revealjs.md before creating or rendering an AsciiDoc
reveal.js deck.
Talk Directory Convention
Use:
talks/
README.md
<talk-slug>/
README.md
slides.adoc
proposal.adoc
demo-script.adoc
speaker-brief.adoc
fragments/
*.adoc
Use lowercase hyphen-case slugs. Prefer the event name when material is
event-specific. Keep future variants in separate talk directories when the
audience, event, or framing changes materially.
Use fragments/ for talk-local reusable source text. If a fragment becomes
useful across several talks, move it to a shared talk fragment location and
update include paths deliberately. Do not mix reviewed source fragments with
generated output.
Slide Writing Rules
- Make each slide carry one claim.
- Use takeaway titles instead of topic labels when possible.
- Keep visible slide copy audience-facing; do not expose planning notes.
- Put presenter-only detail in
[NOTE.speaker] blocks.
- Prefer short bullets, simple tables, and small code snippets.
- Avoid live-demo dependency for the story; provide a fallback demo path.
- Mark AI-created talk material as draft/proposal until reviewed.
Rendering
Render a talk deck with:
scripts/render-presentation.sh talks/<talk-slug>/slides.adoc
Report whether rendering was run successfully. If docs-toolbox, Docker, Podman,
or asciidoctor-revealjs is unavailable, keep the AsciiDoc source valid and
state that render verification could not be completed.
Output Rules
- Do not commit generated files under
build/.
- Do not add binary slide deck artifacts by default.
- Do not use Markdown for project-owned talk artifacts except README files or
external platform content where Markdown is the expected format.
- Keep source links explicit. When slides are based on an issue, proposal, or
source document, mention it in the talk README or proposal artifact.
- Keep changes small enough to review.
