steve/skills
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Wiki Activity

Add playme skill

Browse Source
This commit is contained in:
steve
2026-04-01 13:42:30 +00:00
parent 4cf1ed184e
commit c56a1727c0
1 changed files with 282 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
playme/SKILL.md
+282
View File
@@ -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 `<!-- _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
```