spec-to-readable-html

spec-to-readable-html is a skill plugin for AI coding agents (such as Claude Code) that takes a Markdown or plain-text specification document and converts it into a structured, readable HTML page. The emphasis is on the word readable: it does not simply reformat the source text, it analyzes the content, summarizes it, and reorganizes sections into categories like requirements, APIs, data models, risks, and open questions.

The output HTML includes visual aids generated automatically from the document's content. These include flowcharts, sequence diagrams, state diagrams, and entity-relationship diagrams rendered using a tool called Mermaid. Summary cards, badges, and tables are also added where relevant. The result is a single portable HTML file with embedded CSS, a table of contents, zoomable diagrams, and print support. If you need a file with no external dependencies at all, the README notes that inline SVG diagrams can be used instead of the default CDN-based Mermaid rendering.

A traceability layer tracks the relationship between every section of the output and the original source. Sections are labeled as Preserved (content kept as-is), Summarized (condensed from the original), or Inferred (derived from context). This makes it possible to verify that nothing important was dropped or changed during the conversion.

The default output language is Japanese, reflecting the author's primary audience, but a language argument lets you switch to other languages when calling the skill. The HTML output template is customizable: the base file uses placeholder tokens for the logo and neutral color variables in the CSS, so you can adapt it to match a brand or project style.

Installation is handled through the npx skills tool, or by manually copying two files into your agent's skills directory. The project is under an MIT license.