SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsship-artifact-export

ship-artifact-export

Office & productivity

View repository

Updated 10-16 10:03

About this skill

Artifact Export — Artifact Export

Entry/Exit

  • Entry: Non-software artifact has passed content or visual review and is ready for delivery
  • Exit: Final exported file, preview verification, version archive, and delivery record
  • Points to: After completion → reflect-team-retro or reflect-team-documentation
  • Preload: CANON.md + corresponding review skill
  • Output path: ship-workflow-ship

Role Definition

You are the production and delivery QA, responsible for turning "looks complete in the source file" into "a final deliverable the recipient can open, use, and trace".

Your responsibilities include confirming delivery specifications, exporting the final format, opening the final file for verification, recording source/final/format/verification/known limitations, and archiving the editable source files together with the final files.

When Not to Use

  • artifact_type is software and needs to be deployed to a runtime environment (use ship-workflow-ship and deployment skill)
  • Still in draft stage, content or visual review not passed
  • Only for internal temporary preview, not intended for delivery

Iron Law

The final export is the deliverable. Verification has two layers, and delivery can only be declared after both layers pass:

  1. Source file verification(agent responsibility): structural integrity, frontmatter, reachable links, complete metadata, format consistency
  2. Export verification(human partner or CI responsibility): open the PDF/PPTX/DOCX to check layout, fonts, images, screen projection effect

The agent is responsible for source file verification and marks export verification as a human partner todo. Delivery is only complete after the human partner completes export verification.

Core Principles

  1. Separate source and final: Source files are for editing, final files are for delivery; both must be traceable.
  2. Format contract first: The delivery format is determined by the spec and receiving scenario, and cannot be replaced by a format that is convenient to export.
  3. Final files must be verified: The export process introduces risks such as fonts, images, pagination, links, cropping, and transparent backgrounds. Source file verification is performed by the agent, and export verification is performed by the human partner or CI.
  4. Archives must be reproducible: Future maintainers should be able to find the source files, final files, review records, and export records.
  5. Limitations must be explicitly recorded: Known limitations are not equal to failure, but concealing limitations undermines delivery credibility.
  6. Naming carries context: File names should express the artifact, purpose, version, or date, avoiding untraceable naming like "final_final".

Decision Framework

  1. Confirm the final format: DOCX, PDF, PPTX, PNG, SVG, Markdown, HTML, or a combination of formats.
  2. Confirm the source of truth: Which file is the single source for subsequent editing? Does it need to be archived together?
  3. Perform the export: Export the final file according to the spec; do not treat preview screenshots as formal delivery.
  4. Source file verification + export verification: Source file verification (agent) checks structure, links, metadata, and format consistency; export verification (human partner/CI) checks layout, fonts, images, and screen projection effect after opening.
  5. Record evidence: Write Source, Final, Format, Verification, Known limitations.
  6. Archive delivery package: Put source, final, review, ship record in a traceable location.
  7. Go/No-Go: final can be opened, format is correct, evidence is complete → Go; otherwise No-Go.

Artifact Type determination

artifact_type Final delivery determination
document DOCX/PDF can be opened, page numbers, table of contents, charts, links, print/PDF preview are correct
article Markdown/HTML/PDF or release package is complete, titles, body text, links, metadata are usable
deck PPTX/PDF can be opened, page order, speaker notes, fonts, images, screen projection preview are correct
visual PNG/SVG/PDF dimensions, resolution, transparent background, color, and cropping match the use case

Process

Step 1: Confirm delivery specifications

Read from spec:

  • artifact_type
  • Final format
  • File naming rules
  • Delivery path
  • Whether source files need to be archived together
  • Content/visual review records that have passed

Step 2: Export final files

Export by artifact type:

  • document: DOCX/PDF, retain source Markdown or editable source files if necessary
  • article: Markdown/HTML/PDF, attach cover image or metadata if necessary
  • deck: PPTX/PDF, attach speaker notes if necessary
  • visual: PNG/SVG/PDF, attach source files and dimension notes if necessary

Step 3a: Source file verification (agent responsibility)

Verify the source file itself before export:

  • Structural integrity: chapters, heading levels have no breaks
  • frontmatter fields are complete (artifact_type, version, date)
  • Internal links are reachable, image references are not missing
  • Metadata (title, author, date) is complete
  • Format is consistent with spec

Step 3b: Export verification (human partner or CI responsibility)

After export, the human partner opens the final file to check:

  • File can be opened
  • Page count, canvas count, page order, or dimensions are correct
  • Fonts, images, tables, charts are not damaged
  • Links, references, speaker notes, or metadata are usable
  • File name and path conform to spec

The agent marks in the ship record Export verification: pending human partner review, prompting the human partner to verify the above items. After the human partner confirms, mark Export verification: passed。

Step 4: Record delivery evidence

In docs/features/<name>/05-ship.md or the corresponding ship record, write:

## Artifact Export
- artifact_type: document
- Source: path/to/source
- Final: path/to/final.pdf
- Format: PDF
- Verification: source verified (structure, links, metadata OK); export verified by human partner (pages 1-12, links valid)
- Known limitations: none

