skills/playme/SKILL.md

---
name: playme
description: >-
  Create a visual, attention-grabbing Marp slideshow (PLAYME.md + PLAYME.html) summarising a repository.
  Use when the user asks to generate a presentation, slideshow, or visual summary of a repo.
  Triggered by /playme or phrases like "create a presentation", "visualise this repo", "generate slides".
emoji: 🎬
allowed-tools: [Bash, Read, Write, Edit, Glob, Grep, Agent]
---

# PlayMe — Repository Visual Summary Generator

Generate a stunning dark-themed Marp slideshow that summarises a repository at a high level.

## Modes

The skill has three modes. **Determine the mode from the user's argument or automatically:**

| Invocation | Mode | Behaviour |
|------------|------|-----------|
| `/playme` | **Smart** | If `.playme/PLAYME.md` exists → **Update**. Otherwise → **Create**. |
| `/playme render` | **Render** | Re-inject theme.css into PLAYME.md's style block and re-render HTML only. No content changes. |

---

## Output Files

- `.playme/PLAYME.md` — Marp markdown source (human-editable, git-friendly)
- `.playme/theme.css` — Theme file (copied from default if not already present)
- `.playme/README.md` — Explains the folder to anyone browsing into it
- `PLAYME.html` — Rendered self-contained HTML slideshow (in repo root for easy discovery)

**Do NOT generate PNG previews** — only produce the files listed above.

---

## Mode: Create

Use when `.playme/PLAYME.md` does **not** exist. Generates the full presentation from scratch.

### Phase 1: Gather Context

**Read everything you can** to build a thorough understanding of the repo. Do these in parallel where possible:

> **IMPORTANT:** Skip the `.playme/` directory entirely during scanning — it contains PlayMe's own output and should never be treated as repo content.

1. **README.md** — the primary source. Extract:
   - Project name and description
   - Key features / capabilities
   - Architecture or design decisions
   - Getting started / setup steps
   - Any diagrams or images referenced

2. **Linked markdown files** — follow any links from README.md to other `.md` files in the repo. Read them for additional context on specific areas.

3. **Other root markdown files** — scan for `CONTRIBUTING.md`, `CHANGELOG.md`, `ARCHITECTURE.md`, `docs/` folder contents, etc.

4. **Images** — find all `.png`, `.jpg`, `.svg`, `.gif` files. Read image files (especially diagrams, architecture charts, screenshots) to understand what they depict. Note their relative paths for embedding.

5. **Code structure** — run a quick scan:
   - `ls` the root directory
   - Check for `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `Makefile`, `docker-compose.yml`, etc.
   - Get a feel for the tech stack, languages used, project layout
   - Do NOT read every source file — just enough to understand the structure

6. **Git context** (optional, quick):
   - `git log --oneline -20` for recent activity flavour
   - `git remote -v` for repo URL

### Phase 2: Plan the Slides

Design a slide deck of roughly **8–15 slides**. Typical structure:

| # | Slide | Class | Content |
|---|-------|-------|---------|
| 1 | Title | `title-slide` | Project name, tagline, one-line description |
| 2 | What Is This? | — | 3–5 bullet summary of what the project does |
| 3 | Architecture | — | High-level architecture (bullets or embedded diagram) |
| 4–N | Key Areas | — | One slide per major area/feature (3–5 bullets each) |
| N+1 | Tech Stack | — | Languages, frameworks, infrastructure |
| N+2 | Diagrams | `showcase` | Any architecture/flow diagrams found as images |
| Last | Get Started | `end-slide` | Where to go next, link to full docs |

**Guidelines:**
- Each slide should have **3–6 bullet points max** — this is a summary, not a document
- Use `**bold**` for key terms in list items (renders in accent colour)
- Use `>` blockquotes for important callouts or stats
- Embed images using `![alt](relative/path.png)` where they add value
- Use `<!-- _class: divider -->` for section breaks between major topic areas
- Keep language concise and engaging — imagine presenting to someone who has 5 minutes

### Phase 3: Generate .playme/PLAYME.md

First, create the `.playme/` directory:
```bash
mkdir -p .playme
```

Build the Marp markdown file at `.playme/PLAYME.md` with this structure:

```markdown
---
marp: true
theme: uncover
class: invert
paginate: true
style: |
  /* Contents of theme.css pasted here */
---

<!-- _class: title-slide -->
<!-- topic: title -->

# Project Name

### Tagline or short description

*Auto-generated repository summary*

---

<!-- topic: overview -->

## What Is This?

- **Key point** — explanation
- **Another point** — details

---

<!-- _class: end-slide -->
<!-- topic: closing -->

# Explore the Repository

Full documentation available in README.md
```

**IMPORTANT RULES:**
- The CSS must be inlined in the `style:` frontmatter block (Marp doesn't support external CSS files without custom theme registration). Read the theme from `.playme/theme.css` in the target repo, or from the default at `/home/steve/agent-bobby/.claude/skills/playme/default-theme.css`, and paste it into the `style:` block.
- Every slide **must** have a `<!-- topic: short-name -->` comment as the first line after the `---` separator. This is used by Update mode to identify what each slide covers. Use lowercase, hyphenated names (e.g. `architecture`, `key-features`, `tech-stack`, `api-surface`).

### Phase 4: Create README, Copy Theme & Render

1. **Create README** — write `.playme/README.md` explaining the folder:
   ```markdown
   # .playme

   This folder contains the source files for the **PlayMe** visual presentation — an auto-generated slideshow summarising this repository.

   ## Files

   | File | Purpose |
   |------|---------|
   | `PLAYME.md` | Marp markdown source — edit this to change slide content |
   | `theme.css` | CSS theme — edit this to change colours, fonts, and styling |
   | `README.md` | This file |

   ## Rendering

   The rendered slideshow lives at `PLAYME.html` in the repository root. To regenerate after changes:

   ```
   marp .playme/PLAYME.md -o PLAYME.html --html --allow-local-files
   ```

   Or run `/playme render` in Claude Code.

   ## Regenerating from scratch

   Delete `.playme/PLAYME.md` and run `/playme` to regenerate the entire presentation.
   ```

2. **Copy theme** — if `.playme/theme.css` doesn't exist in the target repo, copy the default:
   ```bash
   cp /home/steve/agent-bobby/.claude/skills/playme/default-theme.css ./.playme/theme.css
   ```

3. **Render HTML** — produce a self-contained HTML file in the repo root:
   ```bash
   marp .playme/PLAYME.md -o PLAYME.html --html --allow-local-files
   ```

4. **Verify** — check the HTML file was created and report its size.

### Phase 5: Report Back

Tell the user:
- How many slides were generated
- What areas/topics are covered
- That `.playme/PLAYME.md` can be edited and `/playme render` used to re-render
- That `.playme/theme.css` can be tweaked for styling, then `/playme render` to apply

---

## Mode: Update

Use when `.playme/PLAYME.md` **already exists**. Preserves all existing slides and adds new ones for any repo content not yet covered.

### Step 1: Read Existing Slides

Read `.playme/PLAYME.md` and extract the `<!-- topic: ... -->` comments from every slide. Build a list of topics already covered.

### Step 2: Scan the Repo

Perform the same repo scan as Create mode (Phase 1) — read README, linked docs, images, code structure. Skip `.playme/`.

### Step 3: Identify Gaps

Compare the repo content against the existing topic list. Look for:
- New sections in README.md not represented by any slide
- New markdown files or docs that have appeared since the last run
- New images/diagrams worth showcasing
- Significant new code areas (new packages, services, tools)

### Step 4: Insert New Slides

For each new topic found:
- Create a new slide with the appropriate `<!-- topic: name -->` comment
- Insert it **before** the closing `<!-- topic: closing -->` slide
- Follow the same style guidelines as Create mode (3–6 bullets, bold key terms, etc.)

**Do NOT modify existing slides.** Leave their content exactly as-is.

### Step 5: Re-inject Theme & Render

1. Read `.playme/theme.css`
2. Replace the `style:` block in PLAYME.md's frontmatter with the current theme CSS
3. Render: `marp .playme/PLAYME.md -o PLAYME.html --html --allow-local-files`

### Step 6: Report Back

Tell the user:
- How many new slides were added (and their topics)
- If no new content was found, say so
- Total slide count

---

## Mode: Render

The simplest mode — no content changes at all.

### Steps

1. Read `.playme/theme.css`
2. Replace the `style:` block in `.playme/PLAYME.md`'s frontmatter with the current theme CSS content
3. Render: `marp .playme/PLAYME.md -o PLAYME.html --html --allow-local-files`
4. Report success and file size

---

## Theme Customisation Notes

The theme CSS uses these key variables that users will most likely want to tweak:

```css
--color-bg: #0b0d17;       /* Main background */
--color-accent: #6c63ff;   /* Purple accent (headings, borders) */
--color-accent2: #00d4aa;  /* Teal accent (bold text, highlights) */
--color-text: #e8eaf6;     /* Body text */
--color-muted: #8892b0;    /* Subtitle / faded text */
```

## Slide Classes Reference

Use these with `<!-- _class: classname -->` on individual slides:

- `title-slide` — centred title with glowing radial background
- `end-slide` — closing slide with gradient title
- `divider` — section break, centred heading
- `showcase` — image-focused slide with centred layout

## Dependencies

- `marp` CLI (`@marp-team/marp-cli`) — install with `npm install -g @marp-team/marp-cli`
- Google Chrome or Chromium (for HTML/PNG rendering)

If `marp` is not available, install it:
```bash
npm install -g @marp-team/marp-cli
```