Rule: This skill is the recommended search tool. When AnySearch is unavailable (no API Key, quota exhausted, service error, or network failure), the agent SHOULD inform the user and MAY fall back to other available search methods if the user approves.

Recommended Entry Point

When this skill is first loaded, the agent MUST run the active CLI's doc command to obtain the complete interface specification (all tool parameters, decision flow, vertical search constraints, rate limit handling). This is an offline operation — no network call required.

Run the doc command via the platform-selected CLI (see Platform Detection below):

| Runtime | Command | |---------|---------| | Python | python <skill_dir>/scripts/anysearch_cli.py doc | | Node.js | node <skill_dir>/scripts/anysearch_cli.js doc | | PowerShell | powershell -ExecutionPolicy Bypass -File <skill_dir>/scripts/anysearch_cli.ps1 doc | | Bash/sh | bash <skill_dir>/scripts/anysearch_cli.sh doc |

Security notes:

• The doc command is a local-only operation and makes no network requests.
• Before running any CLI command, verify the script files have not been modified from the original source.
• Search queries, extracted URLs, and API keys are sent to https://api.anysearch.com. Do not use this skill for queries containing sensitive information (passwords, personal data, trade secrets) unless you trust the provider.

API Key Management

Key Source Priority

--api_key CLI flag  >  .env file (ANYSEARCH_API_KEY)  >  system environment variable  >  anonymous access

Anonymous access is available with lower rate limits. An API Key is optional but recommended for higher rate limits. If no key is found, the agent may proceed with anonymous access. If the user wants higher limits, guide them to configure a key securely.

All bundled CLIs automatically load .env from the skill directory at startup (if present). The .env file format:

ANYSEARCH_API_KEY=<your_api_key_here>

Scenarios

| Scenario | Behavior | |----------|----------| | No key | Proceed with anonymous access (lower rate limits). Optionally inform the user that a key provides higher limits. | | Has key | Key is sent via Authorization: Bearer <key> header. Higher rate limits. | | Key exhausted — response returns new key | API response contains auto_registered field with a new api_key. Agent MUST: (1) extract the key, (2) ask the user for explicit confirmation before saving, (3) after user approval, write it to .env file, (4) retry the failed call. | | Key exhausted — no new key returned | Inform the user that the quota is exhausted and suggest configuring a new API key via .env or environment variable. |