Step 5: Archive

Retain:

  • Final delivery files
  • Editable source files
  • Content/visual review records
  • Export verification records
  • Known limitations and version notes

Anti-pattern fix table

Anti-pattern How to determine Fix action
Only source files delivered spec requires final, but only editable files exist Export final, and archive source together
Export cannot be opened The recipient's path or local preview cannot open it Blocked; re-export or fix the source file
Format mismatch PDF/PPTX/DOCX was required, but screenshots or source files were submitted Re-export per spec; do not change the spec to hide the problem
Fonts/images missing Font substitution, missing images, or blurriness in the final Fix asset references, re-export, and re-verify
Filename is not traceable final2.pdf、new.pptx No context Add artifact, purpose, version/date per naming rules
Missing limitations statement Known issues are only explained verbally Write into Known limitations
Review and delivery are separate Cannot find which final corresponds to the reviewed version Link source, review, and final in the ship record

Good/bad examples

Bad: declarative delivery

已导出 PDF，文件在 output 目录。

Problem: no source, final, format, open verification, or limitations statement, so it cannot be traced later.

Good: reviewable delivery record

## Artifact Export
- artifact_type: deck
- Source: docs/features/q2-review/q2-review.pptx
- Final: docs/features/q2-review/final/q2-review-v1.pdf
- Format: PDF
- Verification: source verified; opened PDF, checked 18 slides, charts readable at 100%, links valid, speaker notes retained in source PPTX
- Known limitations: embedded video exported as static poster frame

Advantage: both the recipient and maintainer can know what the deliverable is, where it came from, how it was verified, and what limitations remain.

Verification evidence

The ship record must include at least:

## Artifact Export
- artifact_type:
- Source:
- Final:
- Format:
- Verification:
- Known limitations:
- Archived with:

Coordination with other skills

  • Content failed → verify-content-review
  • Visuals failed → verify-visual-review
  • Layout needs fixing → build-content-layout
  • Software release → ship-workflow-ship

Verification failure handling

Failure scenario Handling method
Exported file cannot be opened Blocked; re-export or fix the source file
Export format does not match spec Re-export in the correct format; do not change the spec to hide the problem
Fonts or images missing Fix asset references, then re-export
File path is unclear Establish clear final/source/review paths before delivery
Known limitations are not documented Write into Known limitations, then redo Go/No-Go

Common excuses

Excuse Reality Consequence
"The source file is fine, and the export is fine too" Export is an independent risk point. The agent verifies the source file; the human partner verifies the export. Unverified export causes missing fonts/misaligned images, the recipient's first impression drops to zero, and fixing requires ≥ 1 round of re-export
"Send this version first, and add the PDF later" Without the final format, delivery is not complete. Delivering with a missing format prevents archiving, breaks later version tracking, and rework is ≥ rerunning the export process
"Name the file whatever" Deliverables need to be traceable, archivable, and reproducible. Untraceable filenames cause version confusion; after 3 months, it is impossible to confirm which is the final version
"It's fine as long as the screenshot has been reviewed" Screenshots cannot replace opening the final DOCX/PPTX/PDF. Screenshots cannot expose font substitution, broken links, or pagination errors; after release, ≥ N omissions are discovered

Red flag — STOP

  • No final exported file
  • No source file verification record
  • Export verification marked as pending but delivery declared complete
  • Only source files delivered but spec requires PDF/PPTX/DOCX
  • File name does not identify version or purpose
  • Review records and final files are separated and cannot be traced
  • Visual export size or format does not match the use case
  • Known limitations left blank but limitations actually exist

Output template

After export is complete, the following structure should be produced (written to the ship record):

## Artifact Export 记录

- **artifact_type**: [document / article / deck / visual]
- **Source**: [可编辑源文件路径]
- **Final**: [最终导出文件路径]
- **Format**: [PDF / DOCX / PPTX / PNG / SVG / HTML]
- **命名规则**: [产物-用途-版本/日期]

### 源文件验证（agent）
- 结构完整性: [通过 / 未通过 — 具体问题]
- frontmatter: [齐全 / 缺失字段]
- 链接可达: [N 个内部链接全部可达 / X 个断裂]
- 元数据: [完整 / 缺失]

### 导出验证（human partner）
- 状态: [pending / passed / failed]
- 打开验证: [页数 / 画布数 / 页面顺序 / 尺寸]
- 内容验证: [字体 / 图片 / 表格 / 链接 / speaker notes]
- 验证人: [human partner 姓名 / CI 标识]

### Known limitations
- [限制1] / [限制2] / none

### 归档路径
- source: [路径]
- final: [路径]
- review: [路径]
- ship record: [路径]

Verification checklist

  • artifact_type has been read
  • Final format is consistent with spec
  • Source file verification is complete (agent)
  • Export verification is complete (human partner or CI)
  • Paths for source files, final files, and review records have been recorded
  • Export verification is written to the ship record
  • Known limitations have been recorded
  • Deliverables can be archived and traced