From c48630f22a45b78f13dbc68a01019e4631a4be5c Mon Sep 17 00:00:00 2001 From: Lukas Bekr Date: Wed, 25 Mar 2026 01:32:56 +0100 Subject: [PATCH 1/5] feat: add agent-onboarding skill --- skills/apify-agent-onboarding/SKILL.md | 164 +++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 skills/apify-agent-onboarding/SKILL.md diff --git a/skills/apify-agent-onboarding/SKILL.md b/skills/apify-agent-onboarding/SKILL.md new file mode 100644 index 0000000..24e3354 --- /dev/null +++ b/skills/apify-agent-onboarding/SKILL.md @@ -0,0 +1,164 @@ +--- +name: apify-agent-onboarding +description: > + Set up Apify for any use case. Routes to the correct installation path + based on what the user wants to do: MCP server, Agent Skills + CLI, or API client. + Triggers: "install apify", "set up apify", "use apify", "connect apify", + "enable apify", "apify getting started", "which apify package", "apify MCP", + "add apify", "scrape with apify". + Do NOT use when: Apify is already configured and the user wants to run + a specific Actor (use apify-ultimate-scraper) or build an Actor + (use apify-actor-development). +--- + +# Apify agent onboarding + +You are an AI agent setting up Apify for your user. Apify is a platform with thousands of serverless cloud tools called **Actors** for web scraping, browser automation, and data extraction. + +**Before installing anything, determine what your user needs:** + +| Signal | Route | +|--------|-------| +| Universal catch-all solution ideal for research and exploration | **Path A: MCP server** (Apify Store search, small scale ad-hoc scraping, and documentation access) | +| User wants to scrape web data with multi-step agentic workflows | **Path B: Agent Skills** (ultimate-scraper) | +| User wants to build, test, or deploy a custom Actor | **Path B: Agent Skills + CLI** (actor-development, actorization, generate-output-schema) | +| User wants to add Apify to an existing JS/Python app | **Path C: API integration** | +| Ambiguous | Ask: "Do you want to (a) extract data from websites, (b) build and deploy a custom scraper, or (c) add web scraping to an existing app?" | + +> **NAMING TRAP:** The `apify` npm package is the SDK for *building* Actors. The `apify-client` package is the API client for *calling* Actors. If your user wants to call Actors from their app, use `apify-client`. + +--- + +## Path A: MCP server + +Connect to Apify via the Model Context Protocol. No local install needed for remote-capable clients. + +### Exploration mode (no account needed) + +These tools work **without authentication** - use them freely for research and Actor discovery: +- `search-actors` - find Actors by keyword +- `fetch-actor-details` - get Actor specs, input schema, pricing +- `search-apify-docs` / `fetch-apify-docs` - browse documentation + +### Setup + +**Remote (streamable HTTP):** +```json +{ + "mcpServers": { + "apify": { + "url": "https://mcp.apify.com" + } + } +} +``` +Clients that support remote MCP (Claude Code, Cursor, VS Code, Copilot) use OAuth - your user will be prompted to sign in on first use. + +**Local (stdio):** +```json +{ + "mcpServers": { + "apify": { + "command": "npx", + "args": ["-y", "@apify/actors-mcp-server"], + "env": { "APIFY_TOKEN": "" } + } + } +} +``` +Requires an API token. Direct your user to **Console > Settings > Integrations** at https://console.apify.com/settings/integrations to create one. If they don't have an account, open https://console.apify.com/sign-up in their browser - sign-up is free, no credit card needed. + +For client-specific configuration, direct your user to https://mcp.apify.com which generates ready-to-paste configs for all supported clients. + +### Verify + +Call `search-actors` with query `"web scraper"`. If results return, the connection works. + +--- + +## Path B: Agent Skills + +Install pre-built skill workflows for data extraction and Actor development. + +```bash +npx skills add apify/agent-skills +``` + + +**Available skills** + +| Skill | Purpose | +|-------|---------| +| `apify-ultimate-scraper` | Web scraping with multi-step agentic workflows | +| `apify-actor-development` | Full Actor build/test/deploy lifecycle | +| `apify-actorization` | Convert an existing project into an Actor | +| `apify-generate-output-schema` | Auto-generate output schemas from source code | + + +### For data extraction + +Use the `apify-ultimate-scraper` skill for scraping web data via agentic workflows. Create complex multi-step data pipelines with for use cases like lead generation, deep research, social media monitoring, ecommerce intelligence etc. + +**Requires:** `APIFY_TOKEN` environment variable. Ask your user for their API token, or direct them to https://console.apify.com/settings/integrations to create one. If they don't have an account, open https://console.apify.com/sign-up (free, no credit card). + +### For Actor development + +Use the `apify-actor-development` or `apify-actorization` skills in conjuction with `apify-generate-output-schema` skill for a guided workflow covering scaffolding, testing, and deployment of Actors on the Apify platform. + +**Requires Apify CLI:** +```bash +npm install -g apify-cli +apify login +``` + +**Workflow:** `apify create my-actor` > develop in `src/` > `apify run` (test locally) > `apify push` (deploy to cloud). + +--- + +## Path C: API integration + +For adding Apify to an existing application. Install `apify-client` (NOT `apify`). + +**JavaScript/TypeScript:** +```bash +npm install apify-client +``` +```typescript +import { ApifyClient } from 'apify-client'; +const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); +const run = await client.actor('apify/web-scraper').call({ startUrls: [{ url: 'https://example.com' }] }); +const { items } = await client.dataset(run.defaultDatasetId).listItems(); +``` + +**Python:** +```bash +pip install apify-client +``` +```python +from apify_client import ApifyClient +client = ApifyClient(token=os.environ['APIFY_TOKEN']) +run = client.actor('apify/web-scraper').call(run_input={'startUrls': [{'url': 'https://example.com'}]}) +items = client.dataset(run['defaultDatasetId']).list_items().items +``` + +**REST API** (any language): `POST https://api.apify.com/v2/acts/{actorId}/runs` with `Authorization: Bearer `. Full reference: https://docs.apify.com/api/v2 + +### Documentation context for agentic development +If you need Apify documentation while building an integration, consider configuring the MCP server to access docs tools: `search-apify-docs`, `fetch-apify-docs` + +Alternatively refer to following resources: +- Docs index: https://docs.apify.com/llms.txt +- Full docs: https://docs.apify.com/llms-full.txt +- Any Actor details in clean markdown: append `.md` to its Apify Store URL + +--- + +## Quick reference + +| I want to... | Path | Install | Auth | +|---|---|---|---| +| Use Apify platform with my AI agent | MCP server | None (remote) | OAuth | +| Run multi-step scraping workflows | Agent Skills | `npx skills add apify/agent-skills` | `APIFY_TOKEN` | +| Build and deploy a custom Actor | Agent Skills + CLI | `npm i -g apify-cli` | `apify login` | +| Call Actors from Node.js/Python | API client | `npm i apify-client` / `pip install apify-client` | `APIFY_TOKEN` | +| Call Actors from any language | REST API | None | Bearer token | \ No newline at end of file From 9c0e987076633ae9571a36166287eaf88435cf49 Mon Sep 17 00:00:00 2001 From: Lukas Bekr Date: Wed, 25 Mar 2026 01:34:41 +0100 Subject: [PATCH 2/5] feat: register agent-onboarding in marketplace.json --- .claude-plugin/marketplace.json | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 75b127e..bfa9415 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,6 +9,22 @@ "version": "1.6.0" }, "plugins": [ + { + "name": "apify-agent-onboarding", + "source": "./skills/apify-agent-onboarding", + "skills": "./", + "description": "Set up Apify for any use case. Routes to the correct installation path based on what the user wants to do: MCP server, Agent Skills + CLI, or API client.", + "keywords": [ + "apify", + "onboarding", + "setup", + "mcp", + "agent", + "getting-started" + ], + "category": "onboarding", + "version": "2.0.0" + }, { "name": "apify-lead-generation", "source": "./skills/apify-lead-generation", @@ -255,4 +271,4 @@ "version": "1.0.0" } ] -} +} \ No newline at end of file From d2fbe55533790869ec18ea7b86403c0244fca4e3 Mon Sep 17 00:00:00 2001 From: Lukas Bekr Date: Wed, 25 Mar 2026 01:35:13 +0100 Subject: [PATCH 3/5] feat: add quickstart section for agent-onboarding to README From c88b1d051c43b4b41400cd125a05f6589b35f2e1 Mon Sep 17 00:00:00 2001 From: Lukas Bekr Date: Mon, 30 Mar 2026 09:36:38 +0200 Subject: [PATCH 4/5] chore: add agent-onboarding to AGENTS.md --- agents/AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/agents/AGENTS.md b/agents/AGENTS.md index 4bd726d..56e4201 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -3,6 +3,7 @@ You have additional SKILLs documented in directories containing a "SKILL.md" file. These skills are: + - apify-agent-onboarding -> "skills/apify-agent-onboarding/SKILL.md" - apify-actor-development -> "skills/apify-actor-development/SKILL.md" - apify-actorization -> "skills/apify-actorization/SKILL.md" - apify-generate-output-schema -> "skills/apify-generate-output-schema/SKILL.md" @@ -12,6 +13,7 @@ IMPORTANT: You MUST read the SKILL.md file whenever the description of the skill +apify-agent-onboarding: `Set up Apify for any use case. Routes to the correct installation path based on what the user wants to do: MCP server, Agent Skills + CLI, or API client.` apify-actor-development: `Develop, debug, and deploy Apify Actors - serverless cloud programs for web scraping, automation, and data processing. Use when creating new Actors, modifying existing ones, or troubleshooting Actor code.` apify-actorization: `Convert existing projects into Apify Actors - serverless cloud programs. Actorize JavaScript/TypeScript (SDK with Actor.init/exit), Python (async context manager), or any language (CLI wrapper). Use when migrating code to Apify, wrapping CLI tools as Actors, or adding Actor SDK to existing projects.` apify-generate-output-schema: `Generate output schemas (dataset_schema.json, output_schema.json, key_value_store_schema.json) for an Apify Actor by analyzing its source code. Use when creating or updating Actor output schemas.` From 0bd75c64d6e1396d67614982ba4739c71f4a3d9b Mon Sep 17 00:00:00 2001 From: Lukas Bekr Date: Mon, 30 Mar 2026 09:40:35 +0200 Subject: [PATCH 5/5] fix: use single-line description in frontmatter, regenerate AGENTS.md The generate_agents.py script doesn't parse YAML block scalars (>). Switched to single-line description matching the format of other skills. Regenerated AGENTS.md via the script to match expected output exactly. Co-Authored-By: Claude Opus 4.6 (1M context) --- agents/AGENTS.md | 4 ++-- skills/apify-agent-onboarding/SKILL.md | 10 +--------- 2 files changed, 3 insertions(+), 11 deletions(-) diff --git a/agents/AGENTS.md b/agents/AGENTS.md index 56e4201..a1d04df 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -3,9 +3,9 @@ You have additional SKILLs documented in directories containing a "SKILL.md" file. These skills are: - - apify-agent-onboarding -> "skills/apify-agent-onboarding/SKILL.md" - apify-actor-development -> "skills/apify-actor-development/SKILL.md" - apify-actorization -> "skills/apify-actorization/SKILL.md" + - apify-agent-onboarding -> "skills/apify-agent-onboarding/SKILL.md" - apify-generate-output-schema -> "skills/apify-generate-output-schema/SKILL.md" - apify-ultimate-scraper -> "skills/apify-ultimate-scraper/SKILL.md" @@ -13,9 +13,9 @@ IMPORTANT: You MUST read the SKILL.md file whenever the description of the skill -apify-agent-onboarding: `Set up Apify for any use case. Routes to the correct installation path based on what the user wants to do: MCP server, Agent Skills + CLI, or API client.` apify-actor-development: `Develop, debug, and deploy Apify Actors - serverless cloud programs for web scraping, automation, and data processing. Use when creating new Actors, modifying existing ones, or troubleshooting Actor code.` apify-actorization: `Convert existing projects into Apify Actors - serverless cloud programs. Actorize JavaScript/TypeScript (SDK with Actor.init/exit), Python (async context manager), or any language (CLI wrapper). Use when migrating code to Apify, wrapping CLI tools as Actors, or adding Actor SDK to existing projects.` +apify-agent-onboarding: `Set up Apify for any use case. Routes to the correct installation path based on what the user wants to do - MCP server, Agent Skills + CLI, or API client. Triggers on "install apify", "set up apify", "use apify", "connect apify", "apify getting started", "which apify package", "apify MCP". Do NOT use when Apify is already configured and the user wants to run a specific Actor (use apify-ultimate-scraper) or build an Actor (use apify-actor-development).` apify-generate-output-schema: `Generate output schemas (dataset_schema.json, output_schema.json, key_value_store_schema.json) for an Apify Actor by analyzing its source code. Use when creating or updating Actor output schemas.` apify-ultimate-scraper: `Universal AI-powered web scraper for any platform. Scrape data from Instagram, Facebook, TikTok, YouTube, Google Maps, Google Search, Google Trends, Booking.com, and TripAdvisor. Use for lead generation, brand monitoring, competitor analysis, influencer discovery, trend research, content analytics, audience analysis, or any data extraction task.` diff --git a/skills/apify-agent-onboarding/SKILL.md b/skills/apify-agent-onboarding/SKILL.md index 24e3354..4d4345a 100644 --- a/skills/apify-agent-onboarding/SKILL.md +++ b/skills/apify-agent-onboarding/SKILL.md @@ -1,14 +1,6 @@ --- name: apify-agent-onboarding -description: > - Set up Apify for any use case. Routes to the correct installation path - based on what the user wants to do: MCP server, Agent Skills + CLI, or API client. - Triggers: "install apify", "set up apify", "use apify", "connect apify", - "enable apify", "apify getting started", "which apify package", "apify MCP", - "add apify", "scrape with apify". - Do NOT use when: Apify is already configured and the user wants to run - a specific Actor (use apify-ultimate-scraper) or build an Actor - (use apify-actor-development). +description: Set up Apify for any use case. Routes to the correct installation path based on what the user wants to do - MCP server, Agent Skills + CLI, or API client. Triggers on "install apify", "set up apify", "use apify", "connect apify", "apify getting started", "which apify package", "apify MCP". Do NOT use when Apify is already configured and the user wants to run a specific Actor (use apify-ultimate-scraper) or build an Actor (use apify-actor-development). --- # Apify agent onboarding