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.

This repo is a dual-format plugin: a Claude Code plugin (manifest in .claude-plugin/) and an Agent Plugins 1.0.0 compliant plugin (root plugin.json + mcp.json), usable from clients like VS Code (GitHub Copilot), Copilot CLI, Cursor, and Antigravity. See AGENT_PLUGIN_CONVERSION.md for notes on the format differences.

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.

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.

Agent Plugins 1.0.0 (VS Code, Copilot CLI, Cursor, Antigravity)

This repo is also compliant with the vendor-neutral Agent Plugins 1.0.0 spec: the manifest is the root plugin.json, MCP servers are declared in the root mcp.json, and skills are auto-discovered from skills/.

VS Code (GitHub Copilot) — requires the chat.plugins.enabled setting:

1. Open the Command Palette and run Chat: Install Plugin From Source
2. Enter the repo URL: https://github.com/championswimmer/tech-doc-skills

GitHub Copilot CLI:

copilot plugin install https://github.com/championswimmer/tech-doc-skills

Cursor — install as a local plugin:

mkdir -p ~/.cursor/plugins/local
git clone https://github.com/championswimmer/tech-doc-skills ~/.cursor/plugins/local/tech-doc-skills

Then reload the window (or restart Cursor) so it picks up the plugin.

Antigravity — install from a local clone:

git clone https://github.com/championswimmer/tech-doc-skills
agy plugin install ./tech-doc-skills

A note on MCP API keys under Agent Plugins 1.0.0

The bundled MCP servers perplexity, parallel-search, and exa need API keys (PERPLEXITY_API_KEY, PARALLEL_API_KEY, EXA_API_KEY). Unlike Claude Code, the Agent Plugins 1.0.0 spec does not define environment-variable expansion in mcp.json (only ${PLUGIN_ROOT} / ${PLUGIN_DATA} are expanded), so the ${...} placeholders in mcp.json are resolved — or not — by each client. If a server fails to authenticate, configure the key through your client's own MCP secret mechanism (e.g. VS Code ${env:VAR} / input variables) or replace the placeholder in mcp.json with the real key. context7 needs no key and works as-is. See AGENT_PLUGIN_CONVERSION.md for details.

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
├── AGENT_PLUGIN_CONVERSION.md   # notes on the Claude Code → Agent Plugins conversion
├── LICENSE
├── package.json
├── plugin.json                  # Agent Plugins 1.0.0 manifest
├── mcp.json                     # Agent Plugins 1.0.0 MCP server definitions
├── scripts/
│   ├── update-skill-token-counts.js
│   └── validate-agent-plugin.js # Agent Plugins 1.0.0 validator
├── .claude-plugin/
│   ├── plugin.json              # Claude Code plugin manifest
│   └── marketplace.json         # Claude Code marketplace metadata
└── 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:agent-plugin   # validates plugin.json + mcp.json against Agent Plugins 1.0.0 rules
npm run validate                # all of the validators above

License

MIT