X5 Protocol Client

Send X5 protocol API requests from the terminal. Use this skill whenever the user wants to test, call, or send X5 API requests; parse .x5 files; generate X5...

Security Scan

The skill's requests, instructions, and included script are coherent with its stated purpose (sending and parsing X5 protocol requests); it doesn't request unrelated credentials or perform unexplained actions.

Purpose & Capability

Name/description match what the package implements: parsing .x5 files, generating the X5 MD5 signature, Base64-encoding the envelope, and POSTing to user-provided URLs. No unrelated binaries, env vars, or config paths are requested.

Instruction Scope

SKILL.md instructs the agent to run the included Python CLI against .x5 files or inline parameters. The instructions are scoped to building and sending X5 requests, listing requests, generating cURL, or showing dry-run payloads. The agent is allowed to read files the user points it at (e.g., --file, --body-file), which is expected for this tool.

Install Mechanism

No install spec or external downloads; this is an instruction-only skill with an included Python script. No archive extraction or network install occurs as part of installation.

Credentials

The skill does not require environment variables or credentials beyond appid/appkey provided inline or in .x5 files. The code does not read unrelated environment variables or global config paths.

Persistence & Privilege

always:false (no forced inclusion). The skill does not request persistent system privileges or modify other skills' configs. It runs as a CLI tool when invoked.

Assessment

This skill appears to do exactly what it claims: create and send X5 protocol requests. Before using it, review any .x5 files you didn’t author—they can contain appid/appkey values and arbitrary request bodies and headers that will be sent to the URLs you provide. Do not supply sensitive credentials to untrusted .x5 files or remote endpoints. If you want extra assurance, run the script locally on test endpoints or inspect the full script (it’s included) to confirm behavior; the script uses only Python stdlib and performs network requests only to URLs you supply.

X5 Protocol Skill

Send X5 protocol requests directly from the terminal using scripts/x5_client.py.

Quick Start

# Send request from .x5 file
python3 ~/.claude/skills/x5-protocol/scripts/x5_client.py --file request.x5 --json

# Inline request
python3 ~/.claude/skills/x5-protocol/scripts/x5_client.py \
  --appid my_app --appkey my_key \
  --url http://localhost:8080/x5/api \
  --method createUser \
  --body '{"name":"test"}' \
  --json

X5 Protocol Specification

Signature Calculation

sign = md5(appid + JSON.stringify(body) + appkey).toUpperCase()

The body is serialized as compact JSON (no spaces), then concatenated with appid and appkey, MD5-hashed, and uppercased.

Request Encoding Steps

1. Build the X5 envelope:

{
  "header": {
    "appid": "app_id",
    "sign": "MD5_SIGNATURE_UPPERCASE",
    "method": "X5_Method_Name"
  },
  "body": "{\"key\":\"value\"}"
}

2. JSON-serialize the envelope (compact, no spaces)
3. Base64-encode the JSON string
4. Send as POST with Content-Type: application/x-www-form-urlencoded
5. Body: data=<url_encoded_base64>

Response Format

X5 responses use the same envelope structure:

{
  "header": {
    "code": 0,
    "message": "success"
  },
  "body": { ... }
}

Success: HTTP 2xx AND X5 code 0 or 200.

.x5 File Format

### Request Description
@name = RequestName
@appid = my_app_id
@appkey = my_app_key
@url = http://localhost:8080/x5/api/endpoint

POST @url
X5-Method: methodName
X-Custom-Header: custom-value

{
  "key": "value"
}

Directives:

Directive	Description
@name	Request name (for multi-request files)
@appid	Application ID
@appkey	Application secret key
@url	Request URL (referenced by POST @url)
X5-Method:	X5 API method name (overwrites HTTP method)

Key parsing rules:

• ### separates multiple requests in one file
• # lines are comments
• POST @url sets URL via @url directive reference
• X5-Method: overwrites the method from the POST line
• Any Header-Name: value line becomes a custom HTTP header
• JSON body starts with { or [

Multiple requests per file:

### Create Resource
@name = createResource
@appid = my_app
@appkey = my_key
@url = http://localhost:8080/x5/resource/create

POST @url
X5-Method: createResource
{"name": "test"}

### Query Resource
@name = queryResource
@appid = my_app
@appkey = my_key
@url = http://localhost:8080/x5/resource/query

POST @url
X5-Method: queryResource
{"resourceId": "123"}

CLI Reference

python3 x5_client.py [OPTIONS]

Options:
  --file FILE           Path to .x5 file
  --request-name NAME   Specific request name (for multi-request files)
  --list                List all requests in .x5 file (no send)
  --appid APPID         App ID (inline or override)
  --appkey APPKEY       App Key (inline or override)
  --url URL             Target URL (inline or override)
  --method METHOD       X5 method name (inline or override)
  --body BODY           JSON body string
  --body-file FILE      JSON body file path
  --header KEY=VALUE    Custom HTTP header (repeatable)
  --curl                Generate cURL command (no send)
  --dry-run             Show encoded request (no send)
  --json                Output in JSON format
  --timeout MS          Timeout in ms (default: 30000)

Usage Patterns

Pattern 1: Send from .x5 file

python3 ~/.claude/skills/x5-protocol/scripts/x5_client.py --file /path/to/request.x5 --json

For multi-request files, use --request-name:

python3 ~/.claude/skills/x5-protocol/scripts/x5_client.py --file /path/to/api.x5 --request-name createUser --json

Pattern 2: Inline request

Use when the user describes a request conversationally or provides parameters directly:

python3 ~/.claude/skills/x5-protocol/scripts/x5_client.py \
  --appid VALUE --appkey VALUE --url VALUE --method VALUE \
  --body '{"key":"value"}' --json

Pattern 3: Generate cURL

python3 ~/.claude/skills/x5-protocol/scripts/x5_client.py --file request.x5 --curl

Pattern 4: List requests in file

python3 ~/.claude/skills/x5-protocol/scripts/x5_client.py --file request.x5 --list

Pattern 5: Debug / inspect encoded request

python3 ~/.claude/skills/x5-protocol/scripts/x5_client.py --file request.x5 --dry-run --json

Shows signature, Base64 payload, and full envelope without sending.

Important Notes

• Always use --json for programmatic consumption — parse the JSON output to present results to the user
• When a .x5 file has multiple requests and the user doesn't specify which one, list them and ask
• CLI params (--appid, --appkey, etc.) override values from the .x5 file
• The script uses Python stdlib only (zero dependencies)
• Exit code 0 = success, 1 = error, 2 = argument error
• On error with --json, output is {"success": false, "error": "message"}