Add playme skill
This commit is contained in:
+282
@@ -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 `` 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
|
||||
```
|
||||
Reference in New Issue
Block a user