slides (v1)

Quick Reference

CRITICAL, Before starting, MUST read ../lark-shared/SKILL.md with the Read tool. Authentication, permissions, and global parameters are all based on lark-shared.

CRITICAL, Before generating any XML, MUST read xml-schema-quick-ref.md with the Read tool. Guessing XML structure from memory is prohibited.

CRITICAL, When creating a new presentation or performing a major page rewrite, MUST generate .lark-slides/plan/<deck-or-task-id>/slide_plan.json before generating XML. Create the corresponding directory first. See planning-layer.md for planning layer rules and intermediate artifact lifecycles. Small edits to existing pages, such as replacing a single title or inserting a block, are exempt.

CRITICAL, When creating a new presentation or performing a major page rewrite, MUST read visual-planning.md before generating XML to ensure layout_type, visual_focus, and text_density actually change the page geometry, main visual, and text volume.

CRITICAL, When creating a new presentation or performing a major page rewrite, planning asset_need MUST follow asset-planning.md: perform metadata planning only, must include fallback_if_missing, and must not require real searching, downloading, or uploading of assets.

CRITICAL, After creation or major rewrite, MUST perform explicit validation according to validation-checklist.md: read full-text XML, verify page count and key elements, check for blank/broken pages, obvious overflow, and layout risks; use scripts/xml_text_overlap_lint.py for XML syntax and text overlap static checks.

CRITICAL, When self-checking before creation or troubleshooting failures, MUST check XML escaping, structure, shell truncation, image tokens, 3350001, and layout risks according to troubleshooting.md.

CRITICAL, If the user mentions "template", "apply template", "reference a certain theme/style/layout", or if the user request clearly falls within existing scenario templates (e.g., work reports, product introductions, business plans, training, promotion reports, etc.), MUST first perform template search using search in scripts/template_tool.py; provide 2-3 best-matching template candidates for the user to choose from by default. After locking in a template, use summarize to obtain theme and layout summaries; only use extract to crop target page-type XML when a layout skeleton is needed. Do not read the full template XML directly.

