skill-to-document

Files (7)

• SKILL.md
• SKILL_ja.md
• style-template.css · assets/
• generate_docx.py · scripts/
• generate_pdf.py · scripts/
• pyproject.toml · scripts/
• uv.lock · scripts/

SKILL.md (first lines)

# 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

From aws-samples/sample-fsi-reference-architecture-jp, MIT-0.

More from aws-samples/sample-fsi-reference-architecture-jp