feat(slides): document full-TOML custom style authoring#72
Open
ymote wants to merge 1 commit into
Open
Conversation
The mofa-cli binary already supports workspace-authored style TOMLs —
`src/main.rs:537-540` probes `<cwd>/styles/<name>.toml` before built-ins,
and the host's pre-flight validator (octos PR #1323) additionally probes
`<work_dir.parent()>/styles/` so styles authored at the workspace root
resolve correctly when the plugin's cwd is `<workspace>/skill-output`.
But the SKILL.md only documented `Custom styles (inline)` — a per-slide
prompt override that requires no file. Agents had no doc telling them
the binary picks up workspace TOMLs by name, so when a user asked for a
named-but-uninstalled style ("puer-woodcut"), the agent skipped the
authoring step and called `mofa_slides style=puer-woodcut` directly —
producing a "style not found" error.
Adds `## Custom styles (full TOML)` between the existing inline section
and `## Built-in Styles`. Covers: when to pick inline vs full TOML, the
canonical save path (`<workspace>/styles/<name>.toml`, NOT the
skill-output subdirectory), a minimum TOML schema with one annotated
example derived from `nb-pro.toml`, the three-step workflow, and the
three most common "style not found" causes (wrong directory, filename
stem mismatch, separator/`.toml` suffix in the `style` arg).
Bumps manifest + SKILL.md frontmatter to v0.6.1. Doc-only, no behavior
change.
Together with octos PR #1323 (pre-flight validator catches missing styles
in the foreground turn so the LLM sees a [VALIDATION FAILED] tool_result
instead of a synth-ack) and #1324 (post-spawn failure feedback), this
closes the loop: the agent now knows how to author the file, the
validator catches the case where it didn't, and the failure path
surfaces back to the LLM with the same SKILL.md pointer.
6 tasks
ymote
added a commit
that referenced
this pull request
May 27, 2026
…ee (PR-D2) (#79) * feat(mofa-slides): migrate 670→51 line SKILL.md to discovery+docs/ tree (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). * fix(mofa-slides): convert discovery.hints from string array to object 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Custom styles (inline)— per-slide prompt overrides. The mofa-cli binary already supports workspace-authored style TOMLs (mofa-cli/src/main.rs:537-540probes<cwd>/styles/<name>.tomlbefore built-ins), but no doc told the agent that. Real-world failure: user asked for "puer-woodcut" → agent invented the name and calledmofa_slides style=puer-woodcutdirectly → "style not found".## Custom styles (full TOML)section between the existing inline section and## Built-in Styles. Covers when to pick inline vs full TOML, the canonical save path (<workspace>/styles/<name>.toml, NOT the skill-output subdirectory), a minimum TOML schema with one annotated example derived fromnb-pro.toml, three-step workflow, and the three most common "style not found" causes.manifest.json+ SKILL.md frontmatter to v0.6.1. Doc-only, no behavior change.Companion work
This completes the agent-feedback loop for custom-style authoring:
style=<missing>in the foreground turn so the LLM sees[VALIDATION FAILED] …instead of a synth-ack. Probes<skill_dir>/styles/,<work_dir>/styles/, AND<work_dir.parent()>/styles/when the work_dir basename isskill-output— which is why authoring at<workspace>/styles/<name>.toml(workspace root) resolves correctly even though plugin cwd is bound to<workspace>/skill-output.success:falseafter a spawn_only synth-ack, the failure now surfaces back to the LLM as a tool_result.With those two on the host side and this PR on the skill side, the agent now (a) knows to author the file at the right path, (b) gets a validator catch in the foreground turn if it skipped that step, and (c) sees background failures with the same SKILL.md pointer.
Verified
mofa-cli/src/main.rs:537-540that the binary checks<cwd>/styles/<style>.tomlbefore built-ins. Plugin cwd =<workspace>/skill-output, so<workspace>/skill-output/styles/<name>.tomlalso resolves — but the doc-canonical path is the workspace root because the octos host's rewriter probes that location first.octos/crates/octos-agent/src/plugins/tool.rs:1813that the pre-flightparent_probematches the path described in the new SKILL.md section.mofa-slides/styles/nb-pro.toml—[meta](name/display_name/description/category/tags) +[variants](default = "<tag>") + one or more[variants.<tag>]tables with apromptfield.Test plan
<workspace>/styles/puer-woodcut.tomlfirst, then callmofa_slides style=puer-woodcut.<workspace>/skill-output/styles/...by mistake, the failure-mode bullet in the new section steers it to move the file up one directory.