# Agent skills and setup tools

> Teach Claude Code, Codex and other agents when to use Cloak Proxy with installable skills, let them set up capture and certificates step by step, search the docs, and redact credentials before they reach the model.

Source: https://docs.subcloak.com/cloak-proxy/automation/agent-skills/

Added in Cloak Proxy 0.4.0.

Cloak Proxy's [MCP server](https://docs.subcloak.com/cloak-proxy/automation/mcp-server/) gives an AI assistant close to a hundred tools. Tools alone don't tell an agent when to reach for them, or in which order. This page covers what fills that gap: **agent skills** that teach Claude Code, Codex and other coding agents how to use Cloak Proxy, **guided setup tools** an agent uses to get an app's traffic flowing, a **docs search** tool, and the **Redact sensitive data before sending to AI** switch that keeps credentials out of the conversation.

## What's included

| Part | What it does |
|---|---|
| [Agent skills](#install-the-skills) | Seven SKILL.md files: capture setup, debugging a failing request, mocking and intercepting, contract checks, authorization tests, CI recording, and the API client. Agents load one only when a task needs it. |
| [`capture_setup`](#guided-capture-setup) | A checklist for capturing a Mac app, a simulator, an iPhone, an Android device, a terminal tool, Docker, Firefox, Java, Electron or Flutter, with each step marked done or not, and the steps Cloak Proxy can do itself. |
| [`install_certificate`](#install-the-certificate) | Installs the root certificate in simulators, copies it to an Android device, opens the trust prompt on the Mac, or writes it to a file. |
| [`search_docs`](#search-the-docs) | Searches these docs offline and returns the pages, their Markdown versions and the matching sections. |
| [Redaction](#redact-sensitive-data-before-sending-to-ai) | Replaces tokens, cookies, keys and passwords in every tool result with `REDACTED`. On by default. |
| [`cloakctl skills`, `setup` and `docs-search`](#from-the-command-line) | The same from Terminal and in CI. |

## Install the skills

Agent Skills are folders with a `SKILL.md` file: a short description that tells the agent when the skill applies, and instructions it reads only then. Claude Code, Codex and other agents that support the format pick them up from a skills folder.

*[Screenshot: The Agent skills card on the API client's MCP page: an Install for menu set to Claude Code, Show in Finder, Remove and Update Skills buttons, and a list of seven skills, Capture setup, Debug traffic, Mock and intercept, API contracts, Authorization testing, Record in CI and API client, each marked Installed, Update available or Not installed. The Agent skills card shows which skills are installed for the chosen agent.]*

1. Open the API client with <kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>M</kbd> (**File › MCP…**) and scroll to **Agent skills**. **Settings › Advanced › Agent skills › Manage…** opens the same card.
2. Under **Install for**, choose **Claude Code** (every project, in `~/.claude/skills`), **Codex** (`~/.codex/skills`), or **Other Folder…** for any other agent's skills folder.
3. Click **Install 7 Skills**. When a new version of Cloak Proxy changes a skill, the card shows **Update available** next to it and the button becomes **Update Skills**.
4. Connect the [MCP server](https://docs.subcloak.com/cloak-proxy/automation/mcp-server/#connect-your-assistant) if you haven't. The skills call its tools.
5. Restart your agent, or start a new session, so it sees the skills.

Each skill row shows its state:

| Mark | Meaning |
|---|---|
| Green check, **Installed** | The skill is in the folder and matches this version of Cloak Proxy. |
| Orange arrows, **Update available** | The folder has a different version, from an older Cloak Proxy or edited by hand. Updating replaces it. |
| Dashed circle, **Not installed** | The skill isn't in the folder. |

**Remove** deletes the seven `SKILL.md` files and their folders. Other skills, and any files you added inside a skill's folder, are left alone. Right-click a skill and choose **Copy SKILL.md** to paste it somewhere else.

> **Only for one project:**
> To install the skills for one repository instead of every project, run `cloakctl skills install project` in the repository's folder. They go into `.claude/skills`, which you can commit so everyone on the team gets them.

### The skills

| Skill | The agent uses it when you… |
|---|---|
| `cloak-proxy-capture-setup` | Want to see an app's, simulator's, phone's or tool's traffic, or Cloak Proxy shows nothing or only encrypted tunnels. Walks through [guided setup](#guided-capture-setup) and the [Doctor](https://docs.subcloak.com/cloak-proxy/capture/doctor/). |
| `cloak-proxy-debug-traffic` | Ask why a request failed, what an app sent, or where a value came from. Finds the request, compares it with a working one, traces values and confirms a fix with a replay. |
| `cloak-proxy-mock-and-intercept` | Want a fake response, a slow or failing backend, a header added or a request paused. Picks the right [debugging tool](https://docs.subcloak.com/cloak-proxy/tools/overview/), starts from a real request, and offers to clean up afterwards. |
| `cloak-proxy-api-contracts` | Ask whether an API matches its OpenAPI spec, want a spec written from traffic, or want contract checks in CI. See [Contract checking](https://docs.subcloak.com/cloak-proxy/testing/contract-checking/). |
| `cloak-proxy-authorization-testing` | Ask whether one user can see another's data on an API you own. Runs the [authorization matrix](https://docs.subcloak.com/cloak-proxy/testing/authorization-matrix/) and reports leaks. |
| `cloak-proxy-ci-recording` | Want to record or check a test suite's traffic in CI, run tests offline against a recording, or run collections like Newman. See [Headless runs and CI](https://docs.subcloak.com/cloak-proxy/automation/headless-and-ci/). |
| `cloak-proxy-api-client` | Want to save, organise, test or run requests in the [API client](https://docs.subcloak.com/cloak-proxy/api-client/overview/). |

The skills tell the agent what not to do as well: ask before replaying writes or turning macOS capture off, never paste captured tokens, never try to trust the certificate for you, and only run authorization tests on systems you're allowed to test.

## Redact sensitive data before sending to AI

Whatever a tool returns becomes part of the conversation, and your assistant sends the conversation to its model provider. With this switch on, which is the default, the MCP server removes credentials from every tool result and resource before the assistant sees them.

*[Screenshot: Settings › Advanced: the AI assistants (MCP) section with copyable setup for Claude Code and other clients, the Redact sensitive data before sending to AI switch turned on with an explanation, and an Agent skills row reading 5 of 7 current for Claude Code with a Manage button. The switch is in Settings › Advanced and on the MCP page.]*

Turn it off in **Settings › Advanced › AI assistants (MCP)**, or under **Use Cloak Proxy from AI assistants** on the MCP page. An assistant can read the setting but can't change it: `update_settings` doesn't include it.

| What | Becomes |
|---|---|
| `Authorization`, `Proxy-Authorization`, `X-Api-Key` and other credential headers | The scheme and `REDACTED`, such as `Bearer REDACTED` |
| `Cookie` and `Set-Cookie` | Each cookie's name with `REDACTED` as its value |
| Query parameters and JSON or form fields named like `password`, `token`, `access_token`, `api_key`, `secret` or `session_id` | `REDACTED` |
| Anything the [secret scanner](https://docs.subcloak.com/cloak-proxy/insights/secrets/) recognises, anywhere: API keys, JWTs, private keys, card numbers | `REDACTED` |
| cURL commands from `get_request_curl` | Credential headers, `-u` passwords and `-b` cookies redacted |

Request and response bodies stored as text are redacted too, including JSON inside them. Everything else, such as URLs, status codes, other headers, emails and IDs, comes through unchanged so the assistant can still debug. The rules match [redaction on export](https://docs.subcloak.com/cloak-proxy/sessions/redaction/).

Redaction only changes what the assistant sees. Replays and rules still use the real values: `replay_request`, `edit_and_replay` (headers you give are merged over the captured ones), `rule_from_request` and `authorization_matrix` with `from_request` all work on the captured request inside Cloak Proxy.

> **Redacted values can't go back in:**
> If an assistant tries to send a value it only saw as `REDACTED`, for example a header copied from `get_request` into `edit_and_replay`, or a body copied into a Map Local rule, the tool refuses with an error that explains how to keep the original instead. This stops a placeholder from replacing your real token or ending up in a mock.

When the app isn't running (with [`cloakctl run`](https://docs.subcloak.com/cloak-proxy/automation/headless-and-ci/), for example), results are always redacted. To turn redaction off for one MCP server, such as a CI job reading its own test traffic, add `--no-redact` after `mcp` in its command.

## Guided capture setup

`capture_setup` returns the steps that get one kind of client's HTTPS traffic into Cloak Proxy, checked against the current state. Ask your assistant something like "set up Cloak Proxy for my app in the iOS Simulator", and with the capture skill installed it calls `capture_setup`, does what it can, and tells you exactly what's left for you.

| Target | Covers |
|---|---|
| `mac` | Mac apps and browsers through the macOS proxy. |
| `ios_simulator` | iOS, iPadOS, tvOS and watchOS Simulators: macOS capture, Xcode, booted simulators and their certificate. |
| `iphone` | An iPhone or iPad on Wi-Fi: other devices allowed, the Wi-Fi proxy, the profile and full trust. |
| `android` | An emulator or USB device over adb: the device, its proxy, the certificate, and your app's network security config. |
| `terminal` | curl, Node.js, Python, Ruby, Go, git and other command-line tools: `cloakctl run`, or proxy variables for a shell. |
| `docker` | Containers, through `host.docker.internal`. |
| `firefox` | Firefox's own certificate store. |
| `java` | The JVM's trust store and proxy flags. |
| `electron` | Electron and Chromium apps that ignore the macOS proxy. |
| `flutter` | Dart's `HttpClient`, which ignores the system proxy. |

Pass `app` (the app's name, as in the sidebar) and `hosts` (the API hosts, wildcards allowed) and the checklist also checks that they're decrypted and that the app's requests are arriving.

### Read the checklist

Each step has an `id`, a `title`, a `detail` and a `status`:

| Status | Meaning |
|---|---|
| `done` | Already true. |
| `todo` | Not done, and Cloak Proxy can do it: call `capture_setup` again with `apply` set to the step's `id`. |
| `needs_user` | Only you can do it, because it needs your Mac password or happens on the device. The `detail` and `commands` say exactly what to do. |
| `info` | A tip or an optional step. |

`next` names the first required step that isn't done, and `ready` is `true` once every required step is. The result also has a plain-text version of the checklist and a link to the docs page for the target.

### Steps Cloak Proxy can do

| `apply` | What it does |
|---|---|
| `macos-proxy` | Turns on macOS capture. Your previous proxy settings come back when it's turned off. |
| `ssl-proxying` | Adds the `hosts` and `app` you passed to [SSL proxying](https://docs.subcloak.com/cloak-proxy/capture/ssl-proxying/), and closes their open tunnels so new connections are decrypted. |
| `other-devices` | Lets other devices connect, restarting the proxy on every network interface. |
| `recording` | Resumes recording. |
| `mac-certificate` | Opens **Settings › Certificate**. You click **Install & Trust…** and enter your password. |
| `simulator-certificate` | Adds the certificate to every booted simulator, or the one in `udid`, with `simctl`. No password needed. Relaunch the app afterwards. |
| `android-proxy` | Runs `adb reverse` for the proxy port and sets the device's global proxy to it, for every ready device or the one in `serial`. |
| `android-proxy-off` | Clears the device's proxy and the port forward. Do this when you're done. |
| `android-certificate` | Copies the certificate to the device's Downloads. You install it in the device's Settings. |
| `environment` | Returns `export` lines for the proxy and certificate variables, for you to paste into a shell. |

> **Some steps change system settings:**
> `macos-proxy` changes your Mac's network settings and `android-proxy` changes the device's. The capture skill tells the agent to say so before applying them, and your client asks before running the tool unless you've auto-approved it. Undo them with `set_macos_proxy` and `android-proxy-off`.

## Install the certificate

`install_certificate` installs or exports the root certificate on its own, without the rest of the checklist:

| `target` | What happens |
|---|---|
| `simulator` | Adds it to every booted simulator, or the one given as `udid` (a UDID or a name). |
| `android` | Copies it to the Downloads folder of every ready device, or the one given as `serial`. You finish in **Settings › Security › Encryption & credentials › Install a certificate › CA certificate**. |
| `mac` | Reports whether the Mac already trusts it; if not, opens **Settings › Certificate** for you to confirm with your password. |
| `file` | Writes it as `pem` (default) or `der` to `path`, by default `~/Downloads/cloak-proxy-ca.pem`. The result includes its SHA-256 fingerprint. |

The certificate file is public and safe to copy. Its private key never leaves `~/Library/Application Support/CloakProxy/`. See [Root certificate](https://docs.subcloak.com/cloak-proxy/capture/certificate/).

## Search the docs

`search_docs` searches an index of every page in these docs, built into Cloak Proxy, so it works offline. It matches titles, headings and descriptions, and understands common words for the same thing (cert and certificate, IDOR and authorization). Each result has the page's URL, a `markdown` URL that's easier for an assistant to read, and the sections that matched, with links straight to them.

| Argument | Description |
|---|---|
| `query` | A question or keywords, such as `install certificate on android`. Required. |
| `limit` | Most pages to return, 5 by default and at most 20. |

For tools that read docs on their own, the whole site is also published for AI:

| URL | Contents |
|---|---|
| `https://docs.subcloak.com/llms.txt` | An index of every page with a one-line description, in the [llms.txt](https://llmstxt.org) format. |
| `https://docs.subcloak.com/llms-full.txt` | Every page in one Markdown file. |
| Any page's URL with `.md` instead of the final `/` | That page as Markdown. |

## From the command line

`cloakctl` has the same features, for scripts, CI and agents that don't use MCP.

```bash title="Terminal"
cloakctl skills list                    # each skill and whether it's installed for Claude Code
cloakctl skills install claude codex    # install or update for Claude Code and Codex
cloakctl skills install project         # this project only (.claude/skills)
cloakctl skills install ~/my-agent/skills
cloakctl skills show cloak-proxy-debug-traffic
cloakctl skills uninstall claude
```

`cloakctl setup TARGET` prints the capture checklist, and `--apply STEP` does a step. It asks the running app when there is one; without it, it works out what it can itself, which covers simulators, Android devices and terminal variables:

```bash title="Terminal"
cloakctl setup ios_simulator
cloakctl setup ios_simulator --apply simulator-certificate   # no app or password needed
cloakctl setup android --apply android-proxy --serial emulator-5554
cloakctl setup mac --app ShopApp --host api.example.com --json
```

It exits with `0` when every required step is done, `2` when some are still to do, and `1` on an error, so a CI job can install the certificate in a booted simulator and then check that setup is complete before running UI tests through `cloakctl run`.

`cloakctl docs-search QUERY` searches the docs:

```text
$ cloakctl docs-search install certificate on android --limit 1
Android  (Devices and runtimes)
  https://docs.subcloak.com/cloak-proxy/devices/android/
  Capture an Android emulator or USB device with one click through adb, install the Cloak Proxy certificate, and let your app trust user certificates.
  › Install the certificate  https://docs.subcloak.com/cloak-proxy/devices/android/#install-the-certificate
```

## Limits and safety

- **Skills are instructions, not permissions.** They make an agent better at using Cloak Proxy; your client's approval prompts still decide which tools run.
- **Redaction covers credentials, not all personal data.** Names, emails, addresses and IDs stay readable so an assistant can debug. Don't point an assistant at traffic you aren't allowed to share with its model provider.
- **Some setup steps always need you.** Trusting the certificate on the Mac, on an iPhone and on Android, and setting an iPhone's Wi-Fi proxy, can only be done by you. The tools say exactly what to do.
- **Simulators must be booted** for `simctl` to add the certificate, and apps must be relaunched to pick it up. Pinned apps still refuse decrypted traffic; the [Doctor](https://docs.subcloak.com/cloak-proxy/capture/doctor/) tells you when that happens.
- **Android setup needs adb** from the Android platform tools, and your app's debug build must trust user certificates.
- **The docs index is as current as your copy of Cloak Proxy.** For pages added since, read `llms.txt`.

## Related

  - [MCP server](https://docs.subcloak.com/cloak-proxy/automation/mcp-server/): Connect Claude Code, Claude Desktop, Cursor or VS Code to Cloak Proxy.
  - [MCP tools reference](https://docs.subcloak.com/cloak-proxy/automation/mcp-tools-reference/): Every tool and argument, including capture_setup, install_certificate and search_docs.
  - [Doctor](https://docs.subcloak.com/cloak-proxy/capture/doctor/): Why an app's traffic isn't showing, with the evidence and a fix.
  - [Redaction](https://docs.subcloak.com/cloak-proxy/sessions/redaction/): What is removed from exports and recordings.