MAIC Importer Development Skill
Equips AI coding assistants with the architecture, debugging, and contribution rules for OpenMAIC's maic-importer PPTX-parsing package and its fidelity iteration loop.
The SKILL.md is a developer-spec document requiring no dangerous permissions or external side effects; bundled scripts only read/write local files. Deductions: prefetchTexmath in toPptxto.ts sends OMML data to an external /api/texmath endpoint (best-effort with fallback), a data flow not disclosed in SKILL.md; publisher identity unverified; no rollback/confirmation guidance.
Scripts referenced by the doc (transvert.ts, extract-pptx-structure.js) actually exist in the package; instructions are self-consistent. package. has a vitest script and repo CI (ci.yml) explicitly runs importer unit tests — auditable execution evidence justifying slightly above the static baseline. Deductions: test file contents not provided, error-feedback and edge-case coverage unverifiable statically, far from the 20 anchor.
This SKILL.md is in substance a developer specification for the importer package (fidelity iteration, bug-fix workflow, code conventions), not a semantically triggered end-user Agent Skill; invocation conditions and non-fit boundaries are only implicit. Credit: complete Chinese docs, explicit environment requirements. Deductions: weak trigger precision and capability-boundary declaration as an Agent Skill.
Layered docs (SKILL.md → DESIGN.md → README.md), layer red-lines, type protocol and high-risk file lists are thorough; MIT licensing and repository attribution are clear, honestly marking the pptxto fork with upstream license and acknowledgments retained. Deductions: no FAQ, changelog, or maintenance-ownership statement at skill level; some narrative confusion between upstream and fork versions in README.
The core task (guiding safe modification and debugging of the importer) is concrete and actionable with commands and a defect-location table; marginal value is clear. Deductions: 'restoration quality' claims cite a single test deck (test-0601-002) with no statically verifiable representative outputs, and README itself admits remaining styling gaps versus source files.
In-repo CI workflows, runnable debug scripts and a concrete test-case ID constitute auditable primary material. Deductions: key quality claims (iteration scores, OOXML pitfalls) cannot be independently reproduced statically, the test files themselves are absent, and cross-source corroboration is missing; even the static ceiling of 5 is not fully met.
- This SKILL.md is a developer specification, not an end-user Agent Skill; semantic triggering and general applicability are limited.
- The parse pipeline sends OMML formula data to an external /api/texmath endpoint (with fallback when unreachable); verify this egress fits your policy before use.
- README declares the package browser-only; importing in a pure Node process throws at load, and deployment depends on a postinstall-generated vendor artifact that will 404 if missing.
- Font whitelist and video codec detection are stubs: HEVC content can yield broken <video> elements and Chinese fonts are passed through unmodified.
- Fidelity claims rest on a single test deck; this static review executed no code, so actual results require independent verification.
What does this skill do, and when should you use it?
This is the development-specification skill for packages/@openmaic/importer inside the OpenMAIC repository, aimed at AI coding assistants contributing to that package. It mandates reading DESIGN.md first and prescribes the fidelity-iteration workflow, OOXML parsing pitfalls, the standard bug-fixing procedure, coding conventions, and strict layering rules. OpenMAIC is an MIT-licensed open-source multi-agent interactive classroom platform from a Tsinghua team; v0.3.0 published the @openmaic SDK family (DSL/renderer/importer) to npm. This skill is a contributor-facing engineering contract, not an end-user feature.
The skill is a set of instructions an AI assistant reads before working on the importer: it requires studying DESIGN.md and iterate-prompt.md up front; defines the fidelity iteration loop (pull low scores from comparison_run, cluster, write iteration reports, with real cases like test-0601-002); gives a standard debugging flow — extract pptx XML via extract-pptx-structure.js, generate before/after JSON via transvert.ts and diff them; documents OOXML traps such as group-level grpFill, ln noFill precedence over lnRef, and p:pic circular clipping via custGeom; enforces one-way dependency adapter→serializer→model→parser with per-layer responsibilities; and flags high-risk files (shapeSerializer.ts, groupSerializer.ts, parser/units.ts, presets.ts) with pre-change cautions.
- A contributor wants an AI assistant (e.g. Claude Code) to fix PPTX parsing bugs in the OpenMAIC importer under a consistent workflow and guardrails.
- A developer running a fidelity iteration needs to follow the documented process of pulling low-score decks, clustering issues, and shipping an iteration report.
- An engineer debugging pptx-to-JSON restoration differences wants the OOXML pitfall list (grpFill, custGeom, etc.) to locate serializer faults quickly.
- A new team member onboarding to the importer needs to absorb the layered architecture, type protocol, and commit conventions (Chinese verb-first messages, one concern per commit).
What are this skill's strengths and limitations?
- Includes real cases (test-0601-002) with concrete file-level pointers, letting AI assistants navigate instead of guessing.
- Enforces layering red lines and dependency direction (adapter→serializer→model→parser), preventing architectural breakage by AI edits.
- Distills hard-won OOXML traps (grpFill, custGeom, lnRef/noFill precedence), saving repeated debugging cycles.
- Flags high-risk files (800+-line shapeSerializer, 200+-preset presets, widely-depended-on units.ts) with pre-change checklists.
- Strongly internal: nearly unusable outside the OpenMAIC repo (depends on DESIGN.md, src1 reference implementation, and repo scripts).
- Serves package contributors, not end users — it adds no user-facing capability.
- The SKILL.md carries no YAML frontmatter metadata; its purpose must be inferred from its path.
- Some script setup (inspect-low-scores.mjs requires .env.development) is not fully documented in the file.
How do you install this skill?
This skill is an internal development spec inside the OpenMAIC monorepo at packages/@openmaic/importer/SKILL.md — it is not a standalone installable skill. To use it, clone the repo: git clone https://github.com/THU-MAIC/OpenMAIC.git && cd OpenMAIC && pnpm install (requires Node.js >= 20, pnpm >= 10). The repo also ships a separate end-user skills/openmaic OpenClaw skill, but that is a different skill and does not cover this package's development.
How do you use this skill?
Point your AI assistant at packages/@openmaic/importer/SKILL.md as the working spec, e.g. 'Following the importer package's SKILL.md, fix the photo circular clip turning square in test-0601-002.' Typical operations: run node scripts/extract-pptx-structure.js to unzip source XML; run npx tsx scripts/transvert.ts to produce before/after JSON and diff; inspect layoutElements when debugging master/layout decorations; note protocol changes in the commit body when editing adapter/types.ts; re-run compare with a new version after parsing changes. Rendering issues belong to packages/@openmaic/renderer, outside this package.