[!NOTE] scripts/template_tool.py requires Python 3. references/template-index.json is a script cache/lightweight routing index, not a document for the agent to read by default; assets/templates/*.xml are machine resources and should only be summarized or cropped via scripts, not read in full.

CRITICAL, When using templates to generate or rewrite pages, MUST summarize the target page type first; only extract when a specific layout skeleton is needed.

Editing existing slide pages: Prioritize using +replace-slide (block-level replacement/insertion, do not move page order); see lark-slides-edit-workflows.md for action selection and the full read-modify-write process.

Identity Selection

Feishu slides are usually the user's own content resources. By default, you should prioritize explicitly using --as user (user identity) to perform slides-related operations, and always specify the identity explicitly.

• --as user (Recommended): Create, read, and manage presentations as the currently logged-in user. Complete user authorization before execution:

lark-cli auth login --domain slides

• --as bot: Use only when the user explicitly requests operations as the application identity, or when the bot needs to hold/create resources. When using bot identity, confirm whether the bot actually has access to the target presentation.

Execution Rules:

1. Creating, reading, adding/deleting slides, and continuing to edit existing PPTs via user-provided links should all default to --as user.
2. If permission is insufficient, check if the bot identity was used by mistake; do not default to falling back to the bot.
3. Only switch to --as bot if the user explicitly requests "operate as application identity / bot identity", or if the current workflow involves the bot creating resources and then performing collaboration authorization.

Pre-execution Requirements

Important: references/slides_xml_schema_definition.xml is the only correct source of XML protocol for this skill; other md files are only summaries of it and the CLI schema.

High-frequency read-only:

• xml-schema-quick-ref.md
• planning-layer.md (New creation / Major rewrite)
• visual-planning.md (New creation / Major rewrite)
• asset-planning.md (New creation / Major rewrite)
• validation-checklist.md (After creation / Major rewrite)

Read on demand:

• Creation: lark-slides-create.md
• Editing: lark-slides-edit-workflows.md, lark-slides-replace-slide.md
• Images: lark-slides-media-upload.md
• Flowcharts / Sequence diagrams / Architecture diagrams / Decorative patterns: lark-slides-whiteboard.md
• Icons: iconpark.md, scripts/iconpark_tool.py
• Templates: template-catalog.md, scripts/template_tool.py
• Troubleshooting: troubleshooting.md
• Full protocol: slides_xml_schema_definition.xml

Workflow

This is a presentation, not a document. Each slide is an independent visual scene; information density should be low, and layout should include whitespace.

Design Ideas

Do not generate slides without a sense of design. A plain white background + title + bullets can only serve as a minimalist temporary draft and cannot be used as a formal delivery.

Before writing XML, determine the deck-level visual strategy in slide_plan.json:

• Thematic Color Palette: The color scheme must serve the theme, industry, and audience; do not default to blue business style. If the same set of colors works for another completely different theme, the color scheme is not specific enough.
• Primary/Secondary Ratio: Choose 1 primary color to carry about 60-70% of the visual weight, 1-2 secondary colors for structure and partitioning, and 1 accent color used only for key numbers, conclusions, or action points. Do not give all colors the same weight.
• Background Consistency: Determine the background strategy for the entire deck first; default to maintaining the same light/dark tone and base color system. Only section breaks, transitions, or highlight pages should intentionally change the background, and changes must be made to look like they belong to the same design set through the same primary colors, textures, sidebars, or motifs. Regardless of light or dark, ensure sufficient contrast for body text, icons, and lines.
• Unified Motif: Choose a reusable visual motif to run through the entire document, such as thick sidebars, circular icon bases, semi-bleed image areas, numbered nodes, color blocks in the top-left corner of cards, or large numbers. Do not change the decorative language on every page.

Each page must have at least one visual element: image, icon, chart, table, process, comparison structure, large number, schematic, or abstract visual composed of shapes. Text boxes themselves do not count as main visuals.

Prioritize these page forms:

• Two-column structure: Text on left/image on right or image on left/text on right, with the visual area occupying 35-45% of the width.
• Icon rows: Icons on color blocks or circular bases, with short titles and a one-sentence explanation on the right.
• 2x2 / 2x3 grid: Suitable for capabilities, modules, risks, action items; keep content in each cell at the same level.
• Semi-bleed visuals: Images or abstract shapes occupy the left/right half of the screen, with text overlaid or arranged along the edge.
• Large number cards: Use 60-72pt numbers for key metrics, accompanied by 10-14pt labels below.
• Comparison columns: Use side-by-side layout for before/after, plan A/B, problem/solution, with titles and baselines strictly aligned.
• Timeline/Flowchart: Express steps using nodes and arrows; the flow direction must be visible at a glance.

Font and spacing suggestions:

• Titles 36-44pt, key conclusions can be larger; body text 14-18pt; notes 10-12pt.
• Body text defaults to left-aligned; use center-aligned only for covers, endings, or large number scenarios.
• Page margins at least 40px; maintain 24-40px spacing between content blocks, and keep it consistent within the same deck.
• Card padding must provide real space; do not let text touch the edges; consider text box padding when aligning shapes and text.

Common mistakes to avoid:

• Do not reuse the same title + three bullets layout for all pages.
• Do not use low-contrast text or low-contrast icons, such as light gray text on a light background.
• Do not let decorative lines cross through text, or let footers, sources, or numbering crowd the main content.
• Do not represent missing assets as blank image boxes; must generate XML-native visuals according to fallback_if_missing.
• Do not leave template placeholder text, example company names, example dates, or original template content unrelated to the user's theme.

Creation Method Selection

[!WARNING] The risk of --slides '[...]' lies mainly in shell parameter passing, not just the number of pages. Even if there is only 1 page, if the XML is complex enough, the two-step creation method is recommended.

[!IMPORTANT] slides +create --slides creates pages one by one at the underlying level; it is not an atomic operation. If it fails midway, record the xml_presentation_id, read back to confirm the current status, and then continue to fix or append.

Template and Script Priority Workflow

See template-catalog.md for template details. Remember the main workflow: search first, summarize after locking in, and extract only when a skeleton is needed; do not read full template XML directly or copy placeholder text.

python3 skills/lark-slides/scripts/template_tool.py search --query "<User request original text>" --limit 3
python3 skills/lark-slides/scripts/template_tool.py summarize --template <template-id> --label <Cover|Table of Contents|Section|Content|Ending>
python3 skills/lark-slides/scripts/template_tool.py extract --template <template-id> --label <Page type> --out /tmp/template-slice.xml

Step 1: Requirement clarification & Read knowledge
  - Clarify theme, audience, page count, style; handle template requirements according to "Template and Script Priority Workflow"
  - Read xml-schema-quick-ref.md; also read planning-layer.md, visual-planning.md, asset-planning.md for new creation / major rewrite

Step 2: Generate outline → User confirmation → Write slide_plan.json
  - Generate structured outline for user confirmation; if using a template, indicate which template it is based on
  - New creation / major rewrite must first create directory and write to `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`
  - Execute plan fields, path naming, template boundaries, and `asset_need` structure according to planning-layer.md / asset-planning.md

Step 3: Generate XML according to slide_plan.json → Create
  - Consume plan page by page: key_message determines main conclusion, layout_type determines geometry, visual_focus determines main visual, text_density determines text volume
  - When real assets are missing, must use `fallback_if_missing` to generate XML-native fallback visuals; do not leave blank
  - Determine creation method according to "Creation Method Selection"; handle images, complex XML, escaping, and 3350001 troubleshooting according to lark-slides-create.md, media-upload.md, troubleshooting.md

Step 4: Review & Delivery
  - After creation, must use xml_presentations.get to read full-text XML and perform explicit validation according to validation-checklist.md, including XML text overlap check
  - Handle failures or partial successes according to troubleshooting.md; prioritize fixing local issues with `+replace-slide`
  - If no issues → Delivery: Inform the user of the presentation ID and access method

jq Command Template (Use when editing existing PPT)

+create --slides is recommended for new PPTs. The following jq template is suitable for scenarios where pages are appended to an existing presentation, which can avoid manual escaping of double quotes:

# Append to the end
lark-cli slides xml_presentation.slide create \
  --as user \
  --params '{"xml_presentation_id":"YOUR_ID"}' \
  --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
  <style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
  <data>
    Place shape, line, table, chart, whiteboard, etc. elements here
  </data>
</slide>' '{slide:{content:$content}}')"

# Insert before a specific page: before_slide_id must be in the --data body, at the same level as slide
# ⚠️ Do not write before_slide_id into --params, CLI will silently send it as an unknown query parameter, the server will ignore it, and the new page will go to the end
lark-cli slides xml_presentation.slide create \
  --as user \
  --params '{"xml_presentation_id":"YOUR_ID"}' \
  --data "$(jq -n --arg content '<slide ...>...</slide>' --arg before 'TARGET_SLIDE_ID' \
    '{slide:{content:$content}, before_slide_id:$before}')"

Gradients must use rgba() format with percentage stops, such as linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%). Using rgb() or omitting stops will cause the server to fall back to white.

Outline Template

Use the following format when generating an outline for user confirmation:

[PPT Title], [Positioning description], for [Target audience]

Template: [No template used / <category>/<template>.xml (Reason for recommendation)]

Page structure (N pages):
1. Cover page: [Title text]
2. [Page theme]: [Point 1], [Point 2], [Point 3]
3. [Page theme]: [Page description]
...
N. Ending page: [Ending text]

Style: [Color scheme], [Layout style]

Core Concepts

URL Format and Tokens

+replace-slide and +media-upload shortcuts automatically parse the above two types of URLs; when calling native APIs directly, you still need to parse wiki links manually.

Special Handling for Wiki Links (Critical!)

Knowledge base links (/wiki/TOKEN) cannot be used directly as xml_presentation_id. Before calling native APIs directly, query the wiki node first, confirm node.obj_type == "slides", and then use node.obj_token as the real presentation ID.

lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}'

Shortcuts +replace-slide and +media-upload automatically parse /wiki/ URLs; you only need to perform this step yourself when manually calling xml_presentations.* / xml_presentation.slide.*.

Resource Relationships

Wiki Space
└── Wiki Node (Knowledge base node, obj_type: slides)
    └── obj_token → xml_presentation_id

Slides (Presentation)
├── xml_presentation_id (Unique presentation identifier)
├── revision_id (Version number)
└── Slide (Slide page)
    └── slide_id (Unique page identifier)

Shortcuts and APIs

Shortcuts are high-level wrappers for common operations (lark-cli slides +<verb> [flags]). Prioritize using operations that have shortcuts.

Use native APIs when no shortcut covers the requirement. High-frequency resources: xml_presentations.get to read full text; xml_presentation.slide.create/delete/get/replace to manage single pages.

lark-cli schema slides.<resource>.<method>   # Must check parameter structure before calling API
lark-cli slides <resource> <method> [flags] # Call API

Important: When using native APIs, you must run schema first to view the --data / --params parameter structure; do not guess field formats.

Core Rules

1. Plan before writing XML: When creating a new presentation or performing a major page rewrite, you must write to .lark-slides/plan/<deck-or-task-id>/slide_plan.json first; templates, styles, and outlines can only serve as planning input and cannot bypass the planning layer.
2. Creation process: Simple short XML (1-3 pages, simple structure, few special characters) can be created in one step with slides +create --slides '[...]'; for complex content, images, long Chinese text, nested quotes, many special characters, or more than 10 pages, default to creating a blank PPT with slides +create first, then add page by page using xml_presentation.slide.create.
3. Direct children of <slide> are only <style>, <data>, <note>: Text and graphics must be placed inside <data>.
4. Text is expressed via <content>: Must use <content><p>...</p></content>; text cannot be written directly inside a shape.
5. Save key IDs: Subsequent operations require xml_presentation_id, slide_id, and revision_id.
6. Delete with caution: Deletion is irreversible, and at least one slide must remain.
7. Prioritize block-level replacement for editing existing pages: Modify single shapes/images using +replace-slide (block_replace / block_insert); do not rebuild the entire page. Only use slide.delete + slide.create when the entire page structure needs to be replaced.
8. <img src> can only use file_token uploaded to Feishu Drive; http(s) external links are prohibited: The Feishu slides rendering engine does not proxy external images; external src usually does not display or shows a broken image in PPT. The process must be: "Save image locally → Upload using slides +media-upload or @./path placeholder for +create --slides → Write file_token into <img src>". If the user provides a web image link, curl/download it to CWD first before proceeding with the upload process; do not put the external URL directly into src. Images max 20 MB (slides upload API does not support chunked upload).

Note: If the md content is inconsistent with slides_xml_schema_definition.xml or the output of lark-cli schema slides.<resource>.<method>, the latter two take precedence.