Skip to content

nexu-io/open-design / plugins/community/humanize-ppt

humanize-ppt

Verified

A presentation system for agent-made PPTs — born for the talk, not just the template. It turns raw material into an AST (audience-state-transfer) outline with per-page visual-enhancement decisions (image / SVG diagram / video), hands a production brief to a downstream renderer (HTML-PPT skills or native PPTX), then runs a capped 3-round presentation checkup (演讲体检) on the rendered deck. It never renders slides itself. Use before generating PPT/HTML slides from raw material, and after rendering when the user says things like "给这份 deck 做演讲体检" or "PPT 渲染质检". If all you want is one beautiful template page with no outline and no checkup, a rendering skill alone is enough.

FileKindSize
LICENSEother219 B
SKILL.mdskill md15.6 KB
SPEC.mdmarkdown13.1 KB
adapters/guizang-bridge-notes.mdmarkdown153 B
adapters/ppt-master-bridge-notes.mdmarkdown3.3 KB
adapters/presenter-adapter-spec.mdmarkdown458 B
adapters/zara-bridge-notes.mdmarkdown175 B
contracts/asset-manifest.template.mdmarkdown75 B
contracts/ast-outline.schema.mdmarkdown211 B
contracts/deck-brief.template.mdmarkdown114 B
contracts/router-plan.schema.jsonconfig1.2 KB
contracts/run-manifest.schema.jsonconfig608 B
contracts/slide-plan.schema.jsonconfig4.4 KB
contracts/speaker-intent.template.mdmarkdown61 B
contracts/video-slots.schema.jsonconfig528 B
docs/index.mdmarkdown9.2 KB
docs/local-demo.mdmarkdown3.2 KB
examples/01-ai-tool-update/source.mdmarkdown940 B
open-design.jsonconfig1.6 KB
references/agent-teams-public-preview.mdmarkdown2.9 KB
references/beautiful-preview-first-adapter.mdmarkdown2.7 KB
references/guizang-material-qa.mdmarkdown5.2 KB
references/guizang-presenter-deploy.mdmarkdown1.9 KB
references/guizang-production-brief-orchestrator.mdmarkdown5.9 KB
references/humanize-ppt-public-writing.mdmarkdown2.5 KB
references/presenter-export-adapter.mdmarkdown2.5 KB
references/preview-outline-spec.mdmarkdown7.3 KB
references/qa-failure-modes.en.mdmarkdown18.7 KB
references/qa-failure-modes.mdmarkdown16.6 KB
references/renderer-guidance.mdmarkdown2.1 KB
references/renderer-verification.mdmarkdown2.9 KB
references/selected-template-full-deck-adapter.mdmarkdown2.5 KB
references/style-gallery-spec.mdmarkdown5.1 KB
references/workbuddy-team-packaging-and-video-materials.mdmarkdown5.2 KB
registry/renderer_registry.jsonconfig11.4 KB
scripts/humanize_ppt.pyscript349 B
scripts/humanize_ppt_v1.pyexecutablescript11.0 KB
scripts/humanize_ppt_v2.pyexecutablescript174.5 KB
scripts/humanize_ppt_v3.pyscript331 B
scripts/humanize_ppt_v4.pyscript350 B
scripts/humanize_ppt_v5.pyscript354 B
scripts/pptx_qa.pyscript14.9 KB
scripts/preview_outline_html.pyscript9.6 KB
scripts/smoke_check.pyscript11.4 KB

references/workbuddy-team-packaging-and-video-materials.md

View on GitHub
# WorkBuddy/CodeBuddy team packaging and PPT video-material pattern

Use this reference when preparing a Humanize PPT Agent Team for WorkBuddy/CodeBuddy upload or when adding HyperFrames/Remotion output to a PPT workflow.

## Upload package shape

A team upload zip should mirror the `trading-team` style plugin package, not a rendered HTML demo package.

Required root-level entries:

```text
.codebuddy-plugin/plugin.json
setting.json
agents/
rules/
skills/
```

Common optional entries:

```text
avatars/
README.md
.workbuddy-plugin/
settings.json
```

For stricter compatibility, prefer the clean minimal root:

```text
.codebuddy-plugin/
agents/
avatars/
rules/
setting.json
skills/
README.md
```

Do not deliver a zip whose root is mostly `index.html`, `assets/`, `screenshots/`, `source/`, or a rendered deck. That is a demo artifact, not an uploadable team plugin.

