marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add Talk Preparation Pipeline workflow + skill templates

Browse source 
6-stage pipeline: raw material → conference talk → Kimi AI slides.

New files:
- guide/workflows/talk-pipeline.md — Full workflow guide (REX vs Concept
  modes, stage-by-stage breakdown, CHECKPOINT mechanics, Kimi handoff,
  real-world DevWithAI example, 5 design patterns documented)
- examples/skills/talk-pipeline/ — 7 SKILL.md files + orchestrator + 2
  templates (feedback-draft.md, kimi-prompt-template.md)

Updated:
- README.md — badges 164→172 templates, Feb 20 date, 13→14 skills
- guide/workflows/README.md — Talk Pipeline entry under Design & Content
- machine-readable/reference.yaml — 16 new entries for pipeline components
- CHANGELOG.md — [Unreleased] entry

Design patterns showcased: skill chaining + file-based state, tool
permission scoping (Bash only Stage 2), human-in-the-loop CHECKPOINT
(Stage 4), AI-to-AI handoff (Claude → Kimi), dual execution modes
(REX/Concept).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-02-20 15:51:29 +01:00
parent 6d847d24de
commit 00cb973bdb
15 changed files with 2297 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

23
CHANGELOG.md
View file

@ -8,6 +8,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
### Added
- **Talk Preparation Pipeline** — 6-stage skill pipeline: raw material → conference talk → Kimi slides
- New workflow guide: `guide/workflows/talk-pipeline.md` (REX vs Concept modes, stage-by-stage guide, design patterns, real-world example)
- New skill templates: `examples/skills/talk-pipeline/` (7 SKILL.md files + 2 templates)
- Stage 1: Extract (source → structured summary, type auto-detection)
- Stage 2: Research (REX only — git archaeology, changelog analysis, verified timeline)
- Stage 3: Concepts (numbered, scored catalogue — HIGH/MEDIUM/LOW)
- Stage 4: Position (angles, titles, descriptions, peer feedback draft + mandatory CHECKPOINT)
- Stage 5: Script (5-act pitch, slide spec, Kimi prompt for AI slide generation)
- Stage 6: Revision (master concept table, Q&A cheat-sheet, glossary)
- Orchestrator (runs full pipeline from one invocation, routes by mode)
- Generic Kimi template: `stage-5-script/templates/kimi-prompt-template.md` (dark theme, orange accent, WCAG AA)
- Peer feedback template: `stage-4-position/templates/feedback-draft.md` (3 formats: Slack, email, LinkedIn)
- Design patterns documented: skill chaining + file-based state, tool permission scoping, human-in-the-loop gate, AI-to-AI handoff (Claude → Kimi), dual execution modes
- `reference.yaml`: 16 entries for talk pipeline components
- `guide/workflows/README.md`: Talk Pipeline entry under Design & Content + Quick Selection Table
- **Resource evaluation**: Mergify "Cross-System Support Investigator" (score 4/5)
- Production case study: Claude Code + 5 MCP servers (Datadog, Sentry, PostgreSQL, Linear, GitHub) for support ticket triage
- Architecture pattern: Claude Code as operational orchestrator with parallel fan-out across MCP adapters
- Results (self-reported): triage 15 min → <5 min; 75% first-pass accuracy
- Integrated in `guide/ultimate-guide.md` §8.4 → new "Production Case Study" subsection with architecture diagram
- Evaluation archived: `docs/resource-evaluations/2026-02-20-mergify-cross-system-support-investigator.md`
/- **Resource evaluation**: "Evaluating AGENTS.md" — ETH Zürich arXiv 2602.11988 (score 4/5)
- First empirical study on repository-level context files (AGENTS.md/CLAUDE.md) effectiveness
- Developer-written context files: **+4% agent success rate**; LLM-generated: **-3%** vs no context file

14
README.md
View file

@ -6,9 +6,9 @@
<p align="center">
<a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Feb_19,_2026_·_v3.27.8-brightgreen?style=for-the-badge" alt="Last Update"/></a>
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Feb_20,_2026_·_v3.27.8-brightgreen?style=for-the-badge" alt="Last Update"/></a>
<a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-274_questions-orange?style=for-the-badge" alt="Quiz"/></a>
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-164-green?style=for-the-badge" alt="Templates"/></a>
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-172-green?style=for-the-badge" alt="Templates"/></a>
<a href="./guide/security-hardening.md"><img src="https://img.shields.io/badge/🛡️_Threat_DB-19_CVEs_·_655_malicious_skills-red?style=for-the-badge" alt="Threat Database"/></a>
</p>
@ -50,7 +50,7 @@ Both guides serve different needs. Choose based on your priority.
| **Security hardening** | Only threat database (18 CVEs) | Basic patterns only |
| **Test understanding** | 274-question quiz | Not available |
| **Methodologies** (TDD/SDD/BDD) | Full workflow guides | Not covered |
| **Copy-paste ready** templates | 164 templates | 200+ templates |
| **Copy-paste ready** templates | 172 templates | 200+ templates |
### Ecosystem Positioning
@ -136,11 +136,11 @@ graph LR
root[📦 Repository<br/>Root]
root --> guide[📖 guide/<br/>19K lines]
root --> examples[📋 examples/<br/>164 templates]
root --> examples[📋 examples/<br/>172 templates]
root --> quiz[🧠 quiz/<br/>274 questions]
root --> tools[🔧 tools/<br/>utils]
root --> machine[🤖 machine-readable/<br/>AI index]
root --> docs[📚 docs/<br/>78 evaluations]
root --> docs[📚 docs/<br/>83 evaluations]
style root fill:#d35400,stroke:#e67e22,stroke-width:3px,color:#fff
style guide fill:#2980b9,stroke:#3498db,stroke-width:2px,color:#fff
@ -166,11 +166,11 @@ graph LR
│ ├─ mcp-servers-ecosystem.md Official & community MCP servers
│ └─ workflows/ Step-by-step guides
│
├─ 📋 examples/ 164 Production Templates
├─ 📋 examples/ 172 Production Templates
│ ├─ agents/ 6 custom AI personas
│ ├─ commands/ 26 slash commands
│ ├─ hooks/ 31 hooks (bash + PowerShell)
│ ├─ skills/ 13 skills (9 on SkillHub)
│ ├─ skills/ 14 skills (9 on SkillHub)
│ └─ scripts/ Utility scripts (audit, search)
│
├─ 🧠 quiz/ 264 Questions

70
examples/skills/talk-pipeline/README.md Normal file
View file

