New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Vpn Troubleshoot

by Sergei-thinker in Sergei-thinker/vpn-setup

VPN troubleshooting decision tree. An agent skill from Sergei-thinker/vpn-setup.

MITAuto-check: notesDevOps & Cloud

Install Vpn Troubleshoot

skills CLI
$ npx skills add Sergei-thinker/vpn-setup --skill vpn-troubleshoot -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Sergei-thinker/vpn-setup vpn-troubleshoot --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Sergei-thinker/vpn-setup.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/vpn-troubleshoot .claude/skills/vpn-troubleshoot && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
vpn-troubleshoot
GitHub stars
189
Token cost
~2.2k tokens
SKILL.md length
1,193 words
Files
1
Skills in repo
4
Repo updated
First seen
Licence
MIT

At a glance

VPN troubleshooting decision tree. An agent skill from Sergei-thinker/vpn-setup.

  • Works in 6 steps: Can we SSH to the server? → Is xray running? → VPN connects from client? → …
  • User reports VPN problems: VPN not working
  • SKILL.md covers When to Use, The Iron Law, Decision Tree and Relay VPS Troubleshooting, plus 1 more section
  • Calls python and bash; needs VPN_SSH_KEY

What it does

Vpn Troubleshoot is an agent skill from Sergei-thinker/vpn-setup. VPN troubleshooting decision tree. Use when user reports VPN problems: 'VPN not working', 'can't connect', 'stopped working', 'no internet through VPN', 'slow VPN', 'troubleshoot'. Also use when deployment fails.

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in DevOps & Cloud, covering Deployment. It works with Python. The repository describes itself as: Multi-layer VPN (VLESS Reality + Yandex Cloud Relay + WebRTC) for bypassing Russian internet censorship. Automated deployment via Claude Code. The licence is MIT.

When your agent uses it

  • User reports VPN problems: VPN not working
  • Stopped working
  • No internet through VPN
  • Deployment fails

Example prompts

  • “VPN not working”
  • “t connect”
  • “stopped working”
  • “/vpn-troubleshoot”

Requirements

  • Python 3
  • A credential in VPN_SSH_KEY

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Can we SSH to the server?
  2. Is xray running?
  3. VPN connects from client?
  4. Internet works through VPN?
  5. Performance Issues
  6. Works on Wi-Fi, Not on LTE

What it can do on your machine

Read from SKILL.md and the folder at commit 486bf50. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • python
    • bash

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • VPN_SSH_KEY

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Vpn Troubleshoot loads about 2.2k tokens when it runs. Until then it costs about 57 tokens; SKILL.md has 1,193 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~57
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:38
    | "No such file: .env" | Missing config | Tell user to create `.env` from `.env.example` |
  • NoteMentions a .env fileSKILL.md:42
    1. Check current SSH port in `.env` (`VPN_SSH_PORT`)
  • NoteMentions a .env fileSKILL.md:44
    - Change `VPN_SSH_PORT=49152` in `.env`
  • NoteMentions a .env fileSKILL.md:52
    1. Check `.env` for `VPN_SSH_KEY` and `VPN_SSH_PASS`
  • NoteMentions a .env fileSKILL.md:60
    2. Try ping: `ping -c 3 <VPN_HOST from .env>`
  • NoteMentions a .env fileSKILL.md:181
    2. Fill relay credentials in `.env` (`SWEDEN_RELAY_UUID`, `SWEDEN_RELAY_PUBKEY`, `SWEDEN_RELAY_SID`)
  • NoteMentions a .env fileSKILL.md:182
    Sina ~100 RUB/mo), fill `RELAY_HOST` in `.env`

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Sergei-thinker/vpn-setup at commit 486bf50, republished under its MIT licence (© Sergei-thinker). 1,193 words, ~2,202 tokens.

