SublinkPro Manager

SublinkPro AI Skill

Control your SublinkPro instance through natural language. This skill lets an AI assistant call the SublinkPro API directly, so you can manage nodes, subscriptions, shares, airports, and templates without opening the web UI.

Installation

1. Copy this directory into your AI agent's skills directory. The exact path depends on your tool — for Claude Code it is ~/.claude/skills/sublinkpro:

   cp -r skill-sublinkpro ~/.claude/skills/sublinkpro
   # or symlink if you cloned the repo:
   ln -s /path/to/sublinkE/skill-sublinkpro ~/.claude/skills/sublinkpro

   For other agents, place the directory wherever that tool loads skills from.

2. Set environment variables:

   export SUBLINK_BASE_URL=http://localhost:8000  # your SublinkPro server address
   export SUBLINK_API_KEY=prefix_xxx_yyy          # your API key

3. Get an API key:

   • Open SublinkPro web UI
   • Go to Settings → Access Keys
   • Click Create (or Add)
   • Copy the key (shown only once) and set SUBLINK_API_KEY

How to Use

You don't need to know the API, the parameter names, or what data already exists. Just say what you want in plain language and the assistant guides you the rest of the way. If you're not sure what's possible, simply ask "what can I do?" and you'll get a menu.

Example openers:

• "I want to add a node" → the assistant walks you through it step by step
• "Add this node: vless://..."
• "Help me build a new subscription"
• "Show me all my subscriptions"
• "Create a share link"
• "Import an airport"
• "Edit the 'ACL4SSR' template to block ads"
• "Show dashboard stats"
• "How does the smart tag system work?" → the assistant fetches and explains the relevant documentation
• "I don't have SublinkPro yet — help me set it up" → the assistant guides you through deploying it (see Deploy below)

Under the hood the assistant calls the SublinkPro REST API with curl (or the optional Python helper). Authentication and API quirks are handled for you.

Interaction Style: Guided by Default

This is the most important section. The agent must treat every request as a guided, conversational flow — never a one-shot command that fails on a missing field. Users generally do not know the API, the parameter names, or what data already exists. Lead them.

Core rules for the agent:

1. Never guess or invent required values. If a required field is missing, either discover it (rule 2) or ask the user — do not fabricate names, IDs, links, or URLs.
2. Discover before you ask the user to type. Before asking "which group / which subscription / which node?", call the matching GET endpoint and present the existing options as a short numbered list so the user can pick a number instead of typing. Examples:
   • which group → GET /api/v1/nodes/groups
   • which subscription → GET /api/v1/subcription/get
   • which nodes → GET /api/v1/nodes/selector (compact id+name list)
   • which airport → GET /api/v1/airports
   • which template → GET /api/v1/template/get
   • which country / protocol / source filters → GET /api/v1/nodes/countries / /protocols / /sources
3. Collect required fields one step at a time, in plain language. Don't dump a 15-field form on the user. Ask for what's required first; then offer optional refinements as a single "want to set any filters/options? (or say 'no' to skip)" step.
4. Explain choices in the user's terms. When a field has fixed options (e.g. share expire_type: never / N days / specific date), describe them in words and let the user choose, then map to the correct value yourself.
5. Always confirm before any write (POST/PUT/DELETE). Show a plain-language summary of exactly what will happen ("I'll create a subscription named 'US Servers' with these 3 nodes, no filters") and wait for a yes.
6. Confirm extra carefully for destructive or bulk actions — delete, batch-delete, batch-update-*, share token refresh, airport delete. Show the count and the names/IDs that will be affected, and make clear it can't be easily undone.
7. Report results in plain language, not raw JSON. On success, say what was created/changed and surface the useful bits (e.g. the share URL). On error, read the msg, explain it simply, and propose the fix.
8. Offer the logical next step. After adding nodes → offer to put them in a subscription. After creating a subscription → offer to create a share link. After importing an airport → offer to pull its nodes now.
9. Respect mixed content types and the envelope (see Technical Reference). The user never sees --form vs --json; the agent handles it.

