Tech Doc Skills

tech-doc-skills

Portable agent skills for writing technical docs and RFCs.

This repo is the canonical source for two reusable skills:

• mermaid-diagrams — write, style, template, and validate Mermaid diagrams for architecture notes, RFCs, ADRs, and READMEs
• web-research — gather current technical evidence with a clear query strategy, source-quality rules, and failover across search tools

These skills are designed to work with Claude Code, OpenAI Codex, OpenCode, and Pi through the same canonical skills/ tree.

Estimated skill token counts

Generated by npm run update:tokens. Rough estimate only: normalized characters / 4. “Full skill” counts all Markdown prompt files in the skill directory; scripts are excluded because they are not loaded as prompt text.

Skill	Top-level SKILL.md	Full skill markdowns	Markdown files counted
mermaid-diagrams	1,442	7,700	7
web-research	750	1,748	5
Total	2,192	9,448	12

Install

Generic skills bundle

Install the bundle from this GitHub repo:

npx skills add championswimmer/tech-doc-skills

Install only one skill if you want a narrower setup:

npx skills add championswimmer/tech-doc-skills -s mermaid-diagrams
npx skills add championswimmer/tech-doc-skills -s web-research

Claude Code plugin + marketplace

This repo is also structured as a Claude Code plugin marketplace.

Add the marketplace from GitHub:

/plugin marketplace add championswimmer/tech-doc-skills

Install the plugin:

/plugin install tech-doc-skills@championswimmer-tech-doc-skills

Then reload plugins in the current session:

/reload-plugins

Claude Code will then load:

• plugin skills from skills/
• bundled plugin MCP servers for context7, perplexity, parallel-search, and exa

Required environment variables for the plugin MCP servers:

export PERPLEXITY_API_KEY=...
export PARALLEL_API_KEY=...
export EXA_API_KEY=...

context7 does not need an API key here.

What these skills do

mermaid-diagrams

Use this skill when you want to:

• turn a design into a diagram
• choose the right Mermaid diagram type
• group things cleanly with subgraphs and boxes
• apply semantic colors for actors, control planes, data stores, success, and failure
• validate Mermaid before publishing docs

Includes:

• scripts/validate-mermaid.js
• scripts/new-mermaid-template.js
• references/diagram-types.md
• references/flowchart-keywords.md
• references/er-keywords.md
• references/gantt-keywords.md
• references/rfc-diagram-patterns.md
• references/official-sources.md

web-research

Use this skill when you want to:

• research current tools, standards, APIs, or ecosystem changes
• compare options for an RFC or design doc
• gather source-backed evidence from official docs and repos
• keep a clear failover order if one search tool is unavailable

Includes:

• scripts/research-plan.js
• references/query-patterns.md
• references/tool-failover.md
• references/source-quality.md
• references/rfc-research-output-template.md

Repository layout

.
├── README.md
├── LICENSE
├── package.json
└── skills/
    ├── mermaid-diagrams/
    │   ├── SKILL.md
    │   ├── references/
    │   └── scripts/
    └── web-research/
        ├── SKILL.md
        ├── references/
        └── scripts/

Local maintenance

npm run update:tokens
npm run validate:mermaid
npm run validate:research
npm run validate

License

MIT