# Skill To Document

> Convert an Agent Skill into a formatted document (PDF, DOCX, or HTML). Use this skill when the user wants to generate a document from a specific Agent Skill's content, including its SKILL.md and referenced markdown files. Triggers on keywords: "skill to document", "スキルをドキュメント化", "ドキュメント生成", "スキルからPDF", "スキルからWord", "スキルからHTML", "generate document from skill", "convert skill to PDF", "convert skill to DOCX", "convert skill to HTML". Supports PDF (via fpdf2), DOCX (via python-docx), and HTML (built-in). All formats are always available. Defaults to HTML when no format is specified.

- Skill: `aws-samples/skill-to-document` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add aws-samples/skill-to-document`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/skill-to-document/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT No Attribution
- Author: aws-samples (https://skillmd.com/u/aws-samples)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aws-samples/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](https://docs.astral.sh/uv/getting-started/installation/))
- **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.