Capability Menu

When the user asks "what can you do", "help", or seems unsure where to start, present this menu and ask which one they'd like:

• Nodes — add a node (paste a link / WireGuard / Clash YAML), list or search nodes, move nodes between groups, set country/source, delete nodes
• Subscriptions — build a new subscription, edit one, preview which nodes it will output, sort nodes, copy a subscription, delete one
• Sharing — create a share link for a subscription, set expiration, list/refresh/disable share links, view access logs, fetch the actual subscription output
• Airports — import an airport (URL + schedule), pull nodes now, list airports, edit/batch-edit, refresh usage, delete
• Templates — list templates, edit a template by hand, or use AI template editing (describe a change in words → generate → review → apply)
• Chain proxy — view/add chain-proxy rules on a subscription
• Tags — list tags, create rules, apply tagging
• Tasks — view running/finished tasks (speed tests etc.), stop a task
• Dashboard — node/subscription counts, fastest node, country/protocol stats, system stats
• Documentation & help — explain features, configuration, installation, or troubleshooting by fetching the project's official docs (smart tags, speed tests, chain proxy, MFA, etc.)
• Deploy / install SublinkPro — stand up a new instance via docker, docker-compose, or the install script, locally or on a remote host (see the Deploy workflow below)
• Manage an instance — check status / view logs, update to the latest version, or uninstall

Documentation & Help

When the user asks how a feature works, how to configure something, what a feature does, or how to troubleshoot — fetch the project's official documentation from GitHub and answer from it. Do not invent or paraphrase from memory. The documentation is always current and authoritative.

How to use the docs:

1. Match the user's question to a topic in reference/docs.md (the documentation map).
2. Fetch the relevant doc's raw URL from GitHub using your web-fetch capability.
3. Read it and answer in the user's language — summarize and quote the doc directly.
4. Cite the human-readable GitHub page URL so the user can read the full doc themselves.
5. If you can't fetch the doc (offline / no web access), tell the user and give them the GitHub link to read it themselves — never fabricate the content.

Topics covered: installation & configuration, smart tags, speed tests, unlock checks, chain proxy, AI template editing, airport management, subscription sharing, host management, Cloudflare Tunnel, Telegram bot, MFA, script support, development guide, protocol extensions, internationalization.

When docs don't solve the problem:

If the documentation can't answer the user's question, or they've tried the documented solution and it still doesn't work, guide them to escalate:

• Submit a GitHub issue: https://github.com/ZeroDeng01/sublinkPro/issues — for bug reports, feature requests, or questions the docs don't cover.
• Contact the author via Telegram: https://t.me/SublinkPro_ChatMeBot — for real-time help or urgent issues.

Phrase it like: "The docs cover X but your specific case (Y) isn't documented. I'd recommend opening a GitHub issue at [link] or reaching out to the author on Telegram at [link] — they can help diagnose this."

Technical Reference (for the AI agent)

How to Call the API

Call the REST API with curl — it ships on virtually every macOS, Windows 10+, and Linux system, so it's the most portable choice and the default. (A Python convenience wrapper, scripts/sublink.py, also exists for hosts that have Python 3 — see the end of this section — but it is optional.)

First ensure the env vars are set (check before calling; if missing, guide the user — see "Error Handling Playbook"):

export SUBLINK_BASE_URL=http://localhost:8000
export SUBLINK_API_KEY=prefix_xxx_yyy

Each endpoint in reference/api.md is tagged with a content type. Map it to curl like this:

Which endpoints are form vs JSON:

• form (c.PostForm in backend): auth login, node add/update, subscription add/update, template add/update/delete.
• JSON (c.ShouldBindJSON): access keys, node batch operations, subscription preview, subscription sort/batch-sort, chain rules, airports, tags (except /tags/delete which is a query param), scripts, hosts, geoip, group-sort, node-check, settings, AI template endpoints.
• query: all GET list/filter params, plus several deletes and a few POSTs (copy, refresh, trigger).