Download SKILL.mdSave it as .claude/skills/vpn-troubleshoot/SKILL.md (or your agent's skills folder).
name
vpn-troubleshoot
description
VPN troubleshooting decision tree. Use when user reports VPN problems: 'VPN not working', 'can't connect', 'stopped working', 'no internet through VPN', 'slow VPN', 'troubleshoot'. Also use when deployment fails.

VPN Troubleshooting

Decision tree for diagnosing and fixing VPN infrastructure problems. For beginners — specific commands and solutions, not abstract methodology.

When to Use

Use when the user reports ANY VPN problem:

  • "VPN not working", "can't connect", "stopped working"
  • "No internet", "slow speed", "works on Wi-Fi but not LTE"
  • Deployment script failed
  • Any error message related to VPN

The Iron Law

DIAGNOSE BEFORE FIXING. RUN THE COMMAND BEFORE CLAIMING THE RESULT.

Never suggest a fix without first running diagnostics. Never claim "fixed" without verifying.

Decision Tree

Step 1: Can we SSH to the server?

Run: python ssh_exec.py status

ResultDiagnosisAction
Success (shows xray info)SSH worksGo to Step 2
"Connection refused"Port blocked or SSH not runningGo to Branch A
"Authentication failed"Wrong credentialsGo to Branch B
"Connection timed out"VPS down or IP wrongGo to Branch C
"No such file: .env"Missing configTell user to create .env from .env.example
Branch A: Connection Refused
  1. Check current SSH port in .env (VPN_SSH_PORT)
  2. If port is 22: TSPU often blocks port 22 to foreign IPs
    • Change VPN_SSH_PORT=49152 in .env
    • Retry python ssh_exec.py status
  3. If port is 49152 and still refused:
    • VPS firewall may block it, or SSH service is down
    • Ask user to log into VPS provider's web console and check
Branch B: Authentication Failed
  1. Check .env for VPN_SSH_KEY and VPN_SSH_PASS
  2. If using key: verify the key file exists at the specified path
  3. If using password: ask user to verify password is correct (no extra spaces)
  4. Common issue: key is for a different server (user changed VPS but kept old key)
Branch C: Connection Timed Out
  1. Ask user: "Is your VPS running? Check in your provider's dashboard."
  2. Try ping: ping -c 3 <VPN_HOST from .env>
  3. If ping works but SSH doesn't: firewall blocks SSH port
  4. If ping fails: VPS is down, IP is wrong, or ISP blocks the IP entirely
Step 2: Is xray running?

From ssh_exec.py status output, check xray process status.

ResultAction
xray: "running"Go to Step 3
xray: "stopped" or not foundRestart: python ssh_exec.py restart
After restart still not runningCheck logs: python ssh_exec.py logs

Common log errors:

  • "failed to read config" — corrupted xray config. Re-deploy: python ssh_exec.py deploy quick-rebuild.sh
  • "address already in use" — port conflict. Run: python ssh_exec.py exec "ss -tnlp | grep -E '443|8443|2053'"
  • "certificate not found" — SSL cert missing. Re-deploy will regenerate it
Step 3: VPN connects from client?

Ask user: "Does your VPN client (v2rayN/Shadowrocket/v2rayNG) show 'Connected'?"

ResultAction
Yes, connectedGo to Step 4
No, cannot connect at allGo to Branch D
Connects then disconnectsGo to Branch E
Branch D: Client Cannot Connect
  1. Check which port: ask which VLESS URI the user imported (port 443, 8443, or 2053)
  2. Try another port:
    • If using 443, try 8443 or 2053
    • Each port uses a different SNI (microsoft.com, google.com, apple.com)
  3. If NO port works:
    • Server IP is likely blocked by TSPU
    • Solution: deploy Layer 1 relay on a Russian VPS (Timeweb/VDSina/Selectel)
    • Run: python ssh_exec.py deploy deploy-relay-sweden.sh (prepare main VPS)
    • Then rent a RU VPS and run: bash deploy-relay.sh --sweden-ip ... --sweden-uuid ... --sweden-pubkey ... --sweden-sid ...
    • NB: Yandex Cloud does NOT bypass white lists (AS Yandex.Cloud LLC != AS YANDEX LLC); use generic RU provider
    • See CLAUDE.md "Layer 1" section for full instructions
  4. Client-specific issues:
    • v2rayN: ensure TUN mode is ON (toggle at bottom of window)
    • Shadowrocket: ensure "Global Routing" is set to "Proxy"
    • v2rayNG: ensure VPN permission is granted
Branch E: Connects Then Disconnects
  1. Check logs: python ssh_exec.py logs -n 50
  2. Look for repeated connection/disconnection patterns
  3. Common cause: TSPU actively probing the connection
    • Try different port (8443, 2053)
    • Enable TLS fragmentation in client (100-400 bytes)
Step 4: Internet works through VPN?

Ask user: "Open 2ip.ru in your browser. What country does it show?"

ResultAction
Shows VPS country (Sweden/Netherlands/etc)VPN works correctly. Go to Step 5 for optimization
Shows RussiaGo to Branch F
Page doesn't load at allGo to Branch G
Branch F: 2ip.ru Shows Russia (VPN not routing traffic)
  1. TUN mode check (critical!):
    • v2rayN: "Enable Tun" toggle must be ON (bottom of window). Without TUN, only apps configured for proxy work, browser goes direct
    • Hiddify: DO NOT use Hiddify — switch to v2rayN (Hiddify has known QUIC/UDP leaks, see docs/05-security.md)
  2. Split routing check:
    • 2ip.ru IS a Russian site, so with split routing enabled it SHOULD show Russia
    • Test with a non-Russian site instead: whatismyipaddress.com or ifconfig.me
    • If non-Russian sites show VPS IP: split routing works correctly
  3. Core type (v2rayN only):
    • Settings -> Core Type -> select "sing-box" (not Xray)
    • Xray core has known issues with QUIC through SOCKS5
Show full SKILL.md (427 more words)Show less
Branch G: No Internet At All
  1. DNS issue?
    • Try accessing a site by IP directly in browser
    • If works by IP but not by domain: DNS resolution broken
    • Fix: set DNS in client to 1.1.1.1 or 8.8.8.8
  2. Routing issue?
    • Disable split routing temporarily (use "Global" mode)
    • If Global mode works: split routing config has errors
  3. Server-side DNS:
    • Run: python ssh_exec.py exec "nslookup google.com"
    • If fails: python ssh_exec.py exec "systemctl restart systemd-resolved"
Step 5: Performance Issues
SymptomDiagnosticFix
Slow overallpython ssh_exec.py exec "sysctl net.ipv4.tcp_congestion_control"Should be "bbr". If not: python ssh_exec.py deploy quick-rebuild.sh will enable it
Slow on LTEMobile operator throttlingEnable TLS fragmentation (100-400 bytes) in client settings
YouTube buffersCheck core type in v2rayNSwitch to sing-box core. QUIC/UDP may be broken with Xray core
Slow on Wi-Fi, fast on LTEUnusual, likely ISP issueTry Cloudflare DNS (1.1.1.1) in router settings
Step 6: Works on Wi-Fi, Not on LTE

This is a specific and common problem caused by mobile operators using "white lists" (only allowing traffic to known Russian IPs).

Solution: Deploy Layer 1 (Relay on Russian VPS)

IP ranges of Russian VPS providers (Timeweb, VDSina, Selectel) may be in the white list of mobile operators — but this is NOT guaranteed. You must verify after deploy.

NB: Yandex Cloud was previously recommended here; removed 2026-04-17 after Habr 1021160 comments (@paxlo/@aax/@Varpun) proved AS Yandex.Cloud LLC (user VMs) != AS YANDEX LLC (Yandex services) — TSPU filters them separately, YC VMs get blocked under active white lists.

  1. Prepare main VPS: python ssh_exec.py deploy deploy-relay-sweden.sh
  2. Fill relay credentials in .env (SWEDEN_RELAY_UUID, SWEDEN_RELAY_PUBKEY, SWEDEN_RELAY_SID)
  3. Rent a Russian VPS (Timeweb Cloud ~80 RUB/mo, VDSina ~100 RUB/mo), fill RELAY_HOST in .env
  4. Deploy relay: bash deploy-relay.sh --sweden-ip $SWEDEN_VPS_IP --sweden-uuid $SWEDEN_RELAY_UUID --sweden-pubkey $SWEDEN_RELAY_PUBKEY --sweden-sid $SWEDEN_RELAY_SID
  5. Import the relay VLESS URI into client
  6. Test on LTE — if blocked, try a different Russian provider

See CLAUDE.md "Layer 1" section for details.

Relay VPS Troubleshooting

If user has Layer 1 (relay) deployed and it stops working:

  1. python ssh_exec.py -t relay status — check relay xray
  2. python ssh_exec.py -t relay logs — check relay logs
  3. python ssh_exec.py -t relay restart — restart relay
  4. bash monitor-relay.sh — health check both VPSes
  5. Verify main VPS accepts relay connections: python ssh_exec.py exec "ss -tnp | grep 10443"

Communication Rules

  • Communicate in Russian
  • Run diagnostic commands BEFORE suggesting fixes
  • Show the user what each command found (summarize, don't dump raw output)
  • If a fix doesn't work, go back to diagnostics, don't keep guessing
  • For complex issues, reference docs/08-operations.md for additional guidance

© Sergei-thinker, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/vpn-troubleshoot of Sergei-thinker/vpn-setup.

Open the folder on GitHubat commit 486bf50

Compare with similar skills

Vpn Troubleshoot next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Vpn Troubleshoot compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Vpn Troubleshoot this skillSergei-thinker/vpn-setup189—~2.2kAutomated safety check: NotesMIT
AWS Cdk Developmentzxkane/aws-skills3672 repos~2.5kAutomated safety check: PassMIT
Azure Architecture Autopilotgithub/awesome-copilot40k1 repos~1.9kAutomated safety check: PassMIT
Blocks Networkblocksnetwork/blocks-sdk146—~2.3kAutomated safety check: NotesProprietary
DDNS Build and Release MaintenanceNewFuture/DDNS4.7k—~444Automated safety check: PassMIT
Generate Ors Envadithya-s-k/FineEnvs461—~2.3kAutomated safety check: NotesApache-2.0

Similar skills

  • AWS Cdk Development

    zxkane/aws-skills

    AWS Cloud Development Kit (CDK) expert for building cloud infrastructure with TypeScript/Python.

    367 GitHub starsUsed in 2 repos~2.5k tokens
    DevOps & CloudAuto-check passed

  • Azure Architecture Autopilot

    github/awesome-copilot

    Official

    Designs Azure infrastructure from a natural-language description, or diagrams an existing resource group, then refines the design through conversation and deploys it with Bicep.

    40k GitHub starsUsed in 1 repo~1.9k tokens
    DevOps & CloudAuto-check passed

  • Blocks Network

    blocksnetwork/blocks-sdk

    Modify, validate, run, register, publish, consume, and troubleshoot agents on Blocks Network.

    146 GitHub stars~2.3k tokensUpdated 2 days ago
    DevOps & CloudAuto-check: notes

  • DDNS Build and Release Maintenance

    NewFuture/DDNS

    Maintains the DDNS project's GitHub Actions, Docker and Nuitka builds, packaging and release preparation without touching publishing credentials.

    4.7k GitHub stars~444 tokensUpdated 3 days ago
    DevOps & CloudAuto-check passed

  • Generate Ors Env

    adithya-s-k/FineEnvs

    Builds an Open Reward Standard (ORS) variant of an RL environment using the official openreward Python package.

    461 GitHub stars~2.3k tokensUpdated 2 days ago
    DevOps & CloudAuto-check: notes

  • Google Agents CLI Deploy

    pifferologo/cloud-agents-cli

    This skill should be used when the user wants to "deploy an agent", "deploy my ADK agent", "set up CI/CD", "configure secrets", "troubleshoot a deployment", or needs guidance on Agent Runtime, Cloud…

    129 GitHub starsUsed in 1 repo~6k tokens
    DevOps & CloudAuto-check passed

More from Sergei-thinker/vpn-setup

  • Vpn Deploy

    Sergei-thinker/vpn-setup

    Guided VPN deployment wizard. An agent skill from Sergei-thinker/vpn-setup.

    189 GitHub stars~1.4k tokensUpdated 5 mo ago
    Auto-check: notes

  • Vpn Security Check

    Sergei-thinker/vpn-setup

    Infrastructure security audit for VPN server. An agent skill from Sergei-thinker/vpn-setup.

    189 GitHub stars~1.5k tokensUpdated 5 mo ago
    Auto-check: notes

  • Vpn Verify

    Sergei-thinker/vpn-setup

    Post-deployment verification checklist for VPN. An agent skill from Sergei-thinker/vpn-setup.

    189 GitHub stars~1k tokensUpdated 5 mo ago
    Auto-check: notes

Works with

Categories

Questions about Vpn Troubleshoot

What does Vpn Troubleshoot do?

VPN troubleshooting decision tree. An agent skill from Sergei-thinker/vpn-setup. Vpn Troubleshoot is an agent skill from Sergei-thinker/vpn-setup. VPN troubleshooting decision tree.

When should I use Vpn Troubleshoot?

Vpn Troubleshoot fits situations like: user reports VPN problems: VPN not working; stopped working; no internet through VPN; deployment fails.

How do I install Vpn Troubleshoot in Claude Code?

Run `npx skills add Sergei-thinker/vpn-setup --skill vpn-troubleshoot -a claude-code`. Or copy the skill folder (.claude/skills/vpn-troubleshoot in Sergei-thinker/vpn-setup) into .claude/skills/vpn-troubleshoot in your project. Claude Code loads it when a task matches its description.

How do I install Vpn Troubleshoot in Codex?

Run `npx skills add Sergei-thinker/vpn-setup --skill vpn-troubleshoot -a codex`. Or copy the skill folder (.claude/skills/vpn-troubleshoot in Sergei-thinker/vpn-setup) into .agents/skills/vpn-troubleshoot in your project. Codex loads it when a task matches its description.

Can I use Vpn Troubleshoot in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Sergei-thinker/vpn-setup --skill vpn-troubleshoot -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/vpn-troubleshoot, .gemini/skills/vpn-troubleshoot, .github/skills/vpn-troubleshoot and .opencode/skills/vpn-troubleshoot in your project.

What does Vpn Troubleshoot need to run?

Going by SKILL.md and its folder, Vpn Troubleshoot needs the command-line tools its instructions call (python and bash) and credentials named VPN_SSH_KEY. Our summary lists: Python 3; A credential in VPN_SSH_KEY.

Does Vpn Troubleshoot access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Vpn Troubleshoot safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Vpn Troubleshoot use?

Vpn Troubleshoot is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Vpn Troubleshoot use?

About 2.2k tokens (SKILL.md is roughly 8.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Vpn Troubleshoot?

Skills that share tags, products or a category with Vpn Troubleshoot: AWS Cdk Development (zxkane/aws-skills, 367 stars), Azure Architecture Autopilot (github/awesome-copilot, 40k stars), Blocks Network (blocksnetwork/blocks-sdk, 146 stars) and DDNS Build and Release Maintenance (NewFuture/DDNS, 4.7k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Vpn Troubleshoot?

Sergei-thinker (a GitHub user) maintains it in Sergei-thinker/vpn-setup, which has 189 GitHub stars. The repository holds 4 skills in this directory. The repository was last updated on April 17, 2026.

Source: Sergei-thinker/vpn-setup on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.