Runlog Skills — MCP Client Skills

Part of the Runlog project. See the project home for the overview.

Repo: runlog-org/runlog-skills (public, MIT) Content: Agent skill files and MCP client configs Role: drop-in adapters that wrap the Runlog MCP tools (runlog_search, runlog_submit, runlog_report) for nine vendor agent frameworks. Each adapter honours the four-point client contract in common/four-point-client-contract.md: team-memory-first, external-only classification, route learnings to the right layer, maintain a dependency manifest.

About this project: Runlog is a hobby side project by Volker Otto — not a commercial product today. A paid model is not ruled out for a later stage. See About this project for the canonical framing.

Drop-in skill files so agents running Claude Code, Cursor, Cline, Continue, Windsurf, Aider, VS Code Copilot, JetBrains AI Assistant, and Zed can use Runlog without writing their own MCP plumbing. Each skill wraps runlog_search, runlog_submit, and runlog_report with the right framework-specific glue.

Also standardises how each agent framework tracks kb:<id> entries in its working session so the server's failure-attribution engine gets clean dependency manifests.

What's shipped today

All 9 vendor adapters (Claude Code + 8 cross-vendor expansion) are operational on the read side against the live MCP server. The write side ships per-vendor too and is functional end-to-end as of runlog-verifier v0.1.0 (2026-04-28) — the three F24 prerequisites (verifier release artifact, public-key registration flow, runlog-verifier register --email UX) all shipped under F24. See runlog-author/DESIGN.md §Status.

Vendor	Read	Write	Harvest	Read-side install	Notes
Claude Code	✅	✅	✅	claude-code/SKILL.md	Reference adapter
Cursor	✅	✅	✅	cursor/SKILL.md → .cursor/rules/runlog.mdc	Highest priority after Claude Code
Cline	✅	✅	✅	cline/SKILL.md → .clinerules/runlog.md	Open-source, MCP-native
Continue.dev	✅	✅	✅	continue/SKILL.md → .continue/config.yaml rules block	Open-source, MCP-native
Windsurf	✅	✅	✅	windsurf/SKILL.md → .windsurfrules	Codeium-based
Aider	✅ *	✅ *	✅ *	aider/SKILL.md → CONVENTIONS.md or --read	* MCP support is version-dependent
VS Code + GitHub Copilot	✅	✅	✅	copilot/SKILL.md → .github/copilot-instructions.md	Requires Copilot agent mode
JetBrains AI Assistant	✅ *	✅ *	✅ *	jetbrains/SKILL.md → AI guidelines	* Tool-use varies by IDE / plugin version
Zed	✅ *	✅ *	✅ *	zed/SKILL.md → .rules	* HTTP context_servers schema is evolving

Asterisks (*) flag adapters whose MCP integration is evolving in the upstream vendor. The adapter is shipped and works against today's vendor capabilities, but check the per-vendor README's "VERIFY" notes against current vendor docs before publishing your config.

Three skill types ship per vendor:

• Read (SKILL.md) wraps runlog_search so the agent consults the registry when team memory falls short.
• Author / write (runlog-author.md) drives the verifier-loop submission flow mid-session, right after a third-party-system gotcha is solved.
• Harvest (runlog-harvest.md) is the end-of-session retrospective lever. Invoked explicitly via /runlog:runlog-harvest (or each vendor's equivalent — see per-vendor READMEs), it scans the finished session for external-dependency findings and routes selected ones through the author flow.

The canonical bodies under runlog-author/ and runlog-harvest/ are the source of truth; per-vendor folders inherit them and swap orchestration glue.

Install

Five install paths, in order of preference for a given vendor:

1. Claude Code: plugin marketplace (start here)

The Claude Code plugin installs the runlog, runlog-author, and runlog-harvest skills and adds the /runlog:runlog-harvest and /runlog:runlog-author slash commands. The MCP server itself is wired separately in Step 2.

Prerequisites

• Claude Code installed — see https://docs.claude.com/en/docs/claude-code/quickstart if you don't have it yet.
• A Runlog API key from https://runlog.org/register.

Step 1 — Install the plugin

These are two separate slash commands. Run them one at a time inside Claude Code, not on the same line:

/plugin marketplace add runlog-org/runlog-skills

Wait for Successfully added marketplace: runlog-org, then:

/plugin install runlog

Putting both on one line fails with Malformed input to a URL function. Claude Code treats everything after add as the marketplace argument and tries to clone a nonsense URL.

Step 2 — Wire the MCP server

The plugin ships skills, slash commands, and the plugin manifest, but it does not auto-register the Runlog MCP server. (Claude Code's plugin .mcp.json does not expand ${VAR} substitutions in headers. See #9427 and #11927 — a plugin-shipped HTTP-MCP entry would always fail to authenticate.) Wire the server explicitly to user scope, where header substitution works:

claude mcp add --transport http -s user \
  -H "Authorization: Bearer $RUNLOG_API_KEY" \
  runlog https://api.runlog.org/mcp

Your shell expands $RUNLOG_API_KEY before claude mcp add stores the resulting value in ~/.claude.json. Set the env var first if you haven't:

export RUNLOG_API_KEY="sk-runlog-<your-key>"   # in ~/.zshrc, ~/.bashrc, or your shell profile

Restart Claude Code so it picks up the new MCP entry.

Step 3 — Verify

Run claude mcp list. The entry runlog: https://api.runlog.org/mcp (HTTP) — ✓ Connected should appear. (Note: the prefix is not plugin:runlog:runlog, as the server is user-registered, not plugin-registered.) If it's missing or shows an auth error:

• Confirm echo "$RUNLOG_API_KEY" returns the key in the shell that ran claude mcp add.
• Confirm the key starts with sk-runlog- and has no trailing whitespace.

Step 4 — Try it

The skills are now active in any session. Ask Claude something that touches a third-party system, for example:

"Search runlog for known gotchas with git filter-repo on submodules."

The agent calls runlog_search via MCP and folds matching entries into its answer. When you've just solved an external-dependency gotcha that runlog_search did not surface, the runlog-author skill drives the verifier loop to submit it back. End-of-session retrospectives go through /runlog:runlog-harvest.

Common issues

• Plugin 'runlog@runlog-org' is already installed. You're set. Use /plugin to manage existing installs.
• Skills don't show up. Plugin skills load at session start; restart Claude Code.
• runlog doesn't appear in claude mcp list. Re-run the claude mcp add command from Step 2 in a shell where $RUNLOG_API_KEY is exported, then restart Claude Code.
• Skill listed but never invoked. Check that ~/.claude/settings.json does not contain "skillOverrides": { "runlog": "off" } (or "name-only" / "user-invocable-only").

2. Cross-vendor MCP install: npx add-mcp (Claude Code, Cursor, Cline, Zed)

The one-liner that covers the four Runlog vendors add-mcp writes a working config for. Neon's add-mcp reads Runlog's Official MCP Registry entry (org.runlog/runlog) and auto-detects every supported agent on the machine, writing the correct config for each:

npx add-mcp https://api.runlog.org/mcp

Pass -a <agent> to target one host (claude-code, cursor, cline, zed); pass -g for a global config rather than project-scoped. Validated for: Claude Code, Cursor, Cline (both VS Code extension and cline-cli), Zed.

Continue, Windsurf, Aider, VS Code Copilot, and JetBrains are not in add-mcp's supported set today — use path 3, 4, or 5 for those vendors. The python-installer (path 4) also covers Zed as a delegated target.

add-mcp only writes the MCP server config; the per-vendor SKILL.md body still needs to land in the host's rules path. Either copy it manually (path 5) or use the python-installer (path 4) or run npx @runlog/install <vendor> --write (path 3) for the skill side. The Claude Code plugin (path 1) ships the skills + slash commands; the MCP server is wired in path 1 Step 2.

3. Any vendor: npx @runlog/install <vendor>

# Print the rule + MCP config for review
npx @runlog/install cursor

# Or write directly to the vendor's rules path
npx @runlog/install cursor --write

Vendors: claude-code, cursor, cline, continue, windsurf, aider, copilot, jetbrains, zed. The installer fetches the canonical SKILL.md from this repo's main and writes it to the right vendor-specific path (or prints it for vendors that share a single rules file with the user's other content). It does not auto-edit your MCP config. It prints the snippet for you to merge in. See installer/README.md for full flag reference.

4. Python installer: runlog install --target <host> (no npm required)

A stdlib-only Python installer (pipx install runlog-installer) covers seven hosts across two modes. Use this when npm is not available or you want a single command that handles both SKILL placement and MCP-config editing for hosts add-mcp does not reach.

Target	Host	Mode	What gets installed
claude	Claude Code	delegated	SKILL only — wire MCP via npx add-mcp
cursor	Cursor	delegated	SKILL only — wire MCP via npx add-mcp
zed	Zed	delegated	SKILL only — wire MCP via npx add-mcp
aider	Aider	fallback	SKILL + MCP-config edit at ~/.aider.conf.yml (no npm needed)
continue	Continue.dev	fallback	SKILL + MCP-config edit at ~/.continue/config.yaml (no npm needed)
copilot	GitHub Copilot (VS Code)	fallback	SKILL + MCP-config edit (no npm needed)
windsurf	Windsurf	fallback	SKILL + MCP-config edit (no npm needed)

Delegated hosts use add-mcp for the MCP wiring step; the installer places the SKILL and prints the reminder. Fallback hosts get both the SKILL and the MCP block written directly. An API key is required (--api-key flag, RUNLOG_API_KEY env, or interactive prompt).

The python-installer also provides runlog register --email <addr> to orchestrate the verifier registration flow. See python-installer/README.md for the full reference.

Not yet automated (Cline, JetBrains): Cline and JetBrains AI Assistant are not in the python-installer's host set today. For Cline, path 2 (npx add-mcp) covers the MCP wiring and path 3 (npx @runlog/install cline --write) places the SKILL files. For JetBrains, use path 5 (manual) until a follow-up slice ships support.

5. Manual: clone + copy

The original install model still works. Each per-vendor folder's README has a Quickstart section that walks through cp <vendor>/SKILL.md <target-path> plus the MCP config to add. Use this if you want to read the rule before installing it, or your environment has neither npm nor Python.

Cross-vendor coverage — [F25]

Runlog should be usable from any agent that speaks MCP, not tied to a single platform. As LLM vendors ship their own "skills" / "memory" / "knowledge" features, keeping the cross-vendor surface broad is what makes Runlog complementary to those features rather than competing with them.

Each vendor gets two adapters:

• Read-side — port claude-code/SKILL.md with vendor-specific MCP config, the team-memory surface to check first (.cursorrules, .clinerules, .windsurfrules, .github/copilot-instructions.md, etc.), and how the dependency manifest is persisted across the agent's tool-use turns.
• Write-side — wrap runlog-author/SKILL.md. The canonical author body is inherited byte-for-byte; the adapter swaps orchestration glue (vendor's tool-use API, agent-loop iteration, command palette / slash-command invocation, how local Bash is dispatched).

The common/ extraction means each vendor adapter references cross-vendor invariants instead of re-authoring them. When the contract changes, one file moves, not nine.

Layout

skills/
├── .claude-plugin/                         # ✅ Claude Code plugin marketplace + plugin manifest
│   ├── marketplace.json
│   └── plugin.json
├── skills/                                 # ✅ Plugin-discoverable skills (mirrors of canonical bodies)
│   ├── runlog/SKILL.md
│   ├── runlog-author/SKILL.md
│   └── runlog-harvest/SKILL.md
├── installer/                              # ✅ npx @runlog/install package source
│   ├── package.json
│   ├── index.js
│   └── README.md
├── claude-code/                            # ✅ Reference adapter (read side; canonical body)
│   ├── SKILL.md
│   └── runlog-harvest.md
├── commands/                               # ✅ Slash-command shims (e.g. `/runlog:runlog-harvest`)
│   ├── runlog-harvest.md
│   └── runlog-author.md
├── runlog-author/                          # ✅ Canonical author body (vendor-agnostic)
│   ├── SKILL.md
│   └── DESIGN.md                           #     design rationale + open questions
├── runlog-harvest/                         # ✅ Canonical harvest body (vendor-agnostic)
│   ├── SKILL.md
│   └── DESIGN.md                           #     design rationale + open questions
├── common/                                 # ✅ Cross-vendor invariants
│   ├── README.md
│   ├── four-point-client-contract.md       # ✅ shipped
│   ├── runlog-author-contract.md           # ✅ shipped
│   ├── runlog-harvest-contract.md          # ✅ shipped
│   ├── dependency-manifest.md              # ⏳ planned — extracted when 2nd consumer ships
│   └── reporting-conventions.md            # ⏳ planned — extracted when 2nd consumer ships
├── cursor/                                 # ✅ shipped
│   ├── README.md
│   ├── SKILL.md
│   ├── runlog-author.md
│   └── runlog-harvest.md
├── cline/                                  # ✅ shipped
│   ├── README.md
│   ├── SKILL.md
│   ├── runlog-author.md
│   └── runlog-harvest.md
├── continue/                               # ✅ shipped
│   ├── README.md
│   ├── SKILL.md
│   ├── runlog-author.md
│   └── runlog-harvest.md
├── windsurf/                               # ✅ shipped
│   ├── README.md
│   ├── SKILL.md
│   ├── runlog-author.md
│   └── runlog-harvest.md
├── aider/                                  # ✅ shipped (caveats)
│   ├── README.md
│   ├── SKILL.md
│   ├── runlog-author.md
│   └── runlog-harvest.md
├── copilot/                                # ✅ shipped
│   ├── README.md
│   ├── SKILL.md
│   ├── runlog-author.md
│   └── runlog-harvest.md
├── jetbrains/                              # ✅ shipped (caveats)
│   ├── README.md
│   ├── SKILL.md
│   ├── runlog-author.md
│   └── runlog-harvest.md
├── zed/                                    # ✅ shipped (caveats)
│   ├── README.md
│   ├── SKILL.md
│   ├── runlog-author.md
│   └── runlog-harvest.md
└── README.md                               # this file

Invariants every adapter MUST honour

• The four rules in common/four-point-client-contract.md — read, write, and harvest skills all inherit.
• The author-side rules in common/runlog-author-contract.md — adds the submission-flow constraints.
• The harvest-side rules in common/runlog-harvest-contract.md — adds the retrospective-scan, picker-grammar, and route-to-author constraints.

The contract is framework-agnostic; per-vendor adapters swap orchestration glue, not the rules.

Maintenance pattern

When the cross-vendor contract changes (e.g. a new MUST-NOT rule or a tool-call shape update), the change pattern is:

1. Update common/four-point-client-contract.md, common/runlog-author-contract.md, and/or common/runlog-harvest-contract.md (single source of truth).
2. Re-sync each per-vendor SKILL.md / runlog-author.md / runlog-harvest.md by re-reading the canonical body and bringing the vendor wrapper in line.
3. The bodies are deliberately ~80% similar across vendors; the vendor-specific glue is concentrated in the Setup sections and a few notes paragraphs.
4. Re-sync the plugin's discovery copies: cp claude-code/SKILL.md skills/runlog/SKILL.md, cp runlog-author/SKILL.md skills/runlog-author/SKILL.md, and cp runlog-harvest/SKILL.md skills/runlog-harvest/SKILL.md. (The skills/ tree is what Claude Code's plugin loader reads; the canonical bodies stay at their established paths so existing per-vendor wrappers don't need to chase a path move. CIFS doesn't allow symlinks, so they're plain copies.)

The npx installer (installer/index.js) fetches <vendor>/SKILL.md live from main on GitHub at install time, so it always pulls the latest canonical body — no version coupling to maintain.

Future tooling (a generator script that produces vendor adapters from the canonical body + a vendor-glue spec) is a maintenance-pain follow-up; not yet needed at 9 vendors.

Publishing @runlog/install to npm

The npm scope @runlog must be claimed before first publish (npm org create runlog while logged in as the maintainer, or register a user named runlog). Once the scope exists:

cd installer
npm publish --access public

Bump the version in installer/package.json for each release. The installer fetches its content from GitHub at runtime, so users always get the latest skill body regardless of which installer version they ran.

Depends on

• runlog-org/runlog-schema — referenced in documentation only (not as a code dep)
• runlog-org/runlog-verifier — the runlog-author skill drives the local verifier binary; without it the write side cannot submit. Install from the latest release (verify against SHA256SUMS); see runlog-author/SKILL.md §Setup for the platform-keyed download.