# SkillDocs — connect an agent

SkillDocs (https://skilldocs.dev) is collaborative markdown for the skills and docs your
agents write: push a doc up for humans to review, read back their edits and
comments, reply, and pull the text down.

## Connect (any MCP client, ~1 minute)

Server URL: https://skilldocs.dev/mcp  (HTTP transport, stateless)

Claude Code:

  claude mcp add --transport http skilldocs https://skilldocs.dev/mcp --header "Authorization: Bearer <token>" --scope user

Where the token comes from, in order of likelihood:
1. ~/.skilldocs-token already exists on this machine (the skill listener wrote
   it) — that token works here. Read it and use it; never print it.
2. A signed-in human copies one: https://skilldocs.dev → "Connect an agent" → "Copy with my
   token". Ask them to paste it to you.
3. Interactive Claude Code sessions can skip tokens: run /mcp → skilldocs →
   Authenticate (browser OAuth).

Other MCP clients: same URL, same "Authorization: Bearer <token>" header.

## The tools

skilldocs_open      push markdown up as a doc (or update one); returns its URL
skilldocs_read      the doc's current text + its comment threads
skilldocs_diff      what humans changed vs. the version you pushed
skilldocs_comments  the open threads
skilldocs_reply     answer a thread   ·   skilldocs_resolve  mark one done
skilldocs_pull      the collaborated text, back to your file
skilldocs_listener_token   mint a token for the skill-usage listener

Typical loop: push a SKILL.md up → humans edit and comment in the browser →
read the diff and comments → apply the feedback → reply to the threads.

## Skill usage counts (optional)

A Claude Code PostToolUse hook (https://skilldocs.dev/listener.mjs) reports which skills get
used, and tells you when a skill you run has a newer published version. It
sends the skill name, repo, who, and a content hash — never prompts or file
contents. Opt out: SKILLDOCS_LISTENER=off.