## Verification checklist

Before saying a WorkBuddy/CodeBuddy team package is upload-ready, do three checks in this order:

1. Compare the root tree against a known-good team-plugin example, such as `trading-team` style packages. The success criterion is structural compatibility, not visual/demo quality.
2. Inspect the zip root with `unzip -l` or Python. If the root looks like a rendered HTML demo (`index.html`, `assets/`, `screenshots/`, `source/`), stop and rebuild the package as a team plugin.
3. Validate every `plugin.json` reference resolves inside the zip, including agents, skills, and avatars.

Run these checks before saying the package is upload-ready:

```bash
python3 - <<'PY'
from pathlib import Path
import zipfile, json, sys
zp = Path('/path/to/team.zip')
with zipfile.ZipFile(zp) as z:
    names = set(z.namelist())
    roots = sorted(set(n.split('/')[0] for n in names if n))
    print('roots:', roots)

    required_files = ['.codebuddy-plugin/plugin.json', 'setting.json']
    required_dirs = ['agents/', 'rules/', 'skills/']
    missing_required = [p for p in required_files if p not in names]
    missing_required += [d for d in required_dirs if not any(n.startswith(d) for n in names)]

    demo_roots = {'index.html', 'assets', 'screenshots', 'source'}
    if demo_roots.intersection(roots) and not {'.codebuddy-plugin', 'agents', 'rules', 'skills'}.issubset(set(roots)):
        print('looks like rendered demo, not team plugin:', sorted(demo_roots.intersection(roots)))

    plugin = json.loads(z.read('.codebuddy-plugin/plugin.json')) if '.codebuddy-plugin/plugin.json' in names else {}
    missing_refs = []
    for a in plugin.get('agents', []):
        p = a[2:] if a.startswith('./') else a
        if p not in names:
            missing_refs.append(('agent', p))
    for s in plugin.get('skills', []):
        base = (s[2:] if s.startswith('./') else s).rstrip('/') + '/'
        if not any(n.startswith(base) for n in names):
            missing_refs.append(('skill_dir', base))
    for m in plugin.get('members', []):
        avatar = m.get('avatar')
        if avatar and avatar not in names:
            missing_refs.append(('avatar', avatar))
    team_avatar = plugin.get('avatar')
    if team_avatar and team_avatar not in names:
        missing_refs.append(('team_avatar', team_avatar))

    print('missing required:', missing_required or 'OK')
    print('missing refs:', missing_refs or 'OK')
    if missing_required or missing_refs:
        raise SystemExit(1)
PY
```

Also verify size and digest if the file will be shared:

```bash
ls -lh /path/to/team.zip
shasum -a 256 /path/to/team.zip
```

## Scenario rules file

`rules/<plugin-name>_rules.md` should include YAML frontmatter and a `<system_reminder>` block. It should state:

- available lead/member agents;
- bundled skills;
- SOP phases;
- routing rules;
- final delivery requirements;
- pitfalls and hard constraints.

For Humanize PPT teams, include the pitfall below explicitly.

## Video-material pitfall

Do not turn the deck into an empty page that only contains an embedded HyperFrames/Remotion video. That creates a player inside a PPT, not a presentation page.

Use HyperFrames and Remotion as material producers:

- `transition` — short motion bridge between slides or sections;
- `explainer` — 5-15s clip explaining a concept or process;
- `before_after` — visual comparison between raw model output and Humanize PPT output;
- `talking_material` — auxiliary video insert that supports a speaker moment;
- `social_preview` — shareable trailer/card for the deck;
- `fallback_still` — poster image for static/PDF/export contexts.

When a page feels empty, first diagnose the missing material type:

1. explanatory image;
2. flow/process diagram;
3. before/after comparison;
4. screenshot or evidence;
5. transition fragment;
6. short narration clip;
7. fallback still.

Only after this diagnosis choose the producer: GPT image, HyperFrames, Remotion, screenshot capture, or plain HTML/CSS layout.

## Packaging learned pattern

A robust Humanize PPT team package may include both `remotion-video-toolkit` and `hyperframes` in `.codebuddy-plugin/plugin.json` `skills`. The video/motion agent can own both, but its instructions should distinguish responsibilities:

- Remotion: structured explainer clips, timed narration, before/after video materials;
- HyperFrames: HTML motion graphics, transitions, social previews, captioned overlays, slide-to-video adapters.
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall