From c56a1727c080c938343d25696ffdae8faa4988a9 Mon Sep 17 00:00:00 2001 From: steve Date: Wed, 1 Apr 2026 13:42:30 +0000 Subject: [PATCH] Add playme skill --- playme/SKILL.md | 282 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 282 insertions(+) create mode 100644 playme/SKILL.md diff --git a/playme/SKILL.md b/playme/SKILL.md new file mode 100644 index 0000000..e977162 --- /dev/null +++ b/playme/SKILL.md @@ -0,0 +1,282 @@ +--- +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 `` 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 */ +--- + + + + +# Project Name + +### Tagline or short description + +*Auto-generated repository summary* + +--- + + + +## What Is This? + +- **Key point** — explanation +- **Another point** — details + +--- + + + + +# 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 `` 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 `` 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 `` comment +- Insert it **before** the 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 `` 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 +```