@ -0,0 +1,70 @@
# Talk Pipeline Skills
6-stage skill pipeline that transforms raw material (article, transcript, notes) into a complete conference talk with AI-generated slides.
## Install
Copy the `talk-pipeline/` directory to your project's `.claude/skills/` folder:
```bash
cp -r examples/skills/talk-pipeline ~/.claude/skills/
```
Or install only the stages you need (each stage is independent).
## Stages
| Stage | Skill file | Mode | Description |
|-------|-----------|------|-------------|
| 1 | `stage-1-extract/SKILL.md` | REX + Concept | Extract source material into structured summary |
| 2 | `stage-2-research/SKILL.md` | REX only | Git archaeology + timeline |
| 3 | `stage-3-concepts/SKILL.md` | REX + Concept | Scored concept catalogue |
| 4 | `stage-4-position/SKILL.md` | REX + Concept | Angles, titles, descriptions + CHECKPOINT |
| 5 | `stage-5-script/SKILL.md` | REX + Concept | 5-act pitch + slides spec + Kimi prompt |
| 6 | `stage-6-revision/SKILL.md` | REX + Concept | Revision sheets + Q&A cheat-sheet |
| — | `orchestrator/SKILL.md` | REX + Concept | Run the full pipeline from one invocation |
## Quick Start
**Full pipeline (recommended)**:
```
/talk-pipeline
```
The orchestrator asks for metadata and runs all applicable stages.
**Single stage**:
```
/talk-stage1-extract
/talk-stage4-position
```
**With flags**:
```
/talk-pipeline --rex --slug=my-talk --event="Conf 2026" --duration=30
/talk-pipeline --concept --slug=my-idea
```
## Output convention
All files land in `talks/` at your project root:
```
talks/{YYYY}-{slug}-summary.md
talks/{YYYY}-{slug}-git-archaeology.md
talks/{YYYY}-{slug}-concepts.md
talks/{YYYY}-{slug}-angles.md
talks/{YYYY}-{slug}-pitch.md
talks/{YYYY}-{slug}-kimi-prompt.md
...
```
## Using the Kimi prompt
Stage 5 generates `{slug}-kimi-prompt.md`. To generate slides:
1. Open the file and verify no `{PLACEHOLDER}` remains
2. Go to [kimi.com](https://kimi.com) (free, no API needed)
3. Copy-paste the entire prompt
4. Kimi generates a dark-theme presentation with your slide content
## Documentation
Full workflow guide: [guide/workflows/talk-pipeline.md](../../guide/workflows/talk-pipeline.md)

174
examples/skills/talk-pipeline/orchestrator/SKILL.md Normal file
View file

@ -0,0 +1,174 @@
---
name: talk-pipeline
description: Orchestrator for the complete talk preparation pipeline (REX or Concept mode). Runs all 6 stages in sequence with human-in-the-loop checkpoints.
tags: [talk, pipeline, presentation, orchestrator]
allowed-tools:
- Write
- Read
- AskUserQuestion
- Task
---
# Talk Pipeline Orchestrator
Orchestrates the complete talk preparation pipeline — from raw material to revision sheets. Can run the full pipeline or a single isolated stage.
## Modes
- `--rex`: REX talk with git/code proof (changelog, commits, measured metrics)
- `--concept`: Conceptual talk from article, ideas, notes (skips Stage 2)
## Usage
```
/talk-pipeline # full pipeline, asks for context
/talk-pipeline --stage=extract # run a single isolated stage
/talk-pipeline --rex # REX mode (git archaeology included)
/talk-pipeline --concept # Concept mode (skip research)
/talk-pipeline --rex --slug=my-talk --event="Conf 2026" --date=2026-06-15 --duration=30
```
## Context Collection
Ask with AskUserQuestion if not provided:
```
- slug : kebab-case identifier (e.g., my-talk-topic)
- event : event name (e.g., Conf 2026, Tech Meetup)
- date : talk date (YYYY-MM-DD)
- duration : duration in minutes (e.g., 30)
- audience : audience profile (e.g., senior devs, tech leads, non-tech)
- type : --rex or --concept
- source_path : path to source material (article .mdx, transcript .md, notes)
- repo_path : (REX only) path to git repository for archaeology
```
## Workflow
1. **Collect context** — AskUserQuestion for required metadata
2. **Route by mode** — `--rex` vs `--concept` (skip Stage 2 if concept)
3. **Run Stage 1** — `/talk-stage1-extract` — always first
4. **Run Stages 2-4 in parallel** (after Stage 1 confirmed)
- REX: extract → research + concepts + position (in parallel)
- Concept: extract → concepts + position (in parallel, skip research)
5. **CHECKPOINT** — wait for angle + title choice (Stage 4 output)
6. **Run Stage 5** — `/talk-stage5-script` with validated choice
7. **Run Stage 6** — `/talk-stage6-revision`
8. **Final summary** — list all generated files with their paths
## Dependency Graph
```
extract (Stage 1)
|
┌──────────┼──────────┐
v v v
research concepts position
(Stage 2) (Stage 3) (Stage 4)
[--rex only] [CHECKPOINT]
| | |
└──────────┼──────────┘
v
script (Stage 5)
|
v
revision (Stage 6)
```
## Stage Routing (--stage=X)
If `--stage` is provided, run only the corresponding skill:
| Stage | Skill to invoke |
|-------|----------------|
| extract | /talk-stage1-extract |
| research | /talk-stage2-research |
| concepts | /talk-stage3-concepts |
| position | /talk-stage4-position |
| script | /talk-stage5-script |
| revision | /talk-stage6-revision |
## Output Naming Convention
```
talks/{YYYY}-{slug}-summary.md # extract
talks/{YYYY}-{slug}-git-archaeology.md # research
talks/{YYYY}-{slug}-changelog-analysis.md
talks/{YYYY}-{slug}-timeline.md
talks/{YYYY}-{slug}-concepts.md # concepts
talks/{YYYY}-{slug}-concepts-enriched.md
talks/{YYYY}-{slug}-angles.md # position
talks/{YYYY}-{slug}-titre.md
talks/{YYYY}-{slug}-descriptions.md
talks/{YYYY}-{slug}-feedback-draft.md
talks/{YYYY}-{slug}-pitch.md # script
talks/{YYYY}-{slug}-slides.md
talks/{YYYY}-{slug}-kimi-prompt.md
talks/{YYYY}-{slug}-revision-sheets.md # revision
```
## Final Summary Format
After Stage 6 completes, display:
```
Pipeline complete. Files generated:
Stage 1 — Extract:
✓ talks/{YYYY}-{slug}-summary.md
Stage 2 — Research (REX only):
✓ talks/{YYYY}-{slug}-git-archaeology.md
✓ talks/{YYYY}-{slug}-changelog-analysis.md
✓ talks/{YYYY}-{slug}-timeline.md
Stage 3 — Concepts:
✓ talks/{YYYY}-{slug}-concepts.md
✓ talks/{YYYY}-{slug}-concepts-enriched.md (if repo available)
Stage 4 — Position:
✓ talks/{YYYY}-{slug}-angles.md
✓ talks/{YYYY}-{slug}-titre.md
✓ talks/{YYYY}-{slug}-descriptions.md
✓ talks/{YYYY}-{slug}-feedback-draft.md
Stage 5 — Script:
✓ talks/{YYYY}-{slug}-pitch.md
✓ talks/{YYYY}-{slug}-slides.md
✓ talks/{YYYY}-{slug}-kimi-prompt.md ← copy-paste into kimi.com
Stage 6 — Revision:
✓ talks/{YYYY}-{slug}-revision-sheets.md
Next step: open kimi-prompt.md, verify no {PLACEHOLDER} remains, paste into kimi.com.
```
## Anti-patterns
- Do not run Stage 5 without an explicit angle + title choice from the user
- Do not run Stage 2 (research) in `--concept` mode
- Do not proceed to the next stage if an upstream stage failed
- Do not invent metrics or dates not present in the source material
## Validation
- [ ] All upstream files exist before launching a downstream stage
- [ ] Stage 4 CHECKPOINT respected before script
- [ ] Outputs named per convention `talks/{YYYY}-{slug}-{stage}.md`
- [ ] No empty placeholders in generated files
## Tips
- The orchestrator is the recommended entry point for first use
- For repeat users who know the pipeline, running individual stage skills is faster
- The `--stage=X` flag is useful for rerunning a single stage without redoing the full pipeline
## Related
- [Stage 1: Extract](../stage-1-extract/SKILL.md)
- [Stage 2: Research](../stage-2-research/SKILL.md)
- [Stage 3: Concepts](../stage-3-concepts/SKILL.md)
- [Stage 4: Position](../stage-4-position/SKILL.md)
- [Stage 5: Script](../stage-5-script/SKILL.md)
- [Stage 6: Revision](../stage-6-revision/SKILL.md)
- [Full workflow guide](../../../guide/workflows/talk-pipeline.md)

153
examples/skills/talk-pipeline/stage-1-extract/SKILL.md Normal file
View file

@ -0,0 +1,153 @@
---
name: talk-stage1-extract
description: Stage 1 — Extract and structure source material into a talk summary. Auto-detects REX vs Concept type.
tags: [talk, pipeline, presentation, stage-1]
allowed-tools:
- Write
- Read
- AskUserQuestion
---
# Talk Stage 1: Extract
Transforms raw material (article, transcript, notes, or a mix) into a structured summary ready for the pipeline's downstream stages. Auto-detects source type.
## When to Use This Skill
- Starting a new talk from any source material
- First step of the talk pipeline (always run before other stages)
- Auditing existing source material before committing to a talk
## What This Skill Does
1. **Collects metadata** — asks for slug, event, date, duration, audience, mode if not provided
2. **Reads the source** — loads the source file or inline content
3. **Detects source type** — REX (real-world proof) vs Concept (ideas/thesis) based on content signals
4. **Extracts the narrative arc** — chronological for REX, thematic for Concept
5. **Extracts metrics** — every measurable number with its source
6. **Identifies main themes** — 3-7 themes
7. **Flags gaps** — what's missing for a complete talk
8. **Writes `{slug}-summary.md`**
## Input
Required:
- Source file path or inline content (article `.mdx`, transcript `.md`, notes)
- Metadata: `slug`, `event`, `date`, `duration`, `audience`, `type` (--rex or --concept)
If metadata is missing → `AskUserQuestion` before proceeding.
## Output
`talks/{YYYY}-{slug}-summary.md`
## Source Type Detection
| REX signals | Concept signals |
|-------------|-----------------|
| Specific dates | Theses, arguments |
| Measured metrics | General observations |
| Project/tool names | Trend observations |
| Commits, releases, PRs | Analogies, metaphors |
| "I shipped", "We built" | "I think", "In my opinion" |
If hybrid → note both components in the summary.
## Output Format
```markdown
# Talk Summary — {Provisional Title}
**Slug** : {slug}
**Event** : {event}
**Date** : {date}
**Duration** : {duration} min
**Audience** : {audience description}
**Type detected** : REX | Concept | Hybrid
**Source** : {source file path}
---
## Narrative Arc
{Arc description: 3-5 sentences. Chronological if REX, thematic if Concept.}
## Main Themes
| # | Theme | Short description | Weight |
|---|-------|------------------|--------|
| 1 | {theme} | {description} | High/Medium/Low |
...
## Key Metrics Extracted
{All measurable numbers found in the source}
Format: `{value}` — {context} — Source: {section/page/git}
Examples:
- `1,200 commits` over 7 months — Source: "acceleration" section
- `-97% traffic` after SSE migration — Source: CHANGELOG v1.1.0
If none → "No verifiable metrics found (Concept mode)"
## Narrative Potential
{3-5 sentences on the strengths and possible narrative angles.
What makes this talk potentially strong. What might be missing.}
## Gaps Identified
- [ ] {gap 1} — {how to fill it}
- [ ] {gap 2} — {how to fill it}
If no obvious gaps → "No major gaps identified."
## Recommendations for next stages
- **Research**: {recommended / not applicable (Concept mode)} — {why}
- **Concepts**: {priority themes to explore}
- **Position**: {angles already visible from the source material}
---
*Generated by talk-stage1-extract — {date}*
*Source: {source path}*
```
## Metric Extraction Rules
- Do not round without indicating it
- Always include the metric's source
- If two sources contradict → flag both, do not pick one
- No invented metrics to fill gaps
- Use `{before} → {after}` format for evolutions
## Anti-patterns
- Vague summary ("This text is about AI...")
- Omitting metrics — even approximate ones with their source
- Hiding gaps — naming them is better than pretending they don't exist
- Changing the detected type without justification
- Inventing a narrative arc not present in the source
## Validation Checklist
- [ ] Source type detected and justified
- [ ] Narrative arc in 3-5 clear sentences
- [ ] All measurable metrics extracted with their source
- [ ] Main themes listed (3-7 max)
- [ ] Gaps explicitly identified
- [ ] File saved to `talks/{YYYY}-{slug}-summary.md`
## Tips
- Run this before the orchestrator if you want to verify the source material is usable
- The summary is the foundation — every downstream stage reads it
- Hybrid sources (part REX, part Concept) are fine — name both components clearly
## Related
- [Stage 2: Research](../stage-2-research/SKILL.md) — git archaeology (REX mode)
- [Stage 3: Concepts](../stage-3-concepts/SKILL.md) — reads this summary
- [Orchestrator](../orchestrator/SKILL.md) — runs all stages in sequence

196
examples/skills/talk-pipeline/stage-2-research/SKILL.md Normal file
View file

@ -0,0 +1,196 @@
---
name: talk-stage2-research
description: Stage 2 (REX mode only) — Git archaeology, changelog analysis, verified factual timeline. Skip automatically in Concept mode.
tags: [talk, pipeline, presentation, stage-2, git]
allowed-tools:
- Write
- Read
- Bash
---
# Talk Stage 2: Research (REX mode only)
Builds the git proof for a REX talk. Cross-references git history, CHANGELOG, and the Stage 1 summary to produce a verified timeline and velocity analysis.
**Automatically skipped in `--concept` mode** — only runs when the source material is a REX with git repository access.
## When to Use This Skill
- After Stage 1 (Extract) when building a REX talk
- When you have access to the project's git repository
- To verify metrics mentioned in the source material against actual git data
## What This Skill Does
1. **Reads the summary** — understands the period and themes from Stage 1
2. **Git archaeology** — extracts velocity metrics (read-only commands only)
3. **Changelog analysis** — scans releases, features, documented metrics
4. **Cross-references** — aligns git, CHANGELOG, and summary
5. **Builds the timeline** — verified dates, not estimated
6. **Writes 3 output files**
## Input
- `talks/{YYYY}-{slug}-summary.md` (from Stage 1 — required)
- `repo_path` — absolute path to the git repository
- Optional: CHANGELOG path if different from `{repo_path}/CHANGELOG.md`
## Output
Three files:
- `talks/{YYYY}-{slug}-git-archaeology.md`
- `talks/{YYYY}-{slug}-changelog-analysis.md`
- `talks/{YYYY}-{slug}-timeline.md`
## Git Commands (read-only only)
```bash
# Commits by month
git -C {repo_path} log --pretty=format:"%Y-%m" | sort | uniq -c
# Commits by contributor
git -C {repo_path} shortlog -sn --no-merges
# First and last date
git -C {repo_path} log --pretty=format:"%ad" --date=short | tail -1
git -C {repo_path} log --pretty=format:"%ad" --date=short | head -1
# Merged PRs (if merge commit convention)
git -C {repo_path} log --merges --oneline | wc -l
# Tags (releases)
git -C {repo_path} tag --sort=version:refname
# Velocity peak (busiest months)
git -C {repo_path} log --pretty=format:"%Y-%m" | sort | uniq -c | sort -rn | head -5
```
## Output Formats
### git-archaeology.md
```markdown
# Git Archaeology — {slug}
**Repo**: {repo_path}
**Period analyzed**: {start date} → {end date}
**Commands run**: {list}
## Global Metrics
| Metric | Value | Source |
|--------|-------|--------|
| Total commits | {n} | git log |
| Total merges/PRs | ~{n} | git log --merges |
| Total releases (tags) | {n} | git tag |
| Human contributors | {n} | git shortlog |
| Period covered | {n} months | first → last date |
## Monthly Velocity
| Month | Commits | Notes |
|-------|---------|-------|
| {YYYY-MM} | {n} | {context if notable} |
...
## Contributors
| Rank | Name | Commits | % |
|------|------|---------|---|
| 1 | {name} | {n} | {%} |
...
---
*Generated by talk-stage2-research — {date}*
```
### changelog-analysis.md
```markdown
# Changelog Analysis — {slug}
**Source**: {CHANGELOG path}
**Releases analyzed**: {n} (v{first} → v{last})
## Features by release (summary)
| Release | Date | Key features | Metrics mentioned |
|---------|------|--------------|------------------|
| {version} | {date} | {features} | {metrics} |
...
## Patterns identified
### Acceleration
{Periods of high velocity and what drove them}
### Inflection points
{Pivots, direction changes, major releases}
### Verifiable metrics in CHANGELOG
{Exhaustive list of numbers mentioned in CHANGELOG with their release}
---
*Generated by talk-stage2-research — {date}*
```
### timeline.md
```markdown
# Factual Timeline — {slug}
**Period**: {start} → {end} ({n} months)
**Cross-referenced sources**: Summary × Git history × CHANGELOG
---
## Month-by-month timeline
| Month | Commits | Releases | Versions | Key features | Talk event |
|-------|---------|----------|----------|--------------|-----------|
| {YYYY-MM} | {n} | {n} | {versions} | {features} | {anecdote/event} |
...
## Cross-reference: Conflicts and inconsistencies
{If dates or metrics contradict between sources, note here}
---
*Generated by talk-stage2-research — {date}*
*Sources: git log × {CHANGELOG path} × {summary path}*
```
## Key Rules
- **Read-only only** — no git commands that modify repo state
- **Verify before asserting** — a date not found in git = "unverified"
- **Cross-reference** — flag inconsistencies between sources, don't pick one arbitrarily
- **Granularity** — month by month minimum; week by week if the period is short (< 2 months)
## Anti-patterns
- Running git commands that modify the repository
- Estimating dates instead of verifying them in git
- Rounding metrics without flagging it
- Silently merging contradictory data from different sources
- Omitting quiet periods — plateaus tell a story too
## Validation Checklist
- [ ] Only read-only git commands executed
- [ ] Timeline covers the full period from summary
- [ ] All metrics have an explicit source (git or CHANGELOG)
- [ ] Conflicts between sources flagged in dedicated section
- [ ] 3 files generated and saved
## Tips
- The timeline is what Stage 3 (Concepts) uses to enrich concept scores — a good timeline makes the concept catalogue stronger
- "Quiet periods" in git velocity often correspond to hardest engineering challenges — worth noting
- If the CHANGELOG has no version tags, fall back to date-based anchoring
## Related
- [Stage 1: Extract](../stage-1-extract/SKILL.md) — prerequisite
- [Stage 3: Concepts](../stage-3-concepts/SKILL.md) — reads this timeline
- [Orchestrator](../orchestrator/SKILL.md)

161
examples/skills/talk-pipeline/stage-3-concepts/SKILL.md Normal file
View file

@ -0,0 +1,161 @@
---
name: talk-stage3-concepts
description: Stage 3 — Build a numbered, scored concept catalogue. Every concept gets HIGH / MEDIUM / LOW talk-potential rating.
tags: [talk, pipeline, presentation, stage-3]
allowed-tools:
- Write
- Read
---
# Talk Stage 3: Concepts
Builds an exhaustive catalogue of all identifiable concepts in the source material. Each concept is numbered, categorized, and scored for its talk potential.
## When to Use This Skill
- After Stage 1 (and Stage 2 if REX mode)
- Before Stage 4 (Position needs the concept catalogue)
- When you want a structured inventory of what's available before choosing an angle
## What This Skill Does
1. **Reads the summary** — loads `{slug}-summary.md`
2. **Reads the timeline** (if available) — enriches scoring with verified dates
3. **Extracts concepts** — full scan of the source material
4. **Categorizes** — assigns each concept to a domain category
5. **Scores** — HIGH / MEDIUM / LOW for talk potential
6. **Optional repo enrichment** — if repo_path is provided, analyzes AI config concepts
7. **Writes output files**
## Input
- `talks/{YYYY}-{slug}-summary.md` (required)
- `talks/{YYYY}-{slug}-timeline.md` (optional — enriches REX concepts)
- `repo_path` (optional — for config/infrastructure concept extraction)
## Output
- `talks/{YYYY}-{slug}-concepts.md` (main catalogue)
- `talks/{YYYY}-{slug}-concepts-enriched.md` (if repo_path provided)
## Scoring Criteria
### HIGH — Strong potential
- Demonstrable live or with a screenshot
- Counter-intuitive or surprising (triggers a reaction)
- Associated with verifiable numbers
- Concrete and actionable (explainable in 30 seconds)
- Differentiator vs other talks on the same topic
### MEDIUM — Moderate potential
- Useful but expected (not surprising)
- Missing concrete proof or numbers
- Too specific to one particular context
- Needs too much explanation for a 30-min talk
### LOW — Weak potential
- Too abstract or philosophical without concrete grounding
- Already heavily covered by other speakers
- Requires specific technical background
- Hard to illustrate in a slide
**Scoring discipline**: Max 30% HIGH. If everything is HIGH, nothing is.
## Standard Categories
| Category | Description |
|----------|-------------|
| **Architecture** | Technical decisions, stack, structural patterns |
| **Tooling** | Tools, workflows, automations |
| **Philosophy** | Principles, mindsets, approaches |
| **Workflow** | Work processes, habits |
| **Knowledge Transfer** | Onboarding, team, knowledge sharing |
| **Problems** | Obstacles encountered, trade-offs |
| **Open Source** | Contributions, sharing, community |
| **AI Config** | AI configuration, profiles, knowledge feeding |
| **AI Infrastructure** | Agents, skills, hooks, commands |
| **AI Quality** | Review, tests, anti-patterns |
| **AI Security** | Security hooks, guardrails |
| **Optimization** | Performance, cost/token reduction |
Adapt or create categories if the talk has domain-specific areas.
## Output Format
### concepts.md
```markdown
# Key Concepts — {provisional title}
**Date**: {date}
**Source**: {source path} × Summary × Timeline (if available)
---
## Concept table
| # | Concept | Category | Short description | Talk potential |
|---|---------|----------|------------------|----------------|
| 1 | **{Concept name}** | {Category} | {1-2 concrete sentences} | HIGH / MEDIUM / LOW |
...
---
## Category breakdown
| Category | Count | HIGH concepts | Examples |
|----------|-------|---------------|---------|
| {category} | {n} | {n} | {examples} |
...
| **TOTAL** | **{N}** | **{N HIGH}** | |
---
## Recommendations for positioning
{3-5 sentences on concept clusters that could form the talk's acts.
Which HIGH concepts reinforce each other? What narrative arc is emerging?}
```
### concepts-enriched.md (if repo available)
Same structure but focused on what the repo analysis reveals:
- Specialized agents (count, size, roles)
- Invocable skills (catalogue, domains covered)
- System hooks (events, logic)
- Modular config (profiles, modules, pipeline)
- Project-specific code patterns
For each enriched concept, include:
- **Exact source**: file and approximate line
- **Demo-able**: yes/no (can it be shown in a slide or live?)
## Anti-patterns
- Creating overly granular concepts (one feature = one concept max)
- Scoring HIGH by default — be selective
- Omitting LOW concepts (they're useful in positioning as "angles to avoid")
- Duplicating very similar concepts (merge them instead)
- Analyzing repo code if the repo isn't accessible
## Validation Checklist
- [ ] Minimum 15 concepts identified (20+ for REX with repo)
- [ ] Each concept has a 1-2 sentence concrete description
- [ ] Scores are calibrated (not all HIGH, not all LOW)
- [ ] Categories cover the summary's themes
- [ ] Positioning recommendations present
- [ ] Files saved to correct paths
## Tips
- The concept catalogue is what Stage 4 (Position) draws from — the richer it is, the better the angle choices
- LOW concepts are valuable: they define the boundaries of what NOT to put in the talk
- If two concepts feel very similar, merge them — a smaller, sharper list beats a long diluted one
## Related
- [Stage 1: Extract](../stage-1-extract/SKILL.md) — prerequisite
- [Stage 2: Research](../stage-2-research/SKILL.md) — provides timeline (REX)
- [Stage 4: Position](../stage-4-position/SKILL.md) — reads this catalogue
- [Orchestrator](../orchestrator/SKILL.md)

244
examples/skills/talk-pipeline/stage-4-position/SKILL.md Normal file
View file

@ -0,0 +1,244 @@
---
name: talk-stage4-position
description: Stage 4 — Strategic angles, titles, descriptions, peer feedback draft. Includes mandatory CHECKPOINT before script can start.
tags: [talk, pipeline, presentation, stage-4, checkpoint]
allowed-tools:
- Write
- Read
- AskUserQuestion
---
# Talk Stage 4: Position + CHECKPOINT
Generates strategic angles, titles, descriptions, and a peer-feedback draft. Then **stops and waits** for your angle + title choice before Stage 5 can proceed.
## When to Use This Skill
- After Stage 3 (Concepts) — needs the concept catalogue
- When deciding how to frame the talk
- Before sending the CFP (uses the generated descriptions directly)
## What This Skill Does
1. **Reads inputs** — summary + concepts + event constraints
2. **Generates angles** — 3-4 distinct angles with force/weakness analysis
3. **Recommends** — one clear choice with structured justification
4. **Generates titles** — 3-5 options per angle
5. **Generates descriptions** — short abstract + long CFP description
6. **Generates feedback draft** — ready-to-send message (3 formats)
7. **CHECKPOINT** — displays choice request and waits for user response
8. **Saves 4 files**
## Input
- `talks/{YYYY}-{slug}-summary.md` (required)
- `talks/{YYYY}-{slug}-concepts.md` (required)
- Event constraints: duration, audience, CFP format if applicable
## Output
- `talks/{YYYY}-{slug}-angles.md`
- `talks/{YYYY}-{slug}-titre.md`
- `talks/{YYYY}-{slug}-descriptions.md`
- `talks/{YYYY}-{slug}-feedback-draft.md`
## angles.md Format
```markdown
# Talk Angles — {provisional title}
**Goal**: Choose the angle that maximizes impact for {audience}.
**Audience**: {audience description}
---
## Angle 1: {Angle name}
**Pitch**: {2-3 sentences describing the talk from this angle}
**Strengths**:
- {strength 1}
- {strength 2}
**Weaknesses**:
- {weakness 1}
- {weakness 2}
**Audience fit**: Strong / Medium / Weak — {short justification}
**Verdict**: ⭐⭐⭐⭐⭐ (out of 5)
---
[Angle 2, Angle 3, (optional Angle 4) — same structure]
---
## Recommendation: Angle {X}, enriched by the others
**Angle {X} is the right choice.** Here's why:
### 1. It's the only angle that integrates the others
[Structure showing how other angles feed into the main one]
### 2. The narrative arc is natural and compelling
[Why the story holds better with this angle]
### 3. The metrics lend credibility throughout
[Which metrics support this angle most]
### 4. The final message emerges naturally
[How the conclusion flows from this angle]
---
## Recommended structure with sub-angles
| Act | Duration | Main angle | Integrated sub-angle |
|-----|----------|-----------|---------------------|
| 1. {name} | {n} min | {main angle} | {sub-angle} |
...
```
## titre.md Format
```markdown
# Titles — Talk {slug}
**Selected angle**: Angle {X} — {name}
**Constraints**: {duration} min | {audience}
---
## Titles for the recommended angle
### Option 1 (recommended)
**{Main title}**
*Optional subtitle: {subtitle}*
Strengths: {why this title works}
Audience appeal: {who it hooks}
### Option 2
**{Title}**
Strengths: {strengths}
[Options 3-5]
---
## Titles for alternative angles (backup)
### If Angle 2 chosen
- **{title}**
- **{title}**
[If Angle 3 chosen — same]
---
## Verdict
**Recommendation**: Option 1 — "{title}"
**Why**: {short justification}
```
## descriptions.md Format
```markdown
# Descriptions — Talk {slug}
---
## Short description (abstract, ~100 words)
{Full text — direct, engaging, starts with the impact or concrete promise.
Not "In this talk, we will..."}
---
## Long description (CFP, ~250 words)
{Full text — context, what the audience will learn, who it's for.
Includes key metrics if available.
Direct and factual tone.}
---
## Speaker pitch (bio-ready, ~50 words)
{Speaker introduction in 1-2 sentences, their relationship to the topic}
---
## Tags / Keywords
{5-10 relevant tags for CFP or search}
```
## CHECKPOINT (mandatory — Step 7)
After generating and saving the 4 files, display:
```
---
CHECKPOINT: Angle + Title choice
I've generated 4 files:
- talks/{YYYY}-{slug}-angles.md → {n} angles analyzed
- talks/{YYYY}-{slug}-titre.md → {n} title options
- talks/{YYYY}-{slug}-descriptions.md
- talks/{YYYY}-{slug}-feedback-draft.md
Before starting the script (Stage 5), I need your choice:
1. Which angle do you choose? (recommended: Angle {X} — {name})
2. Which title do you prefer? (recommended: "{title}")
You can also modify, combine, or propose something different.
Reply to start the script.
---
```
**Do not invoke Stage 5 without explicit user confirmation.**
## Angle Generation Rules
- Minimum 3 angles, maximum 4 (beyond that it's noise)
- Each angle must be genuinely distinct (not variations of the same)
- The recommendation must be clear and argued — not "your choice"
- Always test: "can this angle sustain the full duration without repeating?"
## Anti-patterns
- Click-bait titles ("What nobody tells you about AI")
- Recommending the last angle listed by default (recency bias)
- Descriptions that read like slide summaries
- Skipping the CHECKPOINT — it's the pipeline's most important control point
- Marketing language in descriptions (revolutionary, game-changer)
## Validation Checklist
- [ ] 3-4 angles with force/weakness/audience-fit analysis
- [ ] Clear recommendation with structured justification
- [ ] 3-5 titles for the recommended angle
- [ ] Short description (~100 words) and long description (~250 words)
- [ ] Feedback draft generated from template
- [ ] CHECKPOINT displayed clearly
- [ ] 4 files saved
## Tips
- Send `feedback-draft.md` to a peer before the checkpoint — 10 minutes of external feedback can save hours of rework on the script
- The recommendation is a starting point, not an order — your audience knowledge overrides any algorithmic suggestion
- Weak titles are usually too abstract: test each title by asking "would someone in the hallway stop walking to read this?"
## Templates
- Peer feedback formats: [`templates/feedback-draft.md`](templates/feedback-draft.md)
## Related
- [Stage 3: Concepts](../stage-3-concepts/SKILL.md) — prerequisite
- [Stage 5: Script](../stage-5-script/SKILL.md) — starts after this CHECKPOINT
- [Orchestrator](../orchestrator/SKILL.md)

89
examples/skills/talk-pipeline/stage-4-position/templates/feedback-draft.md Normal file
View file

@ -0,0 +1,89 @@
# Template: Peer Feedback Draft
Usage: Send to 1-2 trusted peers BEFORE submitting the CFP or finalizing the script.
Adapt with the actual talk information before sending.
---
## Version 1: DM / short message (Slack, LinkedIn)
```
Hi {firstname},
I'm preparing a talk for {event} ({date}).
Working title: "{title}"
The promise: {1 sentence on what the audience will take away}
Quick context: {2-3 sentences on the content — angle, key metrics, concrete examples}
Would you have 10 minutes this week to give feedback?
Mainly on: does the title hook / is the topic relevant for a {audience} audience?
Thanks
```
---
## Version 2: Email (for less accessible peers)
```
Subject: Feedback on talk "{title}" — {event}
Hi {firstname},
I'm preparing a {duration}-min talk for {event} ({date}), and I'd love your input before finalizing.
**Working title**: "{title}"
**What I'll cover**:
{3-5 bullets describing the content — concrete, not abstract}
**Audience**: {audience description}
**What I need**:
- Does the title hook?
- Does the topic feel relevant for this audience?
- Is there something obvious I'm missing?
No need for a long response — 5 sentences is enough.
Thanks,
{firstname}
```
---
## Version 3: Public validation (LinkedIn post or tweet)
```
I'm preparing a talk for {event}.
Topic: {angle in 1 direct sentence, no official title yet}
A few numbers to set the scene: {2-3 key metrics}
Simple question: would this topic resonate with you if you were in the room?
{optional: open question to spark comments}
```
---
## Pre-send Checklist
- [ ] The title is concrete (no jargon or abstraction)
- [ ] The promise is clear in 1 sentence
- [ ] Key metrics are mentioned (if REX)
- [ ] Target audience is specified
- [ ] The ask is specific (not "give me general feedback")
- [ ] Tone is direct, not apologetic ("it might perhaps be worth...")
## What to look for in the feedback
1. **First reaction**: want to attend or not?
2. **Title**: clear? catchy? too technical?
3. **Angle**: original or already seen 10 times?
4. **Audience fit**: does it match the {audience} profile?
5. **Gaps**: something important that's missing?

223
examples/skills/talk-pipeline/stage-5-script/SKILL.md Normal file
View file

@ -0,0 +1,223 @@
---
name: talk-stage5-script
description: Stage 5 — 5-act pitch with speaker notes, slide spec, and Kimi prompt for AI slide generation. Requires validated angle + title from Stage 4.
tags: [talk, pipeline, presentation, stage-5, kimi]
allowed-tools:
- Write
- Read
---
# Talk Stage 5: Script
Produces the complete talk in 3 deliverables: the 5-act narrative with speaker notes, the slide specification, and the Kimi prompt ready to copy-paste.
**Prerequisite**: The user has validated angle + title at the Stage 4 CHECKPOINT. Do not run this stage without that confirmation.
## When to Use This Skill
- After Stage 4 CHECKPOINT is confirmed
- When you have a validated angle + title
- To produce the complete script and slide spec
## What This Skill Does
1. **Verifies inputs** — all upstream files + angle/title confirmation
2. **Loads the Kimi template** — from `templates/kimi-prompt-template.md`
3. **Builds the pitch** — 5-act structure with speaker notes and timing
4. **Builds the slide spec** — slide by slide with visual, text, notes
5. **Generates the Kimi prompt** — fills the template with talk content
6. **Saves 3 files**
## Input
- `talks/{YYYY}-{slug}-summary.md`
- `talks/{YYYY}-{slug}-concepts.md`
- `talks/{YYYY}-{slug}-angles.md`
- `talks/{YYYY}-{slug}-titre.md`
- `talks/{YYYY}-{slug}-timeline.md` (optional — enriches speaker notes)
- **Chosen angle + chosen title** (explicit user confirmation from Stage 4)
## Output
- `talks/{YYYY}-{slug}-pitch.md`
- `talks/{YYYY}-{slug}-slides.md`
- `talks/{YYYY}-{slug}-kimi-prompt.md`
## pitch.md Format
```markdown
# Pitch — {title}
**Event**: {event} | **Duration**: {duration} min | **Slides**: ~{n} slides
**Angle**: {selected angle}
---
## Global structure
| Act | Title | Duration | Slides |
|-----|-------|----------|--------|
| 1 | {act title} | {n} min | {n} slides |
...
| Total | | {duration} min | {n} slides |
---
## ACT 1: {TITLE} (Slides 1-{n}, ~{n} min)
{Narrative description of the act in 2-3 sentences — what happens, the emotion targeted}
---
**Slide {n} — {Slide title}**
- Visual: {visual description — simple, precise}
- Key text: {what appears on screen — max 10 words}
- Speaker notes: "{exact text to say — conversational, natural}"
- Duration: {n} min
- Pause: yes/no | {if yes: why, intended effect}
---
[Repeat for each slide in the act]
---
[Acts 2, 3, 4, 5 — same structure]
---
## Key moments (must not be rushed)
| Moment | Slide | What happens | Technique |
|--------|-------|-------------|-----------|
| {moment} | {n} | {description} | Pause / Number / Anecdote |
---
## Timing check
| Act | Planned | Buffer | Total |
|-----|---------|--------|-------|
| ACT 1 | {n} min | 30s | {n} min |
...
| **Total** | **{n} min** | **{n} min** | **{n} min** |
Q&A planned: {n} min
```
## slides.md Format
Slide-by-slide spec, ready to hand to a designer or pass to Kimi.
```markdown
# Slides Spec — {title}
**Total**: {n} slides | **Event**: {event} | **Date**: {date}
---
### SLIDE 1 — Title Slide
- **Main title**: {title}
- **Subtitle**: {subtitle or tagline}
- **Speaker**: {name}
- **Event**: {event} — {date}
- **Visual**: {background description — texture, image, mood}
- **Speaker notes**: "{text}"
- **Duration**: {n} sec
---
### SLIDE {n} — {Slide title}
- **Title**: {title}
- **Visual**: {precise visual description}
- Type: {bar chart / timeline / diagram / big number / comparison table / screenshot placeholder}
- Data: {specific values if chart}
- **Key text**: {what appears — max 30 words total}
- **Metrics displayed**: {numbers if metrics slide}
- **Speaker notes**: "{exact text}"
- **Duration**: {n} min
- **Act**: {act number}
---
[Repeat for each slide]
---
## Screenshots to capture
| Slide | Screenshot | Source | Status |
|-------|-----------|--------|--------|
| {n} | {description} | {tool/URL} | To capture / Available |
```
## kimi-prompt.md
Fill the template at `templates/kimi-prompt-template.md` with the talk's content.
Required sections to complete:
- Full title and subtitle
- Speaker name + event + date + duration + language + slide count
- Design requirements (adjust color palette if different from default)
- Slide Content Structure (section by section, all 5 acts)
- Screenshot placeholders (slides awaiting real captures)
- Tone reference (adapt to the talk's style)
**Verify no `{PLACEHOLDER}` remains in the final file** before handing to the user.
## Script Construction Rules
- **1 idea per slide** — never more, never less
- **Speaker notes = what you say, not what you read** — minimal slides, conversational notes
- **Numbers are heroes** — metrics appear large and alone on their slide
- **Anecdotes > explanations** — "one Tuesday morning, 3 bugs..." > "git worktrees enable parallelism"
- **Explicit transitions** — note the link between each act in the notes
- **Realistic timing** — add 10% buffer total (slides always run long)
## Anti-patterns
- Slides loaded with bullets (never more than 5 words per line)
- Speaker notes in technical jargon (read them aloud to validate)
- Vague Kimi prompt ("make it look nice") — each slide must be precise
- Omitting screenshot placeholders from the Kimi prompt
- Generating more slides than the duration allows (2-3 min/slide for REX)
## Validation Checklist
- [ ] Pitch covers 5 acts with coherent timing (±10% of target duration)
- [ ] Each slide has visual + text + speaker notes
- [ ] Key moments identified (pauses, punchlines, transitions)
- [ ] Slides spec ready to hand to a designer
- [ ] Kimi prompt complete (all template sections filled)
- [ ] Screenshots to capture listed with source
- [ ] No `{PLACEHOLDER}` remaining in kimi-prompt.md
- [ ] 3 files saved
## Using the Kimi Prompt
1. Open `{slug}-kimi-prompt.md`
2. Verify no `{PLACEHOLDER}` remains (search the file)
3. Go to [kimi.com](https://kimi.com) — free account, no API needed
4. Start a new conversation
5. Copy-paste the entire prompt
6. Kimi generates the presentation
For iterative refinement: add follow-up messages targeting specific slides. "Slide 7: make the number larger, remove the bullet list."
## Tips
- Speaker notes are the heart of this stage — they're what distinguishes a good talk from a good slide deck
- The Kimi template includes a dark design system with orange accent colors. Adapt `Color Palette` in the template if your brand has different colors
- Generate more slides than needed in the first pass, then cut — easier than writing from scratch
## Templates
- Kimi prompt: [`templates/kimi-prompt-template.md`](templates/kimi-prompt-template.md)
## Related
- [Stage 4: Position](../stage-4-position/SKILL.md) — prerequisite (CHECKPOINT required)
- [Stage 6: Revision](../stage-6-revision/SKILL.md) — reads pitch + slides
- [Orchestrator](../orchestrator/SKILL.md)

163
examples/skills/talk-pipeline/stage-5-script/templates/kimi-prompt-template.md Normal file
View file

@ -0,0 +1,163 @@
# Kimi Presentation Template
> Copy-paste this entire prompt into Kimi.com to generate the presentation.
> Fill in all {PLACEHOLDER} values before sending.
> Search for `{` in the file to find remaining placeholders.
---
Please create a professional conference talk presentation with the following specifications:
## Presentation Requirements
**Title**: {FULL_TITLE}
**Speaker**: {SPEAKER_NAME}
**Event**: {EVENT_NAME} — {MONTH_YEAR}
**Target Audience**: {AUDIENCE_DESCRIPTION}
**Duration**: {DURATION} minutes ({SLIDE_COUNT} slides)
**Language**: {LANGUAGE}
**Format**: Conference talk — storytelling, minimal text, big numbers, high visual impact
## Design Requirements
**Visual Style**:
- Dark theme, modern and minimal
- Maximum visual impact with minimal text
- Large typography for key numbers (48pt minimum for metrics)
- Icons over bullet points whenever possible
- Clean sans-serif fonts (Inter, SF Pro, or similar)
- Ample white space even on dark backgrounds
- High contrast for readability on projector screens
**Color Palette**:
- Primary background: Near-black (#0a0a0a)
- Surface background: Dark gray (#141414) — for cards, content blocks
- Elevated background: (#1e1e1e) — for highlighted sections
- Border: (#2a2a2a) — subtle separation between elements
- Primary text: Off-white (#e5e5e5)
- Secondary text: Medium gray (#a3a3a3)
- Muted text: (#8a8a8a) — for labels, captions
- Accent - Orange: (#f97316) — for key numbers, highlights, CTAs
- Accent hover - Light orange: (#fb923c) — for secondary highlights
- Success green: (#22c55e) — for positive metrics only
- Warning red: (#ef4444) — for problems, errors, negative metrics only
**Layout Preferences**:
- 1 idea per slide — never more
- Consistent footer with slide number (discrete, bottom-right)
- Left-aligned text for readability
- Maximum 30 words per slide (excluding titles)
- Numbers displayed extra-large and centered when they are the main point
- Code blocks with slightly lighter background (#1e293b) and monospace font
- Diagrams using simple boxes, arrows, and the accent color palette
## Slide Content Structure
### ACT 1: {ACT1_TITLE} (Slides 1-{ACT1_LAST_SLIDE}, ~{ACT1_DURATION} min)
---
**Slide 1 — Title Slide**
- Main title: "{FULL_TITLE}"
- Subtitle: "{SUBTITLE_OR_TAGLINE}"
- Speaker: {SPEAKER_NAME}
- Event: {EVENT_NAME} — {MONTH_YEAR}
- Visual: {BACKGROUND_DESCRIPTION}
- Speaker notes: "{OPENING_NOTES}"
- Duration: {TITLE_SLIDE_DURATION} min
---
**Slide 2 — {SLIDE2_TITLE}**
- Title: "{SLIDE2_TITLE}"
- Visual: {SLIDE2_VISUAL_DESCRIPTION}
- Key text: "{SLIDE2_KEY_TEXT}"
- Speaker notes: "{SLIDE2_NOTES}"
- Duration: {SLIDE2_DURATION} min
---
{REPEAT_FOR_REMAINING_SLIDES_IN_ACT1}
---
### ACT 2: {ACT2_TITLE} (Slides {ACT2_FIRST}-{ACT2_LAST}, ~{ACT2_DURATION} min)
---
{SLIDES_FOR_ACT2}
---
### ACT 3: {ACT3_TITLE} (Slides {ACT3_FIRST}-{ACT3_LAST}, ~{ACT3_DURATION} min)
---
{SLIDES_FOR_ACT3}
---
### ACT 4: {ACT4_TITLE} (Slides {ACT4_FIRST}-{ACT4_LAST}, ~{ACT4_DURATION} min)
---
{SLIDES_FOR_ACT4}
---
### ACT 5 + CONCLUSION: {ACT5_TITLE} (Slides {ACT5_FIRST}-{LAST_SLIDE}, ~{ACT5_DURATION} min)
---
{SLIDES_FOR_ACT5}
---
## Speaker Notes Guidelines
For each slide, speaker notes include:
- The key narrative beat (what emotion/reaction to aim for)
- Exact phrasing for critical moments (punchlines, transitions)
- Timing guidance
- Pause indicators for dramatic effect
Key storytelling moments requiring deliberate pauses:
1. {PAUSE_MOMENT_1} — {WHY_PAUSE}
2. {PAUSE_MOMENT_2} — {WHY_PAUSE}
3. {PAUSE_MOMENT_3} — {WHY_PAUSE}
## Screenshot Placeholders
Several slides are designed to accommodate real screenshots. Mark these areas clearly with a placeholder rectangle labeled "SCREENSHOT AREA":
| Slide | Screenshot | Source |
|-------|-----------|--------|
| {SLIDE_N} | {SCREENSHOT_DESCRIPTION} | {SOURCE} |
{REPEAT_FOR_ALL_SCREENSHOT_SLIDES}
## Additional Requirements
- Total slide count: Exactly {SLIDE_COUNT} slides
- Include page numbers on all slides except slide 1 (title)
- Add subtle section transition markers between acts (small act number in corner)
- Dark background throughout (#0a0a0a base, #141414 for cards) — projector-friendly
- All diagrams use the accent color palette (orange #f97316 on dark, #1e1e1e for elevated elements)
- Numbers are the hero of this presentation — make them unmissable
- No animations or complex transitions — simple fade between slides
- Footer: discrete slide number bottom-right, speaker name bottom-left
- The overall feel should be: {TONE_DESCRIPTION}
## Accessibility
- Ensure text contrast ratio meets WCAG AA standards (4.5:1 minimum)
- Use large, readable fonts (minimum 20pt for body text, 28pt+ for headers, 48pt+ for key numbers)
- Don't rely on color alone to convey information (use icons + color)
- Test readability at typical projector resolution (1920x1080)
## Tone Reference
{TONE_PARAGRAPH}
---
**End of Prompt**

230
examples/skills/talk-pipeline/stage-6-revision/SKILL.md Normal file
View file

@ -0,0 +1,230 @@
---
name: talk-stage6-revision
description: Stage 6 — Revision sheets for during and after the talk. Master concept table, Q&A cheat-sheet, glossary, external resources.
tags: [talk, pipeline, presentation, stage-6]
allowed-tools:
- Write
- Read
---
# Talk Stage 6: Revision
Produces revision sheets usable during and after the talk. Quick navigation by act, master concept table with URLs to share, Q&A cheat-sheet, and glossary.
## When to Use This Skill
- After Stage 5 (Script) — needs pitch + slides
- Before a talk where Q&A is expected
- To create a shareable resource for attendees
## What This Skill Does
1. **Reads all inputs** — pitch + slides + concepts (+ timeline if available)
2. **Extracts navigation** — table of contents with anchors per act
3. **Rebuilds by act** — key concepts + metrics + anecdotes + probable Q&A
4. **Builds master table** — all concepts + definitions + URLs
5. **Builds Q&A cheat-sheet** — 6-10 questions + short answers + links
6. **Builds glossary** — technical terms from the talk
7. **Lists external resources**
8. **Assembles and saves**
## Input
- `talks/{YYYY}-{slug}-pitch.md` (required)
- `talks/{YYYY}-{slug}-slides.md` (required)
- `talks/{YYYY}-{slug}-concepts.md` (required)
- `talks/{YYYY}-{slug}-timeline.md` (optional — for metrics accuracy)
## Output
`talks/{YYYY}-{slug}-revision-sheets.md`
## Output Format
```markdown
# Revision Sheets — {title}
**Date**: {date} · **Talk duration**: {n} min + {n} min Q&A
**Purpose**: Someone asks a question → find the section → share the URL in 5 seconds
---
## Quick navigation
| Section | Content |
|---------|---------|
| [Act 1](#act-1) | {1-line summary} |
| [Act 2](#act-2) | {1-line summary} |
| [Act 3](#act-3) | {1-line summary} |
| [Act 4](#act-4) | {1-line summary} |
| [Act 5](#act-5) | {1-line summary} |
| [Conclusion](#conclusion) | {1-line summary} |
| [Master Table](#master-table) | All concepts + URLs |
| [Q&A Cheat-sheet](#qa-cheat-sheet) | {n} anticipated questions + answers |
| [Resources](#external-resources) | Links mentioned in the talk |
---
## ACT 1: {Title} (Slides 1-{n})
**~{n} min · {period or context}**
### Key concepts
| Concept | Short definition | URL to share |
|---------|-----------------|--------------|
| **{Concept}** | {1-2 concrete sentences} | {URL or "no direct link"} |
...
### Metrics to know
```
{Metrics as code block — one per line, format: value → context}
```
### Storytelling / Anecdotes
- **{Anecdote name}**: "{Quote or summary}"
### Probable Q&A for Act {n}
| Question | Short answer |
|----------|-------------|
| "{probable question}" | {direct answer, 2-3 sentences max} |
---
[Repeat for each act]
---
## Conclusion (Slides {n}-{n})
**~{n} min**
### Summary metrics (the big numbers)
```
{All summary metrics — one per line}
```
### {N} actions for Monday (if applicable)
1. **{Action 1}**: {description + why}
2. **{Action 2}**: {description + why}
3. **{Action 3}**: {description + why}
---
## Master Table: Concept → Definition → URL to share
**The core deliverable. Every technical concept from the talk.**
| Concept | Definition (1-2 sentences) | Slide | URL to share | Notes |
|---------|--------------------------|-------|--------------|-------|
| **{Concept}** | {precise, concise definition} | {n} | {URL or "pure storytelling"} | {guide section if applicable} |
...
---
## Q&A Cheat-sheet
**The {n} most probable questions + short answers + URL to send**
---
### Q1 — "{Question}"
**Short answer**:
{Answer in 3-5 bullets}
**To go further**:
- {Link 1 with context}
- {Link 2 with context}
---
[Q2 through Q{n} — same structure]
---
## External Resources Mentioned in the Talk
### Priority URLs to share
| Resource | URL | Context |
|----------|-----|---------|
| **{Resource}** | `{url}` | {why it's important} |
...
### Studies and external sources (if applicable)
| Source | URL | How used in the talk |
|--------|-----|---------------------|
| **{Source}** | `{url}` | {how it's cited} |
---
## Quick Glossary (memory aid if you blank)
| Term | Ultra-short definition |
|------|----------------------|
| {term} | {10 words max} |
...
---
*Generated {date}. Source: slides, concepts, pitch.*
```
## Construction Rules
### Master Table
- Include ALL technical concepts mentioned in pitch and slides
- URL = link to a public resource (GitHub, docs, guide) — no dead links
- If no link: note "pure storytelling, no guide section" or "concept specific to the project"
- Definition = what you'd say if someone in the room asked "what's that?"
### Q&A Cheat-sheet
- 6 questions minimum, 10 maximum
- Select the most probable questions for the audience
- Short answer = what you'd say orally in 20 seconds max
- "To go further" = actionable links, not vague references
### Metrics
- Code block format for metrics (faster to scan)
- One metric per line: `{value}` — {context}
- Always with units (%, ms, K, days...)
### Anecdotes
- Extract verbatim from pitch where possible (for memorization)
- Quote format for phrases to say exactly
## Anti-patterns
- Incomplete Master Table (missing concepts = unusable in Q&A)
- Q&A answers that are too long (if it exceeds 5 bullets, cut)
- Invented or approximate URLs (verify every link is real)
- Copy-pasting pitch descriptions without adapting to cheat-sheet format
- Forgetting the glossary (essential when you have a memory blank)
## Validation Checklist
- [ ] Quick navigation with working anchor links
- [ ] Each act has its section (concepts + metrics + Q&A)
- [ ] Master Table covers all pitch concepts (cross-check)
- [ ] Minimum 6 questions in Q&A cheat-sheet
- [ ] External resources listed with verified URLs
- [ ] Glossary present
- [ ] File saved: `talks/{YYYY}-{slug}-revision-sheets.md`
## Tips
- The revision sheets are the most re-used output — attendees ask for links, you pull up the master table in 5 seconds
- Build the Q&A from the audience profile: what are the 3 most skeptical questions a senior dev in that room would ask?
- The glossary is your safety net: you blank on a term mid-talk, glance at the glossary, recover in 2 seconds
## Related
- [Stage 5: Script](../stage-5-script/SKILL.md) — prerequisite
- [Orchestrator](../orchestrator/SKILL.md)

7
guide/workflows/README.md
View file

@ -87,6 +87,12 @@ Generate professional PDFs using Quarto/Typst with Claude Code.
**When to use**: Reports, documentation, whitepapers, technical documents
### [Talk Preparation Pipeline](./talk-pipeline.md) ⭐ NEW
6-stage skill pipeline: raw material → structured talk → AI-generated slides via Kimi.
**When to use**: Conference talks, meetup presentations, internal tech talks — from article, transcript, or notes
### [TTS Setup](./tts-setup.md)
Configure Text-to-Speech for Claude Code responses (Agent Vibes integration).
@ -120,6 +126,7 @@ Systematically explore and understand unfamiliar codebases.
| **New project from template** | [Skeleton Projects](./skeleton-projects.md) |
| **Team AI instructions** | [Team AI Instructions](./team-ai-instructions.md) |
| **Documentation** | [PDF Generation](./pdf-generation.md) |
| **Conference talk from raw material** | [Talk Preparation Pipeline](./talk-pipeline.md) |
| **Audio feedback** | [TTS Setup](./tts-setup.md) |
---

539
guide/workflows/talk-pipeline.md Normal file
View file

@ -0,0 +1,539 @@
---
title: "Talk Preparation Pipeline: From Idea to Slides with AI"
description: "6-stage skill pipeline that transforms raw material into a conference talk with AI-generated slides"
tags: [workflow, skills, pipeline, presentation, ai-handoff]
---
# Talk Preparation Pipeline: From Idea to Slides with AI
> **Confidence**: Tier 2 — Validated in production on real conference talks (DevWithAI Lyon, 2026).
Transform a raw article, transcript, or notes into a complete conference talk — including a Kimi-ready prompt for AI-generated slides. Six stages, two modes, one human-in-the-loop checkpoint.
---
## Table of Contents
1. [TL;DR](#tldr)
2. [When to Use](#when-to-use)
3. [Prerequisites](#prerequisites)
4. [Pipeline Overview](#pipeline-overview)
5. [Stage-by-Stage Guide](#stage-by-stage-guide)
6. [The Kimi Handoff](#the-kimi-handoff)
7. [Human-in-the-Loop Checkpoints](#human-in-the-loop-checkpoints)
8. [Adapting the Pipeline](#adapting-the-pipeline)
9. [Real-World Example](#real-world-example)
10. [Common Pitfalls](#common-pitfalls)
11. [Design Patterns Showcased](#design-patterns-showcased)
12. [See Also](#see-also)
---
## TL;DR
```
Source Material (article / transcript / notes)
│
▼
[Stage 1] EXTRACT ─────────────── {slug}-summary.md
│
├──────────────────────────────────────┐
│ │
▼ (--rex only) ▼
[Stage 2] RESEARCH [Stage 3] CONCEPTS
git-archaeology.md concepts.md
changelog-analysis.md concepts-enriched.md
timeline.md │
│ │
└──────────────┬──────────────┘
│
▼
[Stage 4] POSITION
angles.md
titre.md
descriptions.md
feedback-draft.md
│
[CHECKPOINT]
User selects angle + title
│
▼
[Stage 5] SCRIPT
pitch.md
slides.md
kimi-prompt.md ──► Copy-paste into Kimi.com
│
▼
[Stage 6] REVISION
revision-sheets.md
```
Two modes: **REX** (talk with real-world proof — git history, metrics) and **Concept** (idea/thesis-based — skips Stage 2).
---
## When to Use
This pipeline fits when you have a talk to prepare and either:
- **A REX to tell**: You built something, shipped it, have real metrics — and want to turn that into a structured conference talk
- **A concept to develop**: You have an article, notes, or ideas you want to turn into a structured presentation
Suitable formats:
- Conference talks (20-45 min)
- Meetup presentations (15-30 min)
- Internal tech talks
- Workshop openings
Not suited for: slide-deck updates for recurring meetings, short lightning talks under 10 min, or situations where you have no existing material to work from.
---
## Prerequisites
**Required**:
- Claude Code with skills installed (see [examples/skills/talk-pipeline/](../../examples/skills/talk-pipeline/))
- Source material: article `.mdx`, transcript `.md`, notes, or mix
- Talk metadata: slug, event name, date, duration, audience description
**For REX mode only**:
- Access to the git repository you want to analyze
- Optional: `CHANGELOG.md` path if different from repo root
**For Kimi slide generation (Stage 5 output)**:
- Free account at [kimi.com](https://kimi.com) (no API needed — just copy-paste)
**Optional but recommended**:
- `talks/` directory in your project root for output files
- 1-2 trusted peers available for the feedback draft (Stage 4)
---
## Pipeline Overview
### Output files per mode
| File | Stage | REX | Concept |
|------|-------|-----|---------|
| `{slug}-summary.md` | 1 | ✓ | ✓ |
| `{slug}-git-archaeology.md` | 2 | ✓ | — |
| `{slug}-changelog-analysis.md` | 2 | ✓ | — |
| `{slug}-timeline.md` | 2 | ✓ | — |
| `{slug}-concepts.md` | 3 | ✓ | ✓ |
| `{slug}-concepts-enriched.md` | 3 | ✓ (if repo) | — |
| `{slug}-angles.md` | 4 | ✓ | ✓ |
| `{slug}-titre.md` | 4 | ✓ | ✓ |
| `{slug}-descriptions.md` | 4 | ✓ | ✓ |
| `{slug}-feedback-draft.md` | 4 | ✓ | ✓ |
| `{slug}-pitch.md` | 5 | ✓ | ✓ |
| `{slug}-slides.md` | 5 | ✓ | ✓ |
| `{slug}-kimi-prompt.md` | 5 | ✓ | ✓ |
| `{slug}-revision-sheets.md` | 6 | ✓ | ✓ |
REX mode: 13-14 files. Concept mode: 10 files.
### Naming convention
All outputs follow `talks/{YYYY}-{slug}-{stage-label}.md`. Example for slug `devwithai` in 2026:
```
talks/2026-devwithai-summary.md
talks/2026-devwithai-git-archaeology.md
talks/2026-devwithai-concepts.md
talks/2026-devwithai-angles.md
...
```
---
## Stage-by-Stage Guide
### Stage 1: Extract
**What it does**: Reads the source material and produces a structured summary — narrative arc, key metrics, main themes, gaps.
| | |
|--|--|
| **Input** | Source file + metadata (slug, event, date, duration, audience, mode) |
| **Output** | `{slug}-summary.md` |
| **Tools used** | Read, Write, AskUserQuestion |
| **Mode** | REX + Concept |
**Key rules**:
- Auto-detects source type (REX vs Concept) based on signals (dates, metrics, "I shipped" vs "I think")
- Extracts every measurable metric with its source — no invented numbers
- Flags gaps explicitly rather than hiding them
**Invocation**:
```
/talk-stage1-extract
```
Or via the orchestrator:
```
/talk-pipeline --stage=extract --slug=my-talk --event="Conf 2026" --date=2026-06-15 --duration=30 --audience="senior devs"
```
**Review before moving on**:
- Arc narrative is coherent (not generic: "this talk is about AI...")
- All metrics have an explicit source
- Gaps are listed (even if it's "no major gaps")
- Type detection is correct (REX / Concept / Hybrid)
---
### Stage 2: Research (REX mode only)
**What it does**: Git archaeology — extracts velocity metrics, cross-references CHANGELOG, builds a factual timeline verified by git (not estimated).
| | |
|--|--|
| **Input** | `{slug}-summary.md` + repo path |
| **Output** | `git-archaeology.md`, `changelog-analysis.md`, `timeline.md` |
| **Tools used** | Bash (read-only git commands), Read, Write |
| **Mode** | REX only — **automatically skipped in Concept mode** |
**Key rules**:
- Read-only git commands only — never modifies the repository
- Dates not found in git are marked "unverified" — never estimated
- Contradictions between sources are flagged, not silently resolved
**Git commands used** (read-only):
```bash
git log --pretty=format:"%Y-%m" | sort | uniq -c # velocity by month
git shortlog -sn --no-merges # contributors
git tag --sort=version:refname # releases
git log --merges --oneline | wc -l # PRs merged
```
**Review before moving on**:
- Timeline covers the full period from summary
- No estimated dates — all verified
- Velocity peaks have contextual notes
---
### Stage 3: Concepts
**What it does**: Builds a numbered, scored catalogue of all concepts in the material. Each concept gets a talk-potential score (HIGH / MEDIUM / LOW).
| | |
|--|--|
| **Input** | `{slug}-summary.md` + `{slug}-timeline.md` (optional) |
| **Output** | `{slug}-concepts.md`, `{slug}-concepts-enriched.md` (if repo available) |
| **Tools used** | Read, Write |
| **Mode** | REX + Concept |
**Score criteria**:
- **HIGH**: Demonstrable, counter-intuitive, has verified numbers, actionable in 30 seconds
- **MEDIUM**: Useful but expected, missing proof or numbers
- **LOW**: Too abstract, over-covered, hard to illustrate in a slide
**Scoring discipline**: Maximum 30% HIGH — being selective is the point.
**Review before moving on**:
- 15+ concepts identified (20+ for REX with repo access)
- Scores are calibrated (not all HIGH, not all LOW)
- Each concept has a 1-2 sentence concrete description
---
### Stage 4: Position + CHECKPOINT
**What it does**: Generates strategic angles, titles, descriptions, and a peer-feedback draft. Then **stops and waits** for your angle + title choice.
| | |
|--|--|
| **Input** | `{slug}-summary.md` + `{slug}-concepts.md` + event constraints |
| **Output** | `angles.md`, `titre.md`, `descriptions.md`, `feedback-draft.md` |
| **Tools used** | Read, Write, AskUserQuestion |
| **Mode** | REX + Concept |
**What gets generated**:
- **3-4 angles**: each with forces, weaknesses, audience fit, verdict (scored /5)
- **Recommendation**: one clear choice with structured justification
- **3-5 titles** per angle
- **Description short** (~100 words abstract) + **description long** (~250 words CFP)
- **Feedback draft**: ready-to-send message for peer validation (3 formats: Slack DM, email, LinkedIn post)
**CHECKPOINT display** (mandatory before Stage 5):
```
---
CHECKPOINT : Choix angle + titre
J'ai généré 4 fichiers :
- talks/{YYYY}-{slug}-angles.md → {n} angles analysés
- talks/{YYYY}-{slug}-titre.md → {n} options de titre
- talks/{YYYY}-{slug}-descriptions.md
- talks/{YYYY}-{slug}-feedback-draft.md
Avant de lancer le script (Stage 5), j'ai besoin de ton choix :
1. Quel angle tu retiens ? (recommandé : Angle {X} — {nom})
2. Quel titre tu préfères ? (recommandé : "{titre}")
Tu peux aussi modifier, mixer, ou proposer quelque chose d'autre.
---
```
**Stage 5 cannot start without explicit user confirmation.**
**Review before confirming**:
- You've read the feedback draft and optionally sent it to a peer
- The recommended angle can sustain the full duration without repetition
- The title is concrete (no jargon, no click-bait)
---
### Stage 5: Script
**What it does**: Builds the complete talk in 5 acts with speaker notes, the slide specification, and the Kimi prompt.
| | |
|--|--|
| **Input** | summary + concepts + timeline (optional) + **validated angle + title** |
| **Output** | `{slug}-pitch.md`, `{slug}-slides.md`, `{slug}-kimi-prompt.md` |
| **Tools used** | Read, Write |
| **Mode** | REX + Concept |
**Three deliverables**:
1. **`pitch.md`**: The 5-act narrative with speaker notes, timing, key moments. What you say — not what you read from slides.
2. **`slides.md`**: Slide-by-slide spec: title, visual description, key text (≤30 words), speaker notes, duration, act number. Ready to hand to a designer or pass to Kimi.
3. **`kimi-prompt.md`**: Complete prompt for [kimi.com](https://kimi.com) — includes design system, color palette, typography specs, full slide content, and screenshot placeholders. Copy-paste ready.
**1-idea-per-slide rule**: If a slide needs an "and" to describe it, split it.
**Review before moving on**:
- Timing check: total ≤ duration + 10% buffer
- Speaker notes read naturally out loud (test this)
- Kimi prompt has no `{PLACEHOLDER}` left unfilled
---
### Stage 6: Revision
**What it does**: Produces revision sheets for during and after the talk — quick navigation by act, master concept table, Q&A cheat-sheet, glossary.
| | |
|--|--|
| **Input** | `pitch.md` + `slides.md` + `concepts.md` |
| **Output** | `{slug}-revision-sheets.md` |
| **Tools used** | Read, Write |
| **Mode** | REX + Concept |
**What's in the revision sheets**:
- **Navigation** with anchor links by act
- **Per-act breakdown**: key concepts + metrics + anecdotes + probable Q&A
- **Master table**: concept → 1-2 sentence definition → URL to share
- **Q&A cheat-sheet**: 6-10 probable questions with short answers (≤20 sec to say)
- **Metrics block**: all numbers in one place
- **External resources**: links mentioned in the talk
- **Glossary**: technical terms, max 10 words each
**Purpose**: Someone asks a question → find the section → share the URL in 5 seconds.
---
## The Kimi Handoff
Stage 5 generates `{slug}-kimi-prompt.md` — a complete prompt for [kimi.com](https://kimi.com).
**What to do with it**:
1. Open the generated file
2. Verify no `{PLACEHOLDER}` remains (search the file)
3. Go to [kimi.com](https://kimi.com) — free account, no API needed
4. Start a new conversation
5. Copy-paste the entire prompt
6. Kimi generates the presentation (PowerPoint or PDF)
**Iterating with Kimi**:
- After the first generation, review slides against your `slides.md` spec
- Add follow-up messages for individual adjustments: "Slide 7: make the number larger, remove the bullet list"
- For screenshots: replace `SCREENSHOT AREA` placeholders manually after export
**The design system** embedded in the template:
- Dark theme (#0a0a0a background)
- Orange accent (#f97316) for key numbers and CTAs
- Inter/SF Pro typography
- Max 30 words per slide, numbers as heroes
- WCAG AA contrast ratio (projector-safe)
**Why Kimi?** At the time of writing, Kimi produces higher-quality conference presentations from detailed prompts than most alternatives. The template is Kimi-tuned but the design system and slide structure work with any AI presentation tool.
---
## Human-in-the-Loop Checkpoints
The pipeline has two human checkpoints:
### Checkpoint 1: Stage 1 metadata collection
If talk metadata (slug, event, date, duration, audience, mode) isn't provided upfront, Stage 1 uses `AskUserQuestion` to collect them before proceeding. This avoids generating a summary you'd discard.
### Checkpoint 2: Stage 4 — Angle + Title selection (mandatory)
This is the pipeline's critical gate. Stage 5 cannot start without an explicit human choice.
**Why this matters**: The angle and title determine everything that follows — the 5-act structure, which concepts surface, the Kimi prompt tone. An automated choice here would produce a generic talk. This is the one decision that must be yours.
**What to do at the checkpoint**:
1. Read `angles.md` — don't skip it, the recommendation may be wrong for your context
2. Optionally send `feedback-draft.md` to a trusted peer (takes 10 minutes, saves 2 hours of rework)
3. Reply with your choice (can be the recommendation, a modification, or something entirely different)
---
## Adapting the Pipeline
### Lightning talk (10-15 min)
- Keep Stages 1, 3, 4, 5 — skip Stage 2 even in REX mode
- In Stage 3: limit to 8-10 concepts (filter ruthlessly to HIGH only)
- In Stage 4: generate 2 angles maximum
- In Stage 5: target ~8-10 slides, ~2 min/slide
- Skip Stage 6 (not needed for short format)
### 45-minute talk
- Full pipeline, all stages
- In Stage 3: target 25-35 concepts (gives you enough to fill 5 solid acts)
- In Stage 5: 20-25 slides, allow 3 min/slide average
- Stage 6 becomes critical (Q&A lasts 10-15 min)
### Workshop (90+ min)
- Run the pipeline up to Stage 4
- In Stage 5: replace slides.md with an activities spec (exercises, timing, breakout groups)
- The Kimi prompt section becomes optional (less relevant for workshop materials)
### No git repo available (REX without code)
- Use `--rex` mode if you have metrics from other sources (analytics, dashboards, incident reports)
- In Stage 2: replace git commands with manual data collection from those sources
- Be stricter about sourcing — "unverified" metrics don't survive the talk
---
## Real-World Example
**Talk**: "Dev with AI" REX — How we shipped a complex project in 7 months with AI tooling
**Mode**: REX
**Event**: DevWithAI Lyon, February 2026
**Duration**: 30 minutes
**Source material**: 12,000-word article in `.mdx`
**Files generated (16 total)**:
```
talks/2026-devwithai-summary.md (Stage 1)
talks/2026-devwithai-git-archaeology.md (Stage 2)
talks/2026-devwithai-changelog-analysis.md (Stage 2)
talks/2026-devwithai-timeline.md (Stage 2)
talks/2026-devwithai-concepts.md (Stage 3)
talks/2026-devwithai-concepts-enriched.md (Stage 3)
talks/2026-devwithai-angles.md (Stage 4)
talks/2026-devwithai-titre.md (Stage 4)
talks/2026-devwithai-descriptions.md (Stage 4)
talks/2026-devwithai-feedback-draft.md (Stage 4)
talks/2026-devwithai-pitch.md (Stage 5)
talks/2026-devwithai-slides.md (Stage 5)
talks/2026-devwithai-kimi-prompt.md (Stage 5)
talks/2026-devwithai-revision-sheets.md (Stage 6)
```
**Key metrics surfaced by Stage 2**:
- 1,200 commits over 7 months (verified by `git log`)
- 3 main contributors
- 97% traffic reduction after a specific migration (sourced from CHANGELOG v1.1.0)
- Velocity peak in month 4 (2x normal pace)
**Angle chosen** (from 3 generated): "The builder's journey" — REX angle showing what it's actually like to build with AI tooling over months, not a feature demo
**Kimi output**: Dark-theme deck, 20 slides, numbers-as-heroes design, generated in ~90 seconds
---
## Common Pitfalls
### Metrics without sources
Stage 1 extracts metrics but doesn't verify them. Stage 2 verifies. If you're in Concept mode, any metric you mention in the talk must be sourced explicitly in your summary — or removed. Audiences ask "where did that number come from?" and "I looked it up" is not an answer.
### Overloaded slides
The Kimi prompt enforces 30 words per slide, but the pitch.md you write in Stage 5 may drift toward bullet lists. Test the 1-idea-per-slide rule: if you need "and" to describe the slide's content, split it.
### Skipping the CHECKPOINT
Running Stage 5 without a validated angle + title produces a technically correct script for the wrong talk. Stage 4's recommendation is a good starting point, not a final answer — your audience knowledge matters.
### Sending the feedback draft too late
The feedback draft is generated in Stage 4, before the script exists. That's intentional — peer feedback at the angle/title stage is actionable. Feedback on a finished script mostly generates regret.
### Generic speaker notes
Speaker notes in `pitch.md` should read as natural speech. If you catch yourself writing "in this slide, we discuss...", rewrite it as what you'd actually say to the room. The Kimi prompt copies these notes — they need to be conversational.
---
## Design Patterns Showcased
This pipeline is interesting from a Claude Code perspective because it demonstrates several advanced patterns in one coherent system.
### Skill chaining with file-based state
Each stage writes files that the next stage reads. State persists between skill invocations through the filesystem — no in-memory coupling. You can run Stage 3 a week after Stage 2 without losing context.
```
Stage 1 → writes {slug}-summary.md
Stage 2 → reads {slug}-summary.md → writes 3 new files
Stage 3 → reads summary + timeline → writes 2 new files
...
```
### Tool permission scoping
Stage 2 is the only stage that needs Bash (for git commands). Every other stage is Read + Write only. This is intentional — the minimal footprint for each stage means less surface for mistakes.
```yaml
# Stage 2 only
allowed-tools:
- Write
- Read
- Bash
```
### Human-in-the-loop gates
Stage 4 uses `AskUserQuestion` to surface the CHECKPOINT — not as a convenience, but as a structural requirement. The skill won't proceed to Stage 5 without an explicit human response. This is the pattern for "Claude proposes, human decides."
### AI-to-AI handoff
Stage 5 generates a prompt for a second AI system (Kimi). Claude doesn't generate slides directly — it generates the specification that another AI executes. This pattern lets you combine strengths: Claude for structured narrative reasoning, Kimi for visual presentation generation.
```
Claude (Stage 5) → kimi-prompt.md → Kimi.com → slides.pptx
```
### Two execution modes with conditional stage skip
The `--rex` / `--concept` flag controls which stages run. Stage 2 skips automatically in Concept mode. The orchestrator (`/talk-pipeline`) handles routing — individual stage skills are mode-agnostic.
---
## See Also
- **Skill templates**: [`examples/skills/talk-pipeline/`](../../examples/skills/talk-pipeline/)
- **PDF Generation workflow**: [`guide/workflows/pdf-generation.md`](./pdf-generation.md) — for generating handouts from the talk content
- **Spec-First workflow**: [`guide/workflows/spec-first.md`](./spec-first.md) — complementary pattern for structured work with Claude
- **Skill structure reference**: [`examples/skills/skill-creator/SKILL.md`](../../examples/skills/skill-creator/SKILL.md)
---
**Last updated**: February 2026

19
machine-readable/reference.yaml
View file

@ -95,6 +95,23 @@ deep_dive:
# PDF Generation
pdf_generation: "guide/workflows/pdf-generation.md"
pdf_generator_skill: "examples/skills/pdf-generator.md"
# Talk Preparation Pipeline (6-stage: extract → research → concepts → position → script → revision)
talk_pipeline_workflow: "guide/workflows/talk-pipeline.md"
talk_pipeline_skills: "examples/skills/talk-pipeline/"
talk_pipeline_orchestrator: "examples/skills/talk-pipeline/orchestrator/SKILL.md"
talk_pipeline_stage1: "examples/skills/talk-pipeline/stage-1-extract/SKILL.md"
talk_pipeline_stage2: "examples/skills/talk-pipeline/stage-2-research/SKILL.md"
talk_pipeline_stage3: "examples/skills/talk-pipeline/stage-3-concepts/SKILL.md"
talk_pipeline_stage4: "examples/skills/talk-pipeline/stage-4-position/SKILL.md"
talk_pipeline_stage5: "examples/skills/talk-pipeline/stage-5-script/SKILL.md"
talk_pipeline_stage6: "examples/skills/talk-pipeline/stage-6-revision/SKILL.md"
talk_pipeline_kimi_template: "examples/skills/talk-pipeline/stage-5-script/templates/kimi-prompt-template.md"
talk_pipeline_feedback_template: "examples/skills/talk-pipeline/stage-4-position/templates/feedback-draft.md"
talk_pipeline_modes: "REX (git archaeology) | Concept (skip stage 2)"
talk_pipeline_outputs: "13-14 files REX mode, 10 files Concept mode"
talk_pipeline_patterns: "skill chaining + file-based state + tool permission scoping + human-in-the-loop gate + AI-to-AI handoff (Claude → Kimi)"
talk_pipeline_checkpoint: "Stage 4 CHECKPOINT: user selects angle + title before script starts"
talk_pipeline_kimi: "kimi.com (free) — copy-paste Stage 5 prompt for AI slide generation"
# Whitepapers (FR + EN) — 9 focused whitepapers on Claude Code
whitepapers_url: "https://www.florian.bruniaux.com/guides"
whitepapers_fr: "whitepapers/fr/" # FR sources (Quarto .qmd)
@ -470,7 +487,7 @@ deep_dive:
gsd_note: "Overlap with existing patterns (Ralph Loop, Gas Town, BMAD)"
# Resource Evaluations (added 2026-01-26, updated 2026-02-07)
resource_evaluations_directory: "docs/resource-evaluations/"
resource_evaluations_count: 74
resource_evaluations_count: 83
resource_evaluations_methodology: "docs/resource-evaluations/README.md"
resource_evaluations_watchlist: "docs/resource-evaluations/watch-list.md"
resource_evaluations_appendix: "guide/ultimate-guide.md:15034"