Skip to content

feat(mofa-slides): migrate 670→51 line SKILL.md to discovery+docs/ tree (PR-D2)#79

Merged
ymote merged 2 commits into
mainfrom
feat/d2-mofa-slides-discovery
May 27, 2026
Merged

feat(mofa-slides): migrate 670→51 line SKILL.md to discovery+docs/ tree (PR-D2)#79
ymote merged 2 commits into
mainfrom
feat/d2-mofa-slides-discovery

Conversation

@ymote

@ymote ymote commented May 27, 2026

Copy link
Copy Markdown
Collaborator

Context

mofa-slides is the largest skill on the fleet — its 670-line SKILL.md is the bulk of every fleet turn's standing token cost. This PR ports it to the discovery+docs/ tree model so the LLM reads reference content on-demand via manifest hints instead of paying for it up front on every turn.

Prerequisites (octos): PR-A #1327, PR-B #1333, PR-C #1339, PR-D1 #1340.

This is the single biggest token-cost recovery in the fleet — ~11K tokens/turn savings post-PR-E once the host stops auto-injecting SKILL.md by default (skill_md_auto_inject: false).

Before / after

Before After
SKILL.md 670 lines 51 lines
Reference docs 5 files under docs/
Manifest no discovery discovery.summary + 8 hints
skill_md_auto_inject (implicit true) false
Version 0.6.1 (head was 0.6.0) 0.7.0

Load-bearing anti-patterns preserved in the trimmed SKILL.md

The full 51-line SKILL.md keeps only what cannot be inferred from tool descriptions:

  • Output-path rebind rules (skill-output/ auto-prefix; no /tmp/).
  • Workspace-contract truth (check_background_tasks + check_workspace_contract are authoritative — not chat history).
  • Interactive flow one-liner.
  • The four load-bearing anti-patterns:
    1. Do NOT memorize the style catalog — call mofa_list_styles. The binary errors out (no silent fallback) on unknown names.
    2. Language match end-to-end. Chinese deck → Chinese VQA + Chinese narratives + Chinese quoted text. No mixing. Highest-impact rule for Chinese decks. The runtime no longer auto-appends an English clamp.
    3. Mode 2 (clean bg + manual texts) is the default for "editable PPT" — NOT Mode 3 (auto_layout VQA). Mode 3 is slow, expensive, needs human cleanup.
    4. Every deck is its own self-contained script with a per-deck const VQA block at the top, spliced into every slides[i].prompt via ${VQA}. Write script.js to disk first; invoke with input: "<path>".
  • Pointer to docs/ + the manifest's discovery.hints.