Judge success by the body's code, not the HTTP status — a failure often returns HTTP 200 with code:500. Parse the JSON, check .code (200 = ok; 400/403/404/500 = failure, read .msg and translate it). The #1 cause of 参数错误 failures is a form-vs-JSON mismatch or wrong field casing — re-check the endpoint's tag and exact field names in reference/api.md before retrying.

Examples:

# Get version (public, no key needed)
curl -s "$SUBLINK_BASE_URL/api/v1/version"

# Add a node (form)
curl -s -H "X-API-Key: $SUBLINK_API_KEY" \
  --data-urlencode 'link=vless://...' --data-urlencode 'group=US' \
  "$SUBLINK_BASE_URL/api/v1/nodes/add"

# Create an airport (JSON)
curl -s -H "X-API-Key: $SUBLINK_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"MyAirport","url":"https://...","cronExpr":"0 */6 * * *","enabled":true}' \
  "$SUBLINK_BASE_URL/api/v1/airports"

# List nodes (GET + query)
curl -s -H "X-API-Key: $SUBLINK_API_KEY" \
  "$SUBLINK_BASE_URL/api/v1/nodes/get?page=1&pageSize=50"

# Fetch subscription output (raw — uses a share token, not the API key)
curl -s "$SUBLINK_BASE_URL/c/?token=<shareToken>"

Optional helper script. If Python 3 is present, scripts/sublink.py does the auth header, form-vs-JSON routing, and code check for you, exiting non-zero on failure. The --form/--json/--query/--raw flags used throughout this doc map directly to the curl table above:

python scripts/sublink.py GET  /api/v1/nodes/get --query page=1 --query pageSize=50
python scripts/sublink.py POST /api/v1/nodes/add --form link='vless://...' --form group='US'
python scripts/sublink.py POST /api/v1/airports --json name='MyAirport' --json enabled=true
python scripts/sublink.py GET  /c/ --query token='<shareToken>' --raw

Use whichever is available on the host — curl first, the script if you prefer and Python is installed. Throughout the workflows below, an endpoint marked (--form) / (--json) just means "use that content type" — apply it with either tool.

Key API Patterns

Base URL: All routes are under /api/v1/... (except /c/ for subscription consumption)

Response envelope: Every JSON response has {code, msg, data} where code: 200 = success, code: 500 = error

Subscription group spelling: /api/v1/subcription (missing second 's')

Demo mode: Write endpoints with DemoModeRestrict are blocked in demo mode

Share tokens vs API keys: Subscription consumption (/c/?token=...) uses share tokens (from POST /api/v1/shares/add), NOT the API key

Full Endpoint Catalog

See reference/api.md for the complete list of endpoints with parameters and response shapes.

Field Discovery Map (turn blanks into multiple-choice)

This is how the skill replaces complex web-UI widgets. In the web UI, fields like "Clash template", "nodes", "group", "country filter" are dropdowns, multi-selects, and visual builders. In this skill, the agent reproduces that experience by calling a discovery endpoint, showing the results as a numbered list, and letting the user pick a number. The agent never asks the user to free-type a value that can be discovered, and never invents one.

Whenever you need one of these values, call its source first and present choices:

If a discovery call returns an empty list (e.g. no groups yet), say so and offer the alternative (e.g. "you have no groups — want to pick individual nodes instead, or create the group while adding?").

Field Tiers (don't dump everything at once)

For multi-field resources (subscriptions especially), split fields into three tiers and walk them in order. Never present all fields at once.

1. Required — ask first, can't proceed without. (Subscription: name + at least one of nodeIds/groups.)
2. Common optional — offer as a short, skippable batch with sensible defaults. (Subscription: template config, country/protocol filter, DelayTime, MinSpeed, UpdateInterval.)
3. Advanced — only mention they exist; set only if the user explicitly asks. These include the structured-JSON builder fields (DeduplicationRule, NodeNamePreprocess, UnlockRules) which mirror visual builders in the UI and are easy to malform. Do not hand-craft their JSON from a vague request; if the user wants them, ask precise questions or point them to the web UI for that specific widget, and confirm the exact JSON before sending.