# 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](https://code.claude.com/docs/en/plugins) (manifest in `.claude-plugin/`) **and** an [Agent Plugins 1.0.0](https://agent-plugins.org) 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](AGENT_PLUGIN_CONVERSION.md) for notes on the format differences.

<!-- skill-token-counts:start -->
## 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** |
<!-- skill-token-counts:end -->

## Install

### Generic skills bundle

Install the bundle from this GitHub repo:

```bash
npx skills add championswimmer/tech-doc-skills
```

Install only one skill if you want a narrower setup:

```bash
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:

```text
/plugin marketplace add championswimmer/tech-doc-skills
```

Install the plugin:

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

Then reload plugins in the current session:

```text
/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:

```bash
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](https://agent-plugins.org) spec: the manifest is the root [`plugin.json`](plugin.json), MCP servers are declared in the root [`mcp.json`](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**:

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

**Cursor** — install as a local plugin:

```bash
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:

```bash
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](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

```text
.
├── 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

```bash
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