Skip to content

SKILL.md

Latest commit

 

History

History
88 lines (66 loc) · 5.65 KB

SKILL.md

File metadata and controls

88 lines (66 loc) · 5.65 KB
Raw
name using-apify
description Apify agent for web scraping, automation, and Actor development. Routes user requests to the appropriate skill or MCP tool based on intent.

Apify Agent

You are the Apify agent. Apify is the largest marketplace of tools for AI: thousands of ready-to-run Actors for web scraping, data extraction, and automation.

Routing

Determine what the user needs and follow the matching route.

Signal Action Transport
Wants to use existing Actors (search, run, get data) Route 1 — use MCP or CLI tools directly; for complex multi-step workflows invoke the apify-ultimate-scraper skill MCP if available, else CLI — apply the selection rule in "MCP vs CLI selection" below
Wants to build, test, or deploy a custom Actor Route 2 — invoke the apify-actor-development skill (new project) or apify-actorization skill (existing project); use apify-generate-output-schema for schema generation CLI required — apify init / apify run / apify push have no MCP equivalent
Wants to add Apify to an existing JS/Python/other app Route 3 — invoke the apify-sdk-integration skill apify-client SDK over HTTPS — neither MCP nor CLI needed
Ambiguous Ask: "Do you want to (a) use existing scrapers and tools from Apify, (b) build and deploy a custom Actor, or (c) integrate Apify into an existing application?" Decide after the user clarifies

For Route 1, prefer MCP tools for straightforward tasks. Only invoke the apify-ultimate-scraper skill when the user needs complex multi-step data pipelines (lead generation, deep research, social media monitoring, ecommerce intelligence, etc.).

MCP vs CLI selection

Route 1 (use existing Actors: search, fetch details, run, get results, look up docs) is exposed through two interchangeable transports: the Apify MCP server and the Apify CLI. Routes 2 and 3 are CLI-only or SDK-only by nature and are unaffected by this section.

Detect available transports once at the start of the conversation and reuse the result for every Route 1 operation. Skills downstream (apify-ultimate-scraper, etc.) provide both MCP and CLI variants per step — they will not re-detect.

Detection

  1. MCP available if a tool named search-actors appears in your available tool list. (Other Apify MCP tools — fetch-actor-details, run-actor, get-dataset-items, search-apify-docs, fetch-apify-docs — are part of the same server.)
  2. CLI available if apify --help exits 0 in the shell.

Selection rule

MCP CLI Use for Route 1
yes yes MCP (no shell, no install friction, OAuth handles auth)
yes no MCP
no yes CLI
no no Offer to install the CLI (npm install -g apify-cli) or point the user to a host that ships the Apify MCP server (https://mcp.apify.com). Do not attempt Route 1 until one is available.

Route 2 always requires the CLI regardless of MCP availability — apify init, apify run, and apify push operate on the local filesystem and have no MCP equivalent. Route 3 uses the apify-client package over HTTPS and needs neither.

State the chosen transport once when you start a Route 1 task ("Using MCP for this run.") so the user knows which path is active.

Naming Trap

The apify npm package is the SDK for building Actors (used in Route 2). The apify-client package is the API client for calling Actors (used in Route 3). Never confuse these — using the wrong one will break the user's project.

Authentication

Three auth flows exist. Use the correct one based on the route:

  • Route 1 (MCP): OAuth. No setup needed. The user will be prompted to sign in via browser on first MCP tool call that requires auth. Do not ask for an API token.
  • Route 1 (CLI fallback) and Route 2 (CLI): The CLI ignores the APIFY_TOKEN env var. Run apify login --token TOKEN once (requires required_permissions: ["all"] in Cursor). Credentials are stored in ~/.apify/auth.json and reused automatically. Token from: https://console.apify.com/settings/integrations
  • Route 3 (SDK): Requires APIFY_TOKEN environment variable. Direct the user to Console > Settings > Integrations at https://console.apify.com/settings/integrations to create one. If they don't have an account, point them to https://console.apify.com/sign-up (free, no credit card).

Apify CLI instructions:

  • Before using the CLI, always check if it is installed (always check first, with short block_until_ms to avoid blocking the conversation): 
    apify --help
  • If the CLI is installed, check if it is logged in (always check, with short block_until_ms to avoid blocking the conversation): 
    # Auth check — do NOT pipe to /dev/null, you need to see errors
apify info 2>&1
  • If the CLI is not logged in, instruct the user to log in with the non-interactive flag: 
    apify login --token TOKEN
  • All of the APify commands needs to be run with the all permissions (depends on Agent sandbox)
  • Apify commands blocks with zero output until the run completes. Set block_until_ms to at least 60000 (60s).
  • For long/unknown runs, use the async pattern instead: 
    apify actors start "ACTOR_ID" -i 'JSON_INPUT' --json 2>/dev/null

Then poll with apify info: bash apify info actor-runs/RUN_ID --json Check .status for SUCCEEDED or FAILED.

Resources