toughtongue-skills

# ToughTongue Skills

[![MCP Registry](https://img.shields.io/badge/MCP_Registry-com.toughtongueai%2Fmcp-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=com.toughtongueai/mcp)

Agent skills and MCP server for [ToughTongue AI](https://app.toughtongueai.com),
the voice-agent platform for high-stakes conversation practice: interviews,
sales, coaching, negotiations.

Install once, then work with ToughTongue from Claude Code, Codex, Cursor, or
any agent that supports the Agent Skills format:

- *"Pull the last 3 lost deals from our call notes and create a practice
  scenario for the pricing objection."*
- *"For the Enterprise Discovery Call scenario, pull the last 50 sessions.
  What are the top 5 improvement areas?"*
- *"The onboarding agent keeps ending calls too early. Pull the low-scoring
  sessions, find out why, and fix the scenario."*

These compose with the rest of your MCP ecosystem: Gong, Notion, calendar,
slides, email. See [What you can do](#what-you-can-do) for the full journeys.

## Table of contents

- [What's included](#whats-included)
- [Prerequisites](#prerequisites)
- [Which setup fits you?](#which-setup-fits-you)
- [Set up](#set-up)
  - [Claude Code](#claude-code)
  - [Codex](#codex)
  - [Cursor](#cursor)
  - [Copilot / Windsurf / Gemini CLI / other agents](#copilot--windsurf--gemini-cli--other-agents)
  - [Skills only](#skills-only)
  - [MCP only](#mcp-only)
- [Verify your setup](#verify-your-setup)
- [What you can do](#what-you-can-do)
- [MCP Server](#mcp-server)
- [Troubleshooting](#troubleshooting)
- [Repository structure](#repository-structure)
- [Related](#related)
- [License](#license)

## What's included

This repo ships two layers that work together, plus plugins that bundle both:

**Skills** — workflow guidance your agent loads automatically when the
conversation matches:

| Skill | When it activates | What it does |
|---|---|---|
| [getting-started](skills/getting-started) | "Get started with ToughTongue", "is my ToughTongue MCP working?" | Post-install onboarding. Verifies the MCP connection and PAT, looks at what's in your account, and routes you into your first workflow. |
| [scenario-creator](skills/scenario-creator) | "Create a scenario", "build a practice roleplay", "prep me for this meeting" | Create production-ready scenarios from a brief, URL, or call transcript. Classifies the type (cold call, sales roleplay, coaching), applies proven authoring patterns, validates, and creates via MCP. |
| [scenario-refiner](skills/scenario-refiner) | "Fix the scenario", "it ended the call too early", "make it sound more natural" | Fix a live scenario from real evidence. Pulls the scenario and low-scoring session transcripts, diagnoses the root cause, and applies the smallest possible edit via MCP. |
| [session-analyst](skills/session-analyst) | "How is my team doing?", "top improvement areas", "build me a coaching report" | Turn session data into answers. Aggregates scores, report cards, and weaknesses across a team or scenario into structured reports: ready to hand off to slides or email tools. |

**MCP server** — live actions in your ToughTongue account. 26 tools over the
public API: scenarios (create, update, generate, access tokens), sessions
(list with evaluations, batch fetch, ingest, post-process), analytics and
organizations, SIP phone calls, meeting bots, and collections. Full catalog
in [MCP.md](MCP.md).

**Plugins** (Claude Code, Codex, Cursor) — bundle the skills **and** the MCP
server registration in one install.

How the layers relate:

- **Skills add judgment** — the agent knows *what* good ToughTongue work
  looks like: how to author a scenario, diagnose a failing one, aggregate
  session data into a report.
- **MCP adds action** — the agent *can* do it: create scenarios, pull
  sessions, update configs, place calls.
- With skills only, your agent can advise. With MCP only, it can call tools.
  With both, it picks the right workflow and completes it. The plugin gives
  you both in one step.

## Prerequisites

Every path needs a **ToughTongue AI account** — sign up at
[app.toughtongueai.com](https://app.toughtongueai.com).

The CLI and coding-agent paths in this README (Claude Code, Codex, Cursor,
Copilot, Windsurf, Gemini CLI, Claude Desktop) also need a **Personal Access
Token (PAT)** — create one at
[app.toughtongueai.com/developer](https://app.toughtongueai.com/developer) and
export it in the environment your agent runs in:

```bash
export TTAI_PAT="<your-token>"
```

On macOS, GUI apps need the variable at the launchd level too:

```bash
launchctl setenv TTAI_PAT "$TTAI_PAT"
```

Then fully restart your agent app and start a new thread.

The claude.ai (web) and ChatGPT (web) connectors skip the PAT entirely — they
authenticate over OAuth. See the [web connector sections](MCP.md#claudeai-web)
in MCP.md.

> **Note**: never commit the PAT or paste it into config files: the plugin
> references it only through the `TTAI_PAT` environment variable.

## Which setup fits you?

| Setup | Best for | What you get |
|---|---|---|
| **Plugin** (recommended) | Claude Code, Codex, Cursor | Skills + MCP, auto-configured in one install |
| **Skills + MCP, manual** | Copilot, Windsurf, Gemini CLI, other agents | Same capability, assembled in two steps |
| **Skills only** | Any Agent Skills client, no live tools needed | Workflow guidance; the agent advises but can't act |
| **MCP only** | Developers who want raw API tools | 26 tools; no workflow guidance |

Not sure? Use the plugin — it's the least setup. Per-client instructions
below.

## Set up

### Claude Code

The plugin bundles the skills and registers the ToughTongue MCP server
(`.mcp.json`) in one install: no separate `claude mcp add` step needed.
Just make sure `TTAI_PAT` is set (see [Prerequisites](#prerequisites)).

Inside Claude Code:

```text
/plugin marketplace add tough-tongue/toughtongue-skills
/plugin install toughtongue@toughtongue-skills
```

Or from the terminal:

```bash
claude plugin marketplace add tough-tongue/toughtongue-skills
claude plugin install toughtongue@toughtongue-skills
```

Then run `/toughtongue:getting-started`: it verifies the connection, looks
at your account, and starts your first workflow.

Skills are namespaced after install: invoke them as
`/toughtongue:scenario-creator`, `/toughtongue:scenario-refiner`,
`/toughtongue:session-analyst`: or just describe the task and Claude picks
the right skill automatically.

<details>
<summary>Upgrade / local development</summary>

**Upgrade** — refresh the marketplace catalog, then move the installed pin
to the latest version:

```bash
claude plugin marketplace update toughtongue-skills
claude plugin update toughtongue@toughtongue-skills
```

Then run `/reload-plugins` in your session to apply.

**Local development / testing** — load the plugin without installing:

```bash
claude --plugin-dir /path/to/toughtongue-skills
# after edits, run /reload-plugins inside the session
```

</details>

### Codex

The plugin bundles the skills and registers the ToughTongue MCP server
(`.mcp.json`) in one install:

```bash
codex plugin marketplace add tough-tongue/toughtongue-skills
codex plugin add toughtongue@toughtongue
```

Then restart Codex and start a new thread. Say "get me started with
ToughTongue" to verify the setup and start your first workflow.

<details>
<summary>Upgrade / local development</summary>

**Upgrade** — both steps are needed; the first refreshes the marketplace
snapshot, the second re-pins the installed plugin to it:

```bash
codex plugin marketplace upgrade toughtongue
codex plugin add toughtongue@toughtongue
```

**Local development / testing** — register the checkout as a local
marketplace:

```bash
codex plugin marketplace add /path/to/toughtongue-skills
codex plugin add toughtongue@toughtongue
```

</details>

### Cursor

In Cursor, go to **Settings > Plugins > Team Marketplaces > Add Marketplace
> Import from Repo**, point it at
`https://github.com/tough-tongue/toughtongue-skills`, then install
**toughtongue**.

Or assemble it manually in two steps:

1. Install the skills:

   ```bash
   npx skills add tough-tongue/toughtongue-skills
   ```

2. Add the MCP server:
   [**Install in Cursor**](cursor://anysphere.cursor-deeplink/mcp/install?name=ttai&config=eyJ1cmwiOiJodHRwczovL2FwaS50b3VnaHRvbmd1ZWFpLmNvbS9hcGkvcHVibGljL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciAke1RUQUlfUEFUfSJ9fQ==)
   — one click adds the server; make sure `TTAI_PAT` is exported first. Or
   add it manually via "Cursor Settings" > "MCP" (config JSON in
   [MCP.md](MCP.md#cursor)).

<details>
<summary>Upgrade</summary>

Re-import the marketplace from **Settings > Plugins > Team Marketplaces**.
If you installed the skills via the CLI, refresh them with
`npx skills update`.

</details>

### Copilot / Windsurf / Gemini CLI / other agents

No plugin for these yet — install the skills and the MCP server as two
steps:

**1. Install the skills.** Works with any Agent Skills-compatible client:

```bash
npx skills add tough-tongue/toughtongue-skills
```

The CLI prompts you to pick which skills to install and which agents to
configure. To install everything non-interactively:

```bash
npx skills add tough-tongue/toughtongue-skills --all
```

Update existing skills later with:

```bash
npx skills update
```

**2. Add the MCP server.** Point your client at the hosted server — the
general shape is:

```json
{
  "mcpServers": {
    "ttai": {
      "url": "https://api.toughtongueai.com/api/public/mcp",
      "headers": {
        "Authorization": "Bearer ${TTAI_PAT}"
      }
    }
  }
}
```

Exact config per client (Copilot/VS Code, Windsurf, Gemini CLI) is in
[MCP.md](MCP.md#connect-your-client).

**Stdio-only clients** (Claude Desktop, Zed, older VS Code): bridge to the
hosted server with [mcp-remote](https://github.com/geelen/mcp-remote) — see
[MCP.md](MCP.md#clients-without-remote-mcp-support).

### Skills only

Want the workflow guidance without connecting y