ShowDoc

Write for agents. Render for people.

ShowDoc is an agent skill for Codex, Claude Code, and other compatible coding agents. It replaces separate Markdown and HTML versions with one shared HTML artifact for agents and people.

An agent writes compact Markdown and semantic shw-* elements. One JavaScript include provides the components, Markdown rendering, presentation DOM, and CSS.

The source DOM stays small and focused on content. Agents can read and update it without sorting through repeated presentation code. People get clear type, spacing, status, columns, code, and optional detail. There is no second version to keep in sync.

In one practical review, a normal artifact was estimated at 300 to 800 lines. The same document was estimated at 40 to 80 lines of ShowDoc source. This is an illustrative comparison, not a fixed benchmark. The exact reduction depends on the document.

Example

Open How Offorte ShowDoc works to see a complete ShowDoc document. It explains the authoring model and shows the components in a real page.

Then use View Page Source in your browser. The source contains compact shw-* elements, Markdown, and one versioned CDN script. It does not contain copied component markup or presentation CSS that an agent must maintain.

What the skill creates

The skill creates compact source that contains the meaning and layout decision:

<shw-section heading="Decision" intro="The existing API supports the required flow.">
  <shw-card heading="Recommendation" label="Approved" tone="success">
    Keep the current endpoint. It has the **smallest change** and a reversible rollout.
  </shw-card>
</shw-section>

ShowDoc supplies the repeated presentation DOM and CSS. The agent keeps the useful content small and easy to change.

Use ShowDoc for:

• Technical explanations and architecture reviews.
• Decision records, plans, and project updates.
• Research findings and comparison reports.
• Release notes and other documents that people scan or print.

ShowDoc is not intended for dashboards, forms, modals, or large interactive tools. Those need their own application code.

Plans and change recaps

Build a plan from an outcome, a focused comparison or diagram, and steps with clear checks. Build a recap from the resulting behavior, a real change excerpt, and the checks that actually ran. Existing grids, sections, cards, figures, and tables supply the structure.

For code, shw-code supports language="diff" for supplied unified patches, line-numbers, highlight="2,4-6", and notes tied to lines:

<shw-code
  filename="save.ts"
  language="ts"
  line-numbers
  highlight="2"
  annotations='[{"start":2,"text":"Clear the draft only after the save succeeds."}]'
>
  await save(draft);
  clearDraft();
</shw-code>

Annotations are a JSON array of start, optional end, and Markdown text. Line references are 1-based positions in the displayed excerpt, including any diff headers. They are not file line numbers. Invalid JSON or ranges show an authoring message without hiding the source. Notes remain visible below the code. ShowDoc does not fetch source, compute changes, or verify claims.

Use shw-collapsible content="blocks" for expandable evidence that contains other components:

<shw-collapsible summary="Supporting evidence" content="blocks">
  <shw-code filename="save.ts" language="ts">await save(draft);</shw-code>
  <shw-table caption="Checks">
    Check | Result
    Save retry | Not run
  </shw-table>
</shw-collapsible>

The default disclosure body remains Markdown. In blocks mode, wrap prose in shw-markdown. The authoring skill includes plan and recap recipes, comparison guidance, source escaping rules, and the full compact API.

Documents default to light mode, regardless of the system theme. The theme uses a clear title, restrained accents, distinct metrics, and subtle surface contrast. Use visual variety to explain the content: short comparisons in a grid, wide evidence in a full section, and secondary detail in a disclosure. Keep uncertain results and open decisions explicit.

Install the skill

After you download or clone this repository, copy the complete skills/show-doc folder to your agent's personal skills directory.

For Codex:

mkdir -p ~/.agents/skills
cp -R skills/show-doc ~/.agents/skills/

For Claude Code:

mkdir -p ~/.claude/skills
cp -R skills/show-doc ~/.claude/skills/

Other compatible agents can use the same folder in their own skills directory.

Use the skill

Ask your agent for the document you need:

Use the ShowDoc skill to create a visual project update.

The show-doc skill contains the runtime setup, component reference, and authoring rules. It creates the complete HTML file for you. You do not need to choose a CDN script or write setup code.

The skill uses @latest CDN URLs by default, so generated documents can receive future published updates. Ask for an exact version when a document needs to keep the same runtime. The released showcase stays pinned to its matching package version.

Safety

ShowDoc uses Micromark with safe defaults. Raw HTML and dangerous URL protocols are not enabled in Markdown. Mermaid uses its strict security mode. Syntax highlighting escapes unknown code. ShowDoc performs no lazy loading and makes no runtime request after its selected JavaScript bundle loads.

Do not run a generic HTML formatter over a finished artifact. Some formatters collapse blank lines inside unknown custom elements. Those blank lines are meaningful Markdown input.

Development

The project requires Node.js 24.19.0 or newer and pnpm 10.30.0.

pnpm install --frozen-lockfile
pnpm dev
pnpm serve
pnpm build
pnpm agent:verify

pnpm serve rebuilds the package and serves the CDN-backed showcase at http://127.0.0.1:4173.

pnpm agent:verify checks formatting, lint, TypeScript, browser behavior, the Custom Elements Manifest, bundle limits, package contents, and unused code.

Releases

Release Please reads Conventional Commit types on main. fix: and opt: prepare a patch release. feat: prepares a minor release. A type with !, or a BREAKING CHANGE footer, prepares a major release.

Merging the Release Please pull request creates the GitHub release. The Release package workflow then verifies and publishes the npm package. After publication succeeds, it calls the separate Deploy Pages workflow with the release tag. Deploy Pages only deploys the example site. It can also run manually.

About Offorte

Offorte is automated proposal software that helps businesses create, send, and track beautiful, interactive proposals. It pairs smart workflows with flexible tools, so you can work faster without losing your personal touch. Learn more about Offorte.

License

MIT