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 versioned 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.

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 full versioned runtime contract, 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.

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