Migrated content → mofa-slides/docs/*.md

5 new self-contained docs, each readable in isolation:

  • docs/modes.md — Mode 1/2/3/4 decision tree, when NOT to use auto_layout, costs of enabling it, anti-leak rules, full 4-phase pipeline description.
  • docs/cc-ppt-authoring.md — Required deck-script structure (top constants, const VQA, module.exports), mandatory rules, full Chinese + English minimal worked examples.
  • docs/custom-styles.md — Inline prompt overrides AND full-TOML custom style authoring (PR feat(slides): document full-TOML custom style authoring #72 content: workspace save path, TOML schema, workflow, the three "style not found" failure modes).
  • docs/worked-examples.md — Full 5-slide editable business deck (Mode 2 with texts, runs, fill, margin, lineSpacing), Mode 3 / Mode 4 / reference-image JSON shapes, slide-canvas layout reference (16:9, inch positions), complete TextOverlay + TextRun schemas.
  • docs/style-prompts.md — Inline style-prompt quick-reference table (14 vibes: Art Deco, Bauhaus, Glassmorphism, 国潮, 水墨, 敦煌, 青花瓷, …), built-in style category cheatsheet (verify with mofa_list_styles), API modes, timing/timeout budget, CLI flags, config, OOXML + pptx-scripts/ utilities for editing existing decks.

Discovery hints (8 / 8 max, one per concern)

Each hint names a trigger condition + the doc to read:

  1. Before picking a style → call mofa_list_styles (never recite).
  2. Choosing Mode 1/2/3/4 → docs/modes.md.
  3. Authoring a deck (cc-ppt structure) → docs/cc-ppt-authoring.md.
  4. Inline overrides + full-TOML custom styles → docs/custom-styles.md.
  5. Long worked examples + layout reference + schemas → docs/worked-examples.md.
  6. Style-prompt snippets, API modes, CLI, PPTX-editing → docs/style-prompts.md.
  7. Always invoke via input: "<path>" with ${VQA} spliced (not inline slides:).
  8. Language match (Chinese stays Chinese; English clamp removed).

Untouched

  • Tool descriptions in manifest.json (mofa_list_styles, mofa_slides) — identical.
  • mofa-slides/styles/ (20 TOML files) — untouched.
  • mofa-slides/pptx-scripts/ — untouched.
  • mofa-slides/ooxml/ — untouched.
  • mofa-slides/USER_GUIDE.md and the pre-existing docs/00-SKILL-完整制作指南.md — unchanged.

Test plan

  • manifest.json parses as valid JSON.
  • SKILL.md is 51 lines (≤ 80 cap).
  • All 5 paths referenced by discovery.hints exist under mofa-slides/docs/.
  • All 4 load-bearing anti-patterns are present verbatim in the trimmed SKILL.md.
  • styles/, pptx-scripts/, ooxml/ subdirs untouched.
  • Fleet soak (post-merge + PR-E in octos): verify slides authoring still works end-to-end on Chinese + English decks with the LLM reading docs/ on demand.

ymote added 2 commits May 27, 2026 10:31
…ee (PR-D2)

mofa-slides is the largest skill on the fleet — its 670-line SKILL.md is
the bulk of the standing token cost on every turn. This PR moves the
operational/reference content off SKILL.md and behind manifest
discovery hints the LLM reads on-demand.

Prerequisites (octos): PR-A #1327, PR-B #1333, PR-C #1339, PR-D1 #1340.

Trimmed SKILL.md (51 lines, was 670) keeps only what cannot be inferred
from tool descriptions:
- Output-path rebind rules (skill-output auto-prefix, no /tmp).
- Workspace-contract truth (check_background_tasks +
  check_workspace_contract are authoritative; not chat history).
- Interactive flow one-liner.
- The four load-bearing anti-patterns:
  1. Do NOT memorize the style catalog — call mofa_list_styles.
  2. Language match end-to-end (Chinese stays Chinese; the runtime no
     longer auto-appends an English clamp).
  3. Mode 2 (clean bg + manual texts) is default for "editable PPT" —
     NOT Mode 3 (auto_layout VQA).
  4. Every deck is a self-contained script with a per-deck const VQA at
     the top, spliced into every slide.prompt via ${VQA}.
- Pointer to docs/.

Migrated content → mofa-slides/docs/*.md (read on demand):
- modes.md          Mode 1/2/3/4 decision tree, when NOT to use
                    auto_layout, costs, anti-leak rules.
- cc-ppt-authoring.md  Required deck-script structure (top constants,
                    const VQA, module.exports), mandatory rules,
                    Chinese + English minimal worked examples.
- custom-styles.md  Inline prompt overrides AND full-TOML custom style
                    authoring (PR #72 content: save path, schema,
                    workflow, "style not found" failure modes).
- worked-examples.md  Full 5-slide editable business deck (texts,
                    runs, fill, margin, lineSpacing), Mode 3 / Mode 4
                    / reference-image shapes, slide-canvas layout
                    reference, TextOverlay + TextRun schemas.
- style-prompts.md  Inline style-prompt quick-reference table
                    (14 vibes), built-in style category cheatsheet
                    (verify with mofa_list_styles), API modes,
                    timing/timeout budget, CLI flags, config, OOXML +
                    pptx-scripts/ utilities for editing existing decks.

Manifest gets discovery: { summary, hints[] } with 8 hints (max),
plus skill_md_auto_inject: false so the host stops auto-injecting the
full SKILL.md and instead lets the LLM read docs/ on demand via the
hints. Tool descriptions are unchanged.

Combined with PR-A/B/C/D1 in octos, this is the single biggest
token-cost recovery in the fleet — ~11K tokens/turn savings post-PR-E
once the host stops shipping SKILL.md by default.

styles/, pptx-scripts/, and ooxml/ subdirs are untouched.

Version: 0.6.1 → 0.7.0 (major SKILL.md restructure).
… array

Codex review on octos schema flagged that PluginManifest expects each
discovery.hint to be { when, read?, list? } per PR-C, not a bare string.
Convert the 8 string hints to objects, mapping advisory-only hints
(style catalog, invocation contract, language match) at SKILL.md since
those rules live in the trimmed body, and the doc-specific hints at
their dedicated docs/*.md files.
@ymote ymote merged commit 0a5bef2 into main May 27, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant