@honeydeck/honeydeck 0.1.2 → 0.3.0

package/AGENTS.md

@@ -18,8 +18,7 @@ From repo root:
 npm -w @honeydeck/honeydeck run dev
 npm -w @honeydeck/honeydeck run test
 npm -w @honeydeck/honeydeck run typecheck
-npm -w @honeydeck/honeydeck run build
 npm -w @honeydeck/honeydeck run pack:dry-run
 ```
 
-For full monorepo gates use root workspace scripts: `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`, and `npm run pack:dry-run`.
+For full monorepo gates use root workspace scripts: `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`, and `npm run pack:dry-run`. Root `npm run build` runs only workspaces that define a build script.

package/DEVELOPMENT.md

@@ -87,7 +87,6 @@ npx playwright install chromium
 
 | Script | Purpose |
 |--------|---------|
-| `npm run build` | Run the package TypeScript build gate |
 | `npm run dev` | Run source CLI against starter template deck |
 | `npm run dev:init` | Run source CLI against starter template deck |
 | `npm run format` | Format/lint with Biome and write fixes |
@@ -114,7 +113,6 @@ npm run format
 npm run lint
 npm run typecheck
 npm test
-npm run build
 npm run pack:dry-run
 ```
 

package/Readme.md

@@ -19,18 +19,18 @@ Decks are plain MDX files separated into slides with `---`; see the first deck e
 ## Documentation
 
 - [Getting started](docs/getting-started.md) - first deck, first commands, and the shortest path to presenting
-- [Next steps](docs/next-steps.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills
+- [Deeper dive](docs/deeper-dive.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills
 - [Slides](docs/slides.md) - separators, multiple files, layouts, and assets
 - [Configuration](docs/configuration.md) - deck-level and slide-level frontmatter
 - [Steps and reveals](docs/steps-and-reveals.md) - timeline, reveal groups, code steps, and PDF behavior
 - [Components](docs/components.md) - core Honeydeck components such as `BrowserFrame` and `Keyboard`
-- [Kits](docs/kits.md) - themes, layout sets, Tailwind tokens, and third-party kits
-- [Kit authoring](docs/kit-authoring.md) - layout maps, layout props, demos, and design tokens for kit authors
+- [Customization](docs/customization.md) - themes, layout sets, Tailwind tokens, custom layouts, and layout demos
 - [Navigation](docs/navigation.md) - keyboard, touch, overview mode, and URL state
 - [Mobile and touch](docs/mobile.md) - mobile controls, touch gestures, and pinch zoom
 - [Presenter mode](docs/presenter-mode.md) - notes, presenter window, sync, and mobile behavior
 - [PDF export](docs/pdf-export.md) - options, color modes, and step handling
 - [Local development](docs/local-development.md) - running Honeydeck from this repository
+- [Skills](docs/skills.md) - optional agent skills for authoring, writing, and migration help
 - [Slidev migration](docs/slidev-migration.md) - moving from Slidev with the bundled agent skill
 
 ## Common commands

package/SPEC.md

@@ -42,7 +42,7 @@ The Honeydeck specification is distributed:
 - `react`, `react-dom`, and Tailwind are peer dependencies of `honeydeck`.
 - Honeydeck wires the Tailwind Vite plugin internally, but Tailwind/theme CSS is only loaded when user-authored CSS imports it; generated projects install `tailwindcss` and import `./styles.css` from `deck.mdx`.
 - Generated projects use compatible semver ranges for React, Tailwind, TypeScript, and types.
-- Published third-party kits are plain npm packages; supported runtime ranges are managed by package metadata, not by a Honeydeck-specific mechanism.
+- Custom themes, layouts, and components are plain CSS/TypeScript modules; installed-package usage is handled by standard package metadata rather than by a Honeydeck-specific mechanism.
 - Icons come from `lucide-react` and must use suffixed `...Icon` component exports (for example `ChevronLeftIcon`), not inline SVG path helpers, emoji glyphs, or unsuffixed aliases.
 
 ---
@@ -59,7 +59,7 @@ The Honeydeck specification is distributed:
 | Runtime | [`src/runtime/SPEC.md`](src/runtime/SPEC.md) | timeline semantics, keyboard/touch navigation, SPA/build behavior, runtime errors |
 | Runtime components | [`src/runtime/components/SPEC.md`](src/runtime/components/SPEC.md) | `Reveal`, `RevealGroup`, `TimelineSteps`, `ListStyle`, `Keyboard`, `BrowserFrame`, `Notes` |
 | Runtime views | [`src/runtime/views/SPEC.md`](src/runtime/views/SPEC.md) | presenter mode, overview mode, theme/layout/component reference pages |
-| Layouts and kits | [`src/layouts/SPEC.md`](src/layouts/SPEC.md) | kit model, built-in layouts, layout props, demos, layout resolution |
+| Layouts and customization | [`src/layouts/SPEC.md`](src/layouts/SPEC.md) | custom theme/layout/component model, built-in layouts, layout props, demos, layout resolution |
 | Theme | [`src/theme/SPEC.md`](src/theme/SPEC.md) | design tokens, base theme CSS, Tailwind mapping, color mode behavior |
 | Public exports | [`src/SPEC.md`](src/SPEC.md) | import paths and public TypeScript types |
 | Public release governance | Repository root `.github/SPEC.md` | protected branch, CI checks, PR title contract, publishing automation; repository-only, not shipped in the npm package |
@@ -80,7 +80,7 @@ The Honeydeck specification is distributed:
 Honeydeck prioritizes:
 
 1. **Zero to presenting** — a plain `deck.mdx` works with built-in layouts, even before CSS is imported.
-2. **Progressive power** — add explicit CSS imports, React, custom layout maps, and kits as needed.
+2. **Progressive power** — add explicit CSS imports, React components, and custom layout maps as needed.
 3. **Explicit composition** — see imports and configuration; no user-content auto-discovery and no automatic theme CSS injection.
 4. **Presentation-native** — timeline, steps, presenter mode, runtime reference pages, and PDF export built in.
 5. **Fun** — starter sparkle button, tasteful CLI output, playful defaults.

package/docs/customization.md

@@ -0,0 +1,413 @@
+# Customization
+
+Honeydeck starts with built-in layouts and a small base theme. Customize only what you need: CSS tokens, React components, or a layout map.
+
+## Mental model
+
+| Concern | What you write | How you use it |
+|---------|----------------|----------------|
+| Theme | CSS files with Honeydeck tokens and Tailwind utilities | import CSS from `deck.mdx` or from another CSS file |
+| Components | React components | import them in MDX |
+| Layouts | React layout components in a layout map | set `layouts:` in deck frontmatter, then choose `layout:` per slide |
+
+All references are explicit. Local files and installed packages work the same way: import the module you want.
+
+## Start with CSS
+
+The starter deck imports `./styles.css` from `deck.mdx`:
+
+```mdx
+import './styles.css'
+
+# Hello world
+```
+
+A typical styles file imports Tailwind and the Honeydeck base theme:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+```
+
+Override tokens after the base theme:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+
+:root {
+  --honeydeck-primary: oklch(55% 0.25 280);
+  --honeydeck-font-heading: "Playfair Display", serif;
+  --honeydeck-border-radius: 1rem;
+}
+```
+
+Target light and dark modes when needed:
+
+```css
+[data-honeydeck-color-mode="light"] {
+  --honeydeck-primary: oklch(50% 0.2 250);
+}
+
+[data-honeydeck-color-mode="dark"] {
+  --honeydeck-primary: oklch(70% 0.2 250);
+}
+```
+
+## Bundled themes and layouts
+
+The default visual style is clean black, white, and grey:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+```
+
+`@honeydeck/honeydeck/themes/clean.css` is available as an optional named clean layer.
+
+The Bee theme adds the original playful palette:
+
+```css
+@import "tailwindcss";
+@import "@honeydeck/honeydeck/theme.css";
+@import "@honeydeck/honeydeck/themes/bee.css";
+```
+
+Use the matching Bee layout set when you want Bee slide chrome too:
+
+```yaml
+---
+layouts: "@honeydeck/honeydeck/layouts/bee"
+---
+```
+
+The default clean layout set is available through either path:
+
+```yaml
+---
+layouts: "@honeydeck/honeydeck/layouts"
+---
+```
+
+```yaml
+---
+layouts: "@honeydeck/honeydeck/layouts/clean"
+---
+```
+
+## Tailwind token utilities
+
+Honeydeck maps theme tokens to Tailwind utilities:
+
+```mdx
+<div className="rounded-honeydeck border border-border bg-surface p-6 text-surface-foreground">
+  Styled with Honeydeck tokens.
+</div>
+```
+
+Useful color utilities include `primary`, `primary-foreground`, `accent`, `accent-foreground`, `background`, `foreground`, `surface`, `surface-foreground`, and `border`.
+
+## Design tokens
+
+Themes provide CSS custom properties. Colors derive from a primary using `oklch` relative color syntax, with separate values for light and dark modes:
+
+```css
+[data-honeydeck-color-mode="light"] {
+  --honeydeck-primary: oklch(50% 0.2 250);
+  --honeydeck-background: oklch(from var(--honeydeck-primary) 98% 0.01 h);
+  --honeydeck-foreground: oklch(from var(--honeydeck-primary) 15% 0.02 h);
+  --honeydeck-surface: oklch(from var(--honeydeck-primary) 94% 0.02 h);
+}
+```
+
+| Token | Purpose |
+|-------|---------|
+| `--honeydeck-primary` | Brand color for this mode |
+| `--honeydeck-primary-foreground` | Text on primary backgrounds |
+| `--honeydeck-background` | Main slide background |
+| `--honeydeck-foreground` | Main text color |
+| `--honeydeck-surface` | Cards, code blocks, callouts |
+| `--honeydeck-surface-foreground` | Text on surfaces |
+| `--honeydeck-border` | Border/divider color |
+| `--honeydeck-accent` | Accent, computed as complementary by default |
+| `--honeydeck-accent-foreground` | Text on accent backgrounds |
+| `--honeydeck-link-color` | Link color, defaulting to inherit |
+| `--honeydeck-border-radius` | Default border radius |
+| `--honeydeck-font-heading` | Heading font family |
+| `--honeydeck-font-body` | Body font family |
+| `--honeydeck-font-mono` | Monospace font family |
+| `--honeydeck-font-base` | Base font size, defaulting to `16px` |
+| `--honeydeck-font-scale` | Heading scale factor, defaulting to `1.25` |
+| `--honeydeck-code-line-dim-opacity` | Dim opacity for non-highlighted code lines |
+
+## Use built-in layouts
+
+Select a layout in slide frontmatter:
+
+```mdx
+---
+layout: Section
+---
+
+# Big idea
+```
+
+If no `layout:` is specified, `Default` is used. Layout names are PascalCase.
+
+| Layout | Description |
+|--------|-------------|
+| `Blank` | Empty slide with only children |
+| `Default` | Title top-left, body flows below |
+| `Section` | Big centered heading for section breaks |
+| `Cover` | Opening/closing slide with title, body, author, and date |
+| `TwoCol` | Two equal columns |
+| `Image` | Prominent image with optional title and caption/content |
+| `ImageLeft` | Prominent left image with title and body on the right |
+| `ImageRight` | Prominent right image with title and body on the left |
+
+Extra slide frontmatter fields are passed to the selected layout:
+
+```mdx
+---
+layout: Cover
+author: You_Name_Here
+---
+
+# Honeydeck
+
+A modern slide framework.
+```
+
+### Two-column slides
+
+`TwoCol` uses slot components from the active layout set:
+
+```mdx
+---
+layout: TwoCol
+---
+
+import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
+
+<Left>
+## Benefits
+- Fast iteration
+- Live reload
+</Left>
+
+<Right>
+## Trade-offs
+- Requires Node.js
+</Right>
+```
+
+For Bee layouts, import slots from the Bee path:
+
+```mdx
+import { Left, Right } from '@honeydeck/honeydeck/layouts/bee/TwoCol'
+```
+
+### Image slides
+
+`Image`, `ImageLeft`, and `ImageRight` accept `image`, `darkImage`, and `alt` frontmatter:
+
+```mdx
+---
+layout: ImageRight
+image: /photos/launch.jpg
+darkImage: /photos/launch-dark.jpg
+alt: Launch moment
+---
+
+# Launch moment
+
+Supporting context sits beside the image.
+```
+
+## Create custom layouts
+
+Custom layouts are React components. Use a layout map when you want `layout:` frontmatter to select them.
+
+```tsx
+// layouts/Hero.tsx
+import type { LayoutProps } from '@honeydeck/honeydeck/types'
+
+export default function HeroLayout({ title, children }: LayoutProps) {
+  return (
+    <div className="grid h-full place-items-center bg-gradient-to-br from-purple-900 to-indigo-900 p-12 text-center text-white">
+      <div>
+        {title ? <h1>{title}</h1> : null}
+        {children}
+      </div>
+    </div>
+  )
+}
+```
+
+Create a layout map:
+
+```ts
+// layouts/index.ts
+import type { LayoutMap } from '@honeydeck/honeydeck/types'
+import defaultLayouts from '@honeydeck/honeydeck/layouts'
+import HeroLayout from './Hero'
+
+export default {
+  ...defaultLayouts,
+  Hero: HeroLayout,
+} satisfies LayoutMap
+```
+
+Reference it from deck frontmatter:
+
+```yaml
+---
+layouts: "./layouts"
+---
+```
+
+Use it on any slide:
+
+```mdx
+---
+layout: Hero
+---
+
+# Special slide
+
+With a custom gradient background.
+```
+
+You can also import a React component directly and wrap slide content when you do not need a layout map:
+
+```mdx
+---
+
+import { GradientPanel } from './components/GradientPanel'
+
+<GradientPanel>
+# Special slide
+</GradientPanel>
+
+---
+```
+
+## Layout props
+
+`LayoutProps` is generic so layouts can type their accepted frontmatter:
+
+```ts
+type LayoutProps<F extends Record<string, unknown> = Record<string, unknown>> = {
+  title: ReactNode | null
+  children: ReactNode
+  rawChildren: ReactNode
+  frontmatter: F
+}
+```
+
+Example typed layout:
+
+```tsx
+import type { LayoutProps } from '@honeydeck/honeydeck/types'
+
+type CoverFrontmatter = {
+  author?: string
+  date?: string
+}
+
+export function CoverLayout({ title, children, frontmatter }: LayoutProps<CoverFrontmatter>) {
+  const { author, date } = frontmatter
+  return (/* ... */)
+}
+```
+
+## Layout demos
+
+Layouts can export a `demo` constant for `/#/layouts`:
+
+```tsx
+import type { LayoutDemo, LayoutProps } from '@honeydeck/honeydeck/types'
+
+type HeroFrontmatter = {
+  /** Short label shown above the title. */
+  eyebrow?: string
+}
+
+export default function HeroLayout({ title, children, frontmatter }: LayoutProps<HeroFrontmatter>) {
+  return (/* ... */)
+}
+
+export const demo: LayoutDemo<HeroFrontmatter> = {
+  mdx: `---
+layout: Hero
+eyebrow: Launch
+---
+
+# Hero moment
+
+This snippet and preview come from the same demo.`,
+}
+```
+
+`mdx` is the single source for both the live preview and the copyable usage snippet in the layouts reference page. If no demo is exported, the layout still appears with a “No demo MDX provided” hint.
+
+## Slot components
+
+Layouts that need content slots can export slot components alongside the layout:
+
+```tsx
+// layouts/TwoCol.tsx
+import type { ReactNode } from 'react'
+import type { LayoutProps } from '@honeydeck/honeydeck/types'
+
+export function Left({ children }: { children: ReactNode }) {
+  return <div data-honeydeck-slot="left" className="col-start-1 overflow-hidden">{children}</div>
+}
+
+export function Right({ children }: { children: ReactNode }) {
+  return <div data-honeydeck-slot="right" className="col-start-2 overflow-hidden">{children}</div>
+}
+
+export default function TwoColLayout({ title, children }: LayoutProps) {
+  return (
+    <div className="grid h-full grid-cols-2 gap-12">
+      {children}
+    </div>
+  )
+}
+```
+
+Users import slots from the layout module:
+
+```mdx
+import { Left, Right } from './layouts/TwoCol'
+```
+
+## Image helpers
+
+Built-in placeholder images are available as URL exports for custom image layouts:
+
+```ts
+import {
+  imagePlaceholder,
+  imagePlaceholderDark,
+  verticalImagePlaceholder,
+  verticalImagePlaceholderDark,
+} from '@honeydeck/honeydeck/layouts/placeholders'
+```
+
+Use `ColorModeImage` when a custom layout accepts separate light and dark image URLs:
+
+```tsx
+import { ColorModeImage } from '@honeydeck/honeydeck'
+
+<ColorModeImage src={image} darkSrc={darkImage} alt={alt} />
+```
+
+## Runtime reference
+
+During development, open the built-in reference pages:
+
+- `/#/theme` shows all `--honeydeck-*` CSS tokens with computed values and descriptions.
+- `/#/layouts` shows layouts from the active layout map, live visual previews, copyable snippets, and extracted frontmatter prop docs.
+- `/#/components` shows public built-in components exported from `@honeydeck/honeydeck/components`.

package/docs/{next-steps.md → deeper-dive.md}

@@ -1,4 +1,4 @@
-# Next steps
+# Diving deeper
 
 Use this guide after the quick start when you want to understand the main Honeydeck workflows without jumping straight into every reference page.
 
@@ -285,24 +285,26 @@ All tokens are mapped to Tailwind utilities:
 
 Available color utilities: `primary`, `primary-foreground`, `accent`, `accent-foreground`, `background`, `foreground`, `surface`, `surface-foreground`, and `border`.
 
-See [Kits](kits.md) for theme and layout customization.
+See [Customization](customization.md) for theme and layout customization.
 
-## Kits
+## Customization
 
-A kit is an npm package bundling a theme, layouts, and components.
+Customize Honeydeck with explicit CSS imports, React component imports, and layout maps.
 
 ```mdx
 ---
-layouts: "@company/honeydeck-kit-brand/layouts"
+layouts: "./layouts"
 ---
 
-import '@company/honeydeck-kit-brand/theme.css'
-import { Callout } from '@company/honeydeck-kit-brand/components'
+import './styles.css'
+import { Callout } from './components/Callout'
 
-# Slide with brand kit
+# Slide with custom pieces
+
+<Callout>Important!</Callout>
 ```
 
-Zero config still works: built-in defaults apply without imports. See [Kits](kits.md) and [Kit authoring](kit-authoring.md).
+Zero config still works: built-in defaults apply without imports. See [Customization](customization.md).
 
 ## Runtime reference
 
@@ -360,18 +362,11 @@ type LayoutProps<F = Record<string, unknown>> = {
 
 ## Agent skills
 
-Honeydeck ships optional agent skills:
-
-- `honeydeck` for Honeydeck-specific MDX and CLI guidance
-- `presentation-writing` for help writing strong slide narratives
-- `slidev-migration` for moving decks from Slidev to Honeydeck
-
-`honeydeck init` can open the same interactive skills installer as `honeydeck skill`.
+Honeydeck ships optional agent skills for Honeydeck authoring, presentation writing, and Slidev migration. `honeydeck init` can open the same interactive skills installer as `honeydeck skill`.
 
 ```bash
 honeydeck skill
-npx skills add <honeydeck-repo-url> --copy
-npx skills add <honeydeck-repo-url> --copy --skill slidev-migration
 ```
 
+See [Skills](skills.md) for installation options and bundled skill details.
 Coming from Slidev? See the [Slidev migration guide](slidev-migration.md).

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting started
 
-Honeydeck helps you create polished, interactive presentations from plain-text MDX. Write slides in Markdown, add React components when you need them, and present with built-in layouts, speaker notes, presenter mode, and PDF export.
+Honeydeck helps you create polished, interactive presentations using MDX. Write slides in Markdown, use different Layout, add React components when you need them, present using presenter mode, and export to PDF for easy sharing.
 
 ## Quick start
 
@@ -21,11 +21,11 @@ npm run build
 npm run pdf
 ```
 
-Running `honeydeck` with no subcommand shows CLI help.
+`npx @honeydeck/honeydeck` to see cli help.
 
 ## Your first deck
 
-Decks are MDX files. The first frontmatter block configures the deck and opening slide. Later `---` separators start new slides.
+Decks are MDX files. The first frontmatter block [configures the deck](configuration.md) and opening slide. Later `---` separators start new slides.
 
 ```mdx
 ---
@@ -62,7 +62,7 @@ Add React when it helps.
 </Right>
 ```
 
-Use `layout:` to choose a slide layout. Built-in layouts include `Blank`, `Default`, `Cover`, `Section`, `TwoCol`, `Image`, `ImageLeft`, and `ImageRight`.
+Use `layout:` to choose a slide layout. Built-in layouts include `Blank`, `Default`, `Cover`, `Section`, `TwoCol`, `Image`, `ImageLeft`, and `ImageRight`. See them in the [showacase/#/layouts](https://showcase.honeydeck.dev/#/layouts).
 
 ## What Honeydeck gives you
 
@@ -76,6 +76,13 @@ Use `layout:` to choose a slide layout. Built-in layouts include `Blank`, `Defau
 - PDF export through headless Chromium
 - Optional Honeydeck agent skills for writing and migration help
 
+## Navigating your deck
+
+- Next or previous step using `→` `d` / `←` `a`
+- Next or previous slide with `↓` `s` / `↑` `w`
+- Overview of all slides `o`
+- Presenter mode `p`
+
 ## Common commands
 
 ```bash
@@ -91,18 +98,18 @@ honeydeck skill               # install optional Honeydeck agent skills
 
 ## Where to go next
 
-- [Next steps](next-steps.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills in one follow-up guide
+- [Deeper dive](deeper-dive.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills in one follow-up guide
 - [Slides](slides.md) - separators, multiple files, layouts, and assets
 - [Configuration](configuration.md) - deck-level and slide-level frontmatter
 - [Steps and reveals](steps-and-reveals.md) - timeline, reveal groups, code steps, and PDF behavior
 - [Components](components.md) - core Honeydeck components such as `BrowserFrame` and `Keyboard`
-- [Kits](kits.md) - themes, layout sets, Tailwind tokens, and third-party kits
-- [Kit authoring](kit-authoring.md) - layout maps, layout props, demos, and design tokens for kit authors
+- [Customization](customization.md) - themes, layout sets, Tailwind tokens, custom layouts, and layout demos
 - [Navigation](navigation.md) - keyboard, touch, overview mode, and URL state
 - [Mobile and touch](mobile.md) - mobile controls, touch gestures, and pinch zoom
 - [Presenter mode](presenter-mode.md) - notes, presenter window, sync, and mobile behavior
 - [PDF export](pdf-export.md) - options, color modes, and step handling
 - [Local development](local-development.md) - running Honeydeck from this repository
+- [Skills](skills.md) - optional agent skills for authoring, writing, and migration help
 - [Slidev migration](slidev-migration.md) - moving from Slidev with the bundled agent skill
 
 ## Learn inside a running deck
@@ -113,4 +120,6 @@ During development, open the runtime reference pages to see:
 - layout previews with copyable usage snippets
 - built-in component docs
 
+See those in our [showcase](https://showcase.honeydeck.dev/#/layouts)
+
 Honeydeck is built with MDX, React, Vite, and Tailwind v4.

package/docs/skills.md

@@ -0,0 +1,65 @@
+# Skills
+
+Honeydeck ships optional agent skills that help AI coding agents work with presentations more reliably. They are plain skill files bundled with the `@honeydeck/honeydeck` package, so you can install them into a deck project or into your global agent setup.
+
+## Install skills
+
+New projects can open the skills installer during init:
+
+```bash
+npx @honeydeck/honeydeck init --name my-talk --install-skill
+```
+
+Existing projects can run:
+
+```bash
+honeydeck skill
+```
+
+Both commands open the same `skills` CLI flow, where you choose which Honeydeck skills to install, whether to install them for the project or globally, and which agents should receive them.
+
+You can also install from the Honeydeck repository:
+
+```bash
+npx skills add <honeydeck-repo-url> --copy
+npx skills add <honeydeck-repo-url> --copy --skill honeydeck
+npx skills add <honeydeck-repo-url> --copy --skill presentation-writing
+npx skills add <honeydeck-repo-url> --copy --skill slidev-migration
+```
+
+## Bundled skills
+
+| Skill | Use it for |
+| --- | --- |
+| `honeydeck` | Honeydeck-specific guidance for MDX decks, layouts, CSS imports, presenter notes, reveals, code steps, PDF export, and package docs. |
+| `presentation-writing` | Framework-agnostic help with audience, storyline, slide headlines, speaker notes, timing, and review heuristics. |
+| `slidev-migration` | Migrating Slidev decks to Honeydeck while preserving source files until you approve cleanup. |
+
+The `honeydeck` and `presentation-writing` skills work well together: one keeps the agent inside Honeydeck conventions, while the other improves the story and delivery. Add `slidev-migration` when you are converting an existing Slidev project.
+
+## How agents use them
+
+Skills do not change Honeydeck runtime behavior. They give your agent a focused local instruction file before it edits your deck.
+
+For example, an agent with the `honeydeck` skill should prefer:
+
+- `deck.mdx` as the entry file
+- exact `---` slide separators
+- slide frontmatter for layouts
+- explicit imports from `@honeydeck/honeydeck`
+- `<Notes>` for speaker notes
+- `<Reveal>`, `<RevealGroup>`, and code metadata for steps
+- `honeydeck pdf` for PDF export
+
+The skills also point agents back to the packaged docs and specs, so generated deck changes can stay aligned with the installed Honeydeck version.
+
+## Updating skills
+
+Skills are copied into the target scope when you install them. Re-run the installer after upgrading Honeydeck if you want the latest bundled instructions:
+
+```bash
+npm update @honeydeck/honeydeck
+honeydeck skill
+```
+
+Coming from Slidev? See the [Slidev migration guide](slidev-migration.md) for the migration-specific workflow.