# Skill Guide

The TokST skill file (`skill.md`) is a self-contained document that AI agents can read to install and use TokST memory. This page documents how to use it.

## What is skill.md?

`skill.md` is a single Markdown file hosted at `https://tokst.com/skill.md`. It contains the operational rules an AI agent needs to:

1. Install the TokST CLI
2. Complete browser authorization or use an API key for automation
3. Place the Skill in its client directory when that client supports Skills
4. Read, search, store, and govern durable memories
5. Run Cloud or Local Sessions and exchange scoped Agent handoffs

Agents can read it via URL fetch or users can paste its content directly into a chat.

## One-Link Setup

Share this link with any AI agent so it can read the current setup and operating rules:

```
https://tokst.com/skill.md
```

### How to use it

Copy this message and paste it into your agent's chat:

```
Read https://tokst.com/skill.md. Install TokST, configure the matching MCP mode, and follow the Session memory workflow.
```

The installer opens browser authorization and retains the local connection during upgrades. The same `skill.md` works with WorkBuddy, ZCode, Qoder, Kimi, and other clients that support Skills or MCP.

## Version Checking

The skill file includes a version marker (`<!-- skill-version: 0.8.3 -->`). Agents can compare their locally installed version against the remote to detect updates:

```bash
# Installed version
grep "^version:" ~/.claude/skills/tokst-memory/SKILL.md

# Latest version
curl -fsSL https://tokst.com/skill.md | grep "skill-version:"
```

## Supported Agents

Place `skill.md` as `SKILL.md` in the directory used by the target client:

| Agent | Skill directory |
|-------|----------------|
| Claude Code | `~/.claude/skills/tokst-memory/` |
| ZCode | `~/.zcode/skills/tokst-memory/` |
| Cursor / Windsurf | `~/.cursor/skills/tokst-memory/` |
| Codex CLI | `~/.codex/skills/tokst-memory/` |
| Pi | `~/.pi/skills/tokst-memory/` |
| WorkBuddy | `~/.workbuddy/skills/tokst-memory/` |
| Qoder | `~/.qoder/skills/tokst-memory/` |
| Kimi Code | `~/.kimi-code/skills/tokst-memory/` |
| Generic MCP | `~/.agents/skills/tokst-memory/` |

## Connection modes

Browser-capable MCP clients can connect to `https://api.tokst.com/mcp` and approve OAuth in TokST. Static MCP clients use a dedicated API key in the `Authorization` header. Local MCP runs through `tokst local mcp` after `tokst setup --local` and keeps data in the device SQLite profile.

TokST Cloud MCP exposes 51 tools for memories, workspaces, files, Sessions, automatic memory, trusted Agent identity, and messages. The public Skill includes a concise recovery path for PATH conflicts, browser approval, static MCP authorization, quota failures, Local SQLite repair, automatic-memory diagnostics, and Agent listener reconnection.

## Dashboard Integration

When you create an API key for automation in the [dashboard](https://tokst.com/dashboard/api-keys), the creation modal provides:
- A ready-to-copy **SKILL.md** with your key embedded
- A **Quick Start script** for terminal paste
- An **MCP config** JSON
- A per-key **Copy for Agent** button

Browser sign-in and remote MCP approval do not create an API key. Use the [Agents](/dashboard/agents) page to review trusted `agt_...` identities and workspace handoffs.

WorkBuddy, ZCode, Qoder, and Kimi Code can also import `https://tokst.com/skill.md` from their Skills or Agent Skills settings.

## Related

- [Agent Setup Guide](/docs/agent-setup) — Full setup walkthrough
- [CLI Reference](/docs/cli) — Complete command documentation
- [MCP Server](/docs/mcp) — MCP configuration details