How do I install the Surge skill?

Run npx skillmds@latest add aioneas/surge in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Surge safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Surge?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Surge free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Aioneas (@aioneas) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Surge by aioneas — Agent Skill

Name: Surge
Rating: 4.2 (5 reviews)
Author: Aioneas

Surge

Operate and troubleshoot Surge via surge-cli, including command discovery, runtime diagnostics, state inspection (dump/watch/test), and environment mutation with set key-paths. Use when a task asks to control Surge behavior, inspect live status, adjust policy/runtime switches, or automate Surge operations from CLI.

Aioneas Updated Sep 22, 2026

File contents

Surge CLI Ops

Use this skill to run Surge operations safely and consistently through surge-cli.

Startup

Resolve executable path in this order:
- surge-cli in PATH
- /Applications/Surge.app/Contents/Applications/surge-cli
Prefer JSON output with --raw for machine parsing.
If operating on remote instances, add --remote password@host:port.

Baseline Context Workflow

Before mutating runtime settings, collect baseline state:

surge-cli --raw environment
surge-cli --raw dump policy
surge-cli --raw dump profile

After changes, re-run the relevant read commands to verify effects.

Mutation Rules

When using set:

Use minimal key-path deltas only.
Batch related updates in one command when possible.
Treat <nil> and (null) as null assignments.
Re-check environment immediately after mutation.

Examples:

surge-cli --raw set ProxyMode=2
surge-cli --raw set ProxyGroupSelection.Proxy=HK
surge-cli --raw set AutoPolicyGroupOverride.Streaming=<nil>

Streaming Command Handling

For streaming commands (for example diagnostics/bandwidth tests):

Process incremental chunks.
Respect completion markers (hasMore=false or command-specific completion payload).
Do not assume a single response frame.

Platform and Capability Notes

Some commands are platform-limited (for example certain device-management and profile-edit commands).
Validate capability and platform before execution in automation workflows.

Reference

Read detailed command semantics, full command list, and environment key definitions from:

Command Reference

---name: surgedescription: Operate and troubleshoot Surge via surge-cli, including command discovery, runtime diagnostics, state inspection (dump/watch/test), and environment mutation with set key-paths. Use when a task asks to control Surge behavior, inspect live status, adjust policy/runtime switches, or automate Surge operations from CLI.---# Surge CLI OpsUse this skill to run Surge operations safely and consistently through `surge-cli`.## Startup1. Resolve executable path in this order: - `surge-cli` in `PATH` - `/Applications/Surge.app/Contents/Applications/surge-cli`2. Prefer JSON output with `--raw` for machine parsing.3. If operating on remote instances, add `--remote password@host:port`.## Baseline Context WorkflowBefore mutating runtime settings, collect baseline state:1. `surge-cli --raw environment`2. `surge-cli --raw dump policy`3. `surge-cli --raw dump profile`After changes, re-run the relevant read commands to verify effects.## Mutation RulesWhen using `set`:1. Use minimal key-path deltas only.2. Batch related updates in one command when possible.3. Treat `<nil>` and `(null)` as null assignments.4. Re-check `environment` immediately after mutation.Examples:```bashsurge-cli --raw set ProxyMode=2surge-cli --raw set ProxyGroupSelection.Proxy=HKsurge-cli --raw set AutoPolicyGroupOverride.Streaming=<nil>```## Streaming Command HandlingFor streaming commands (for example diagnostics/bandwidth tests):1. Process incremental chunks.2. Respect completion markers (`hasMore=false` or command-specific completion payload).3. Do not assume a single response frame.## Platform and Capability Notes1. Some commands are platform-limited (for example certain device-management and profile-edit commands).2. Validate capability and platform before execution in automation workflows.## ReferenceRead detailed command semantics, full command list, and environment key definitions from:- [Command Reference](references/command-reference.md)

Frequently asked questions