presentation

Files (2)

• SKILL.md
• asciidoc-revealjs.md · references/

SKILL.md (first lines)

# 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

1. Inspect the repository and read the relevant issue, proposal, documentation,
   or source artifacts before writing slides.
2. Define the communication job in one sentence: by the end, the audience should
   understand, believe, decide, discuss, or do what, and why.
3. Choose a narrative arc before drafting slides. Prefer story flow over a
   feature inventory.
4. Create or update a talk directory below `talks/<event-or-talk-slug>/`.
5. Keep the deck source in `slides.adoc`.
6. 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.
7. Apply "write once, use everywhere": put repeated talk text in reusable,
   heading-neutral AsciiDoc fragments and include it with `include::[]`.
8. Add or update `talks/README.md` and the repository `README.md` when a new
   public talk entry should be discoverable.
9. Render the deck with docs-toolbox through the repository helper when
   available.
10. 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:

```text
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:

```sh
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.

From docs-as-code-toolkit/architecture-knowledge-toolkit, MIT.

More from docs-as-code-toolkit/architecture-knowledge-toolkit