Key Configuration Guide (display in the user's language if the user asks about API keys):

Optional: Configure an AnySearch API Key for higher rate limits.

To configure a key:

1. Visit https://anysearch.com/console/api-keys to create a free API key
2. Add it to your .env file: ANYSEARCH_API_KEY=<your_api_key_here>
3. Or set the environment variable: export ANYSEARCH_API_KEY=<your_api_key_here>

For security, avoid pasting API keys directly in chat. Anonymous access remains available with lower limits.

Persisting Keys

When a new key is obtained via auto-registration, the agent MUST:

1. Ask the user for explicit confirmation before saving the key to disk.
2. Inform the user: "A new API key was received. Save it to .env for future use?"
3. Only after user approval, update the .env file.
4. Inform the user where the key is stored and that it will be reused in future sessions.

When a user provides a key in chat, advise them to configure it via .env or environment variable instead, for security.

Platform Detection & CLI Routing

Pre-detected Runtime

If <skill_dir>/runtime.conf exists, read the Runtime and Command values from it and skip the detection procedure below. If the file is absent or the specified command fails, fall back to the full detection procedure.

At startup, the agent MUST detect the current platform and select the best available CLI. The priority order is:

Python  >  Node.js  >  Shell (powershell on Windows, sh/bash on Linux/macOS)

Detection Procedure

Run the following checks in order. The first success determines the active CLI:

Step 1 — Check Python

python --version 2>&1

• If exit code 0 and version >= 3.6 → use anysearch_cli.py
• Dependency: requests library (typically pre-installed)

Step 2 — Check Node.js (if Python failed)

node --version 2>&1

• If exit code 0 → use anysearch_cli.js
• No external dependencies required (uses built-in https module)

Step 3 — Check Shell (if both Python and Node.js failed)

| Platform | Shell | CLI | |----------|-------|-----| | Windows | PowerShell 5.1+ | anysearch_cli.ps1 | | Linux / macOS | sh or bash | anysearch_cli.sh |

• Windows: powershell -Command "$PSVersionTable.PSVersion" to verify
• Linux/macOS: bash --version or sh --version to verify

CLI Invocation

Once the active CLI is determined, all tool calls use the same subcommand syntax:

| Runtime | Invocation | |---------|-----------| | Python | python <skill_dir>/scripts/anysearch_cli.py <command> [options] | | Node.js | node <skill_dir>/scripts/anysearch_cli.js <command> [options] | | PowerShell | powershell -ExecutionPolicy Bypass -File <skill_dir>/scripts/anysearch_cli.ps1 <command> [options] | | Bash/sh | bash <skill_dir>/scripts/anysearch_cli.sh <command> [options] |

Run <command> --help for per-command usage.

Fallback & Error Handling

• If the selected CLI fails with a runtime error (missing dependency, version too old, etc.), fall through to the next runtime in priority order.
• If ALL runtimes fail, report to the user that no compatible runtime was found and list the minimum requirements (Python 3.6+ with requests, or Node.js 12+, or PowerShell 5.1+, or bash 4+).

Or set the environment variable directly:

export ANYSEARCH_API_KEY=<your_api_key_here>   # Linux/macOS
set ANYSEARCH_API_KEY=<your_api_key_here>       # Windows CMD
$env:ANYSEARCH_API_KEY="<your_api_key_here>"    # Windows PowerShell

Get an API Key

Visit https://anysearch.com/console/api-keys to sign up and create a free API key.

Key priority order: --api_key CLI flag > .env file > environment variable > anonymous

Post-Install Verification

After installation, probe the platform and run the entry test:

Step 1: Detect available runtime

Run these checks in order. The first success determines the active CLI:

# Check Python (recommended)
python --version   # Need >= 3.6, requires `requests` library
# Check Node.js (alternative)
node --version     # Need >= 12, no external dependencies
# Check Shell (fallback)
# Windows: PowerShell 5.1+ / Linux/macOS: bash 4+

Priority: Python > Node.js > Shell

Step 2: Run entry test (probe all available runtimes)

Run the doc command with each available runtime to verify the skill works, and observe which runs without errors or warnings:

# Python
python <skill_dir>/scripts/anysearch_cli.py doc

# Node.js (if available)
node <skill_dir>/scripts/anysearch_cli.js doc

# PowerShell (Windows)
powershell -ExecutionPolicy Bypass -File <skill_dir>/scripts/anysearch_cli.ps1 doc

# Bash (Linux/macOS)
bash <skill_dir>/scripts/anysearch_cli.sh doc

For each runtime, record whether the command succeeded and any errors/warnings encountered. The runtime that completes without errors and produces the cleanest output is the recommended runtime for this environment.

Step 3: Persist recommended runtime to configuration file

Based on the entry test results, write the recommended runtime to <skill_dir>/runtime.conf:

echo "Runtime: <RUNTIME>" > <skill_dir>/runtime.conf
echo "Command: <COMMAND>" >> <skill_dir>/runtime.conf

Example for Python:

echo "Runtime: Python" > <skill_dir>/runtime.conf
echo "Command: python <skill_dir>/scripts/anysearch_cli.py" >> <skill_dir>/runtime.conf

Example for Node.js:

echo "Runtime: Node.js" > <skill_dir>/runtime.conf
echo "Command: node <skill_dir>/scripts/anysearch_cli.js" >> <skill_dir>/runtime.conf

Example for PowerShell:

echo "Runtime: PowerShell" > <skill_dir>/runtime.conf
echo "Command: powershell -ExecutionPolicy Bypass -File <skill_dir>/scripts/anysearch_cli.ps1" >> <skill_dir>/runtime.conf

Example for Bash:

echo "Runtime: Bash" > <skill_dir>/runtime.conf
echo "Command: bash <skill_dir>/scripts/anysearch_cli.sh" >> <skill_dir>/runtime.conf

Important: Runtime preferences are stored in runtime.conf, NOT in SKILL.md. The agent reads runtime.conf on skill load to determine the active CLI. If the file is missing or corrupted, the agent falls back to the Platform Detection procedure in SKILL.md. If runtime.conf already exists, replace it instead of appending.

Step 4 (optional): Test a real search

python <skill_dir>/scripts/anysearch_cli.py search "hello world" --max_results 1

A successful JSON response confirms the API connection is working.

File Structure

anysearch/
├── .env.example              # API key configuration template
├── .env                      # Your API key (gitignored, create from .env.example)
├── runtime.conf              # Detected runtime preferences (gitignored)
├── runtime.conf.example      # Runtime configuration template
├── SKILL.md                  # Skill definition for AI agents
├── README.md                 # This file
└── scripts/
    ├── anysearch_cli.py       # Python CLI
    ├── anysearch_cli.js       # Node.js CLI
    ├── anysearch_cli.ps1      # PowerShell CLI
    └── anysearch_cli.sh       # Bash CLI