Skill To Document

Skill to Document

Convert an Agent Skill package into a professionally formatted PDF, DOCX, or HTML document. Read the skill's SKILL.md and all referenced markdown files, build a logical table of contents, and output a complete document in Japanese.

Prerequisites

• Python: 3.10 or later
• uv: Python package manager (installation guide)
• OS: macOS or Windows (Japanese system fonts are auto-detected)

The bundled Python scripts (scripts/) handle PDF and DOCX generation using fpdf2 and python-docx respectively. Dependencies are managed via scripts/pyproject.toml and automatically installed on first run by uv.

Execution Guidelines

• Execute this skill as a subagent when possible to avoid consuming the caller's context.
• Use extended thinking (ultrathink / super think) for all processing steps due to complexity.

Supported Output Formats

All three output formats are always available — no external skill dependencies required:

1. HTML — Built-in, no additional tools required. Uses bundled assets/style-template.css.
2. PDF — Generated by scripts/generate_pdf.py using fpdf2 with OS-native Japanese fonts.
3. DOCX — Generated by scripts/generate_docx.py using python-docx with book-quality styling.

Architecture

This skill uses an HTML-centric approach:

Agent (Steps 1-7)
    │
    ▼  Always generates HTML first (Step 7)
    ├── HTML format requested → output .html + style.css directly
    ├── PDF format requested  → pass HTML to scripts/generate_pdf.py → .pdf
    └── DOCX format requested → pass HTML to scripts/generate_docx.py → .docx

The agent always produces HTML as the intermediate representation. For PDF and DOCX, the generated HTML file is passed to the corresponding Python script for conversion.

Workflow

Execute these steps in order. Stop and return control on any fatal error.

Step 1: Determine Output Format

User explicitly specified format?
  ├─ Yes (pdf)  → use PDF
  ├─ Yes (docx) → use DOCX
  ├─ Yes (html) → use HTML
  └─ No         → use HTML (default)

All formats are always available. No availability check is needed.

Step 2: Locate the Target Skill

Identify the skill to document:

• Local skill: Resolve the SKILL.md path from the skill name and known skill directories.
• Remote skill (URI): Fetch the SKILL.md content from the given URI. If fetch fails, output the error and stop:

  エラー: SKILL.md を取得できませんでした。
  URI: <uri>
  理由: <error details>
  

Read the SKILL.md frontmatter to extract name and description.

Step 3: Collect Content

Starting from SKILL.md, recursively collect referenced files:

1. Parse all relative file references (links and explicit paths) in SKILL.md.
2. Include: Markdown files (.md) — read their full content and follow their references recursively.
3. Include as appendix: JSON Schema files (.json with $schema or schema-like structure) — add to the end of the document as reference material.
4. Exclude: Application code and scripts (.py, .js, .ts, .jsx, .tsx, .mjs, .cjs, .sh, .bash, .tf, .hcl, .yaml/.yml that are IaC manifests, package.json, tsconfig.json, etc.).

For remote skills, fetch referenced markdown files relative to the SKILL.md URI base.

For image files referenced in markdown (.png, .jpg, .jpeg, .gif, .svg, .bmp):

• Download to a temporary directory.
• Record the mapping from original path to local temp path.
• Clean up all temporary files after document generation is complete.

Step 4: Build Table of Contents

From the collected markdown content, construct a logical document structure:

1. Map markdown headings (#, ##, ###, etc.) to chapter/section/subsection hierarchy.
2. Merge content from multiple files into a coherent structure — use the SKILL.md structure as the primary outline.
3. Assign chapter numbers (1, 1.1, 1.1.1, etc.).
4. Produce the ToC as an ordered list of {number, title, level} entries.

Step 5: Generate Document Body

Compose the document body in Japanese:

• Translate all English content to Japanese. Preserve technical terms, AWS service names, CLI commands, and code snippets in their original form.
• Do not summarize — use the full original text, translated faithfully.
• Preserve the logical structure determined in Step 4.
• Maintain code blocks, tables, and lists as-is (translate surrounding prose only).

Step 6: Place Images

For each image reference found in the content:

• Insert the image at the corresponding position in the document.
• Scale images to fit within page margins (max width: content area width).
• If an image file is unavailable, insert a placeholder note: [画像: <original path> — 取得不可].

Step 7: Generate HTML

Always generate the HTML document first, regardless of the final output format.

Produce a readable, print-friendly HTML document:

• Copy assets/style-template.css (bundled with this skill) to the output subdirectory as style.css.
• Create <skill-name>.html that links to style.css.
• Copy referenced images into an images/ subdirectory and update src attributes accordingly.

The HTML must include proper structural CSS classes for the conversion scripts to parse:

• .title-page for the title page div
• .toc for the table of contents div
• .chapter for each chapter div
• .appendix for the appendix div

Title Page

Center-aligned, containing:

• Document title: Derive an appropriate Japanese title from the skill's name and description.
• Skill name: The raw name field value.
• Date: Current date in YYYY/MM/DD format.

Table of Contents Page

Output the ToC built in Step 4 with chapter numbers and titles.

Body

Output each chapter sequentially, starting each top-level chapter on a new page (use .chapter class).

Appendix (if applicable)

If JSON Schema or other reference files were collected in Step 3, output them in an "付録 (Appendix)" section at the end.

Step 8: Convert to Final Format (if not HTML)

If the requested format is PDF or DOCX, convert the generated HTML using the bundled Python scripts.

Determine the scripts directory path relative to this SKILL.md file location.

PDF Conversion

Run the following command:

uv run --project <scripts-dir> <scripts-dir>/generate_pdf.py --input <html-file-path> --output <output-dir> --skill-name <skill-name>

DOCX Conversion

Run the following command:

uv run --project <scripts-dir> <scripts-dir>/generate_docx.py --input <html-file-path> --output <output-dir> --skill-name <skill-name>

Optionally, pass --template <path> to use a custom DOCX template from assets/.

Important: The --project <scripts-dir> option tells uv run to resolve dependencies from the pyproject.toml in that directory. Do not use shell-specific syntax (e.g., bash). The commands must work on both macOS and Windows.

If the final format is PDF or DOCX, the intermediate HTML file and style.css may be retained or removed based on user preference.

Output Location

All output files are placed in a subdirectory named after the target skill:

<output-base>/<skill-name>/
├── <skill-name>.pdf          # if PDF format
├── <skill-name>.docx         # if DOCX format
├── <skill-name>.html         # if HTML format (or retained as intermediate)
├── style.css                 # if HTML format
└── images/                   # if HTML format and images exist
    └── ...

• If the user specified an output directory, use it as the base. The skill-name subdirectory is created within it.
• Otherwise, determine an appropriate writable directory from the current context (e.g., ~/work/ or the project's output directory) as the base.

Step 9: Verify Output

Confirm the generated file(s):

• Output subdirectory <skill-name>/ exists at the expected path.
• Main file exists and file size is greater than 0 bytes.
• For PDF: verify it starts with %PDF header bytes.
• For DOCX: verify the file is a valid ZIP archive (DOCX is ZIP-based).
• For HTML: verify both <skill-name>.html and style.css exist and are non-empty.

Step 10: Report Completion

On success, return the following to the caller:

ドキュメント生成が完了しました。
ファイル名: <filename>
パス: <absolute path to output subdirectory>
ファイルサイズ: <size in human-readable format>

Clean up any remaining temporary files before returning.