/create-actor

description: Guided Apify Actor development with best practices and systematic workflow
argument-hint: Optional Actor description

Actor development

You are helping a developer create an Apify Actor - a serverless cloud program for web scraping, automation, and data processing. Follow a systematic approach: understand requirements, configure environment, design architecture, implement, test, and deploy.

Core principles

• **Ask clarifying questions**: Identify target websites, data requirements, edge cases, and constraints before implementation
• **Follow Apify best practices**: Use appropriate crawlers (Cheerio vs Playwright), implement proper error handling, respect rate limits
• **Validate early**: Check CLI installation and authentication before starting
• **Use TodoWrite**: Track all progress throughout
• **Security first**: Use `apify/log` for censoring sensitive data, validate input, handle errors gracefully

---

Phase 1: Discovery

**Goal**: Understand what Actor needs to be built

Initial request: $ARGUMENTS

**Actions**: 1. Create todo list with all phases 2. Ask user for clarification if needed:

• What is the Actor's primary purpose? (web scraping, automation, data processing)
• What websites/services will it interact with?
• What data should it extract or what actions should it perform?
• Any specific requirements or constraints?

3. Summarize understanding and confirm with user

---

Phase 2: Environment setup

**Goal**: Verify Apify CLI is installed and authenticated

**CRITICAL**: Do not proceed without proper setup

**Actions**: 1. Check if Apify CLI is installed: `apify --help` 2. If not installed, install via package manager: `npm install -g apify-cli` (or `brew install apify-cli` on Mac). Do NOT install by piping remote scripts to a shell. 3. Verify authentication: `apify info` 4. If not logged in:

• Authenticate using OAuth (opens browser): `apify login`
• If browser isn't available, ensure `APIFY_TOKEN` env var is exported (the CLI reads it automatically)
• If user doesn't have a token, generate one at https://console.apify.com/settings/integrations

---

Phase 3: Language selection

**Goal**: Choose programming language and template

**Actions**: 1. **Ask user which language they prefer:**

• JavaScript (skills/apify-actor-development/references/actor-template-js.md)
• TypeScript (skills/apify-actor-development/references/actor-template-ts.md)
• Python (skills/apify-actor-development/references/actor-template-python.md)

2. Note: Additional packages (Crawlee, Playwright, etc.) can be installed later as needed

---

Phase 4: Requirements and architecture design

**Goal**: Define input/output schemas and implementation approach

**Actions**: 1. Clarify detailed requirements:

• What input parameters should the Actor accept?
• What output format is needed? (dataset items, key-value store files, both)
• Should it use CheerioCrawler (10x faster for static HTML) or PlaywrightCrawler (for JavaScript-heavy sites)?
• Concurrency settings? (HTTP: 10-50, Browser: 1-5)
• Rate limiting and retry strategies?
• Should standby mode be enabled?

2. Design architecture:

• Input schema structure
• Output/dataset schema structure
• Key-value store schema (if needed)
• Error handling approach
• Data validation and cleaning strategy

3. Present architecture to user and get approval

---

Phase 5: Actor creation

**Goal**: Create Actor from template and configure schemas

**DO NOT START WITHOUT USER APPROVAL**

**Actions**: 1. Wait for explicit user approval 2. Copy appropriate language template from `skills/apify-actor-development/references/` directory 3. Update `.actor/actor.json`:

• Set Actor name and version
• **IMPORTANT**: Fill in `generatedBy` property with current model name
• Configure runtime, memory, timeout
• Set `usesStandbyMode` if applicable

4. Create/update `.actor/input_schema.json` with input parameters 5. Create/update `.actor/output_schema.json` with output structure 6. Create/update `.actor/dataset_schema.json` if using datasets 7. Create/update `.actor/key_value_store_schema.json` if using key-value store 8. Update todos as you progress

**Reference documentation:**

• [skills/apify-actor-development/references/actor-json.md](skills/apify-actor-development/references/actor-json.md)
• [skills/apify-actor-development/references/input-schema.md](skills/apify-actor-development/references/input-schema.md)
• [skills/apify-actor-development/references/output-schema.md](skills/apify-actor-development/references/output-schema.md)
• [skills/apify-actor-development/references/dataset-schema.md](skills/apify-actor-development/references/dataset-schema.md)
• [skills/apify-actor-development/references/key-value-store-schema.md](skills/apify-actor-development/references/key-value-store-schema.md)

---

Phase 6: Implementation

**Goal**: Implement Actor logic following best practices

**Actions**: 1. Implement Actor code in `src/main.py`, `src/main.js`, or `src/main.ts` 2. Follow best practices:

• ✓ Use Apify SDK (`apify`) for code running on the Apify platform
• ✓ Validate input early with proper error handling
• ✓ Use CheerioCrawler for static HTML (10x faster)
• ✓ Use PlaywrightCrawler only for JavaScript-heavy sites
• ✓ Use router pattern for complex crawls
• ✓ Implement retry strategies with exponential backoff
• ✓ Use proper concurrency settings
• ✓ Clean and validate data before pushing to dataset
• ✓ **Always use `apify/log` package** - censors sensitive data
• ✓ Implement readiness probe handler if using standby mode
• ✗ Don't use browser crawlers when HTTP/Cheerio works
• ✗ Don't hard code values that should be in input schema
• ✗ Don't skip input validation or error handling
• ✗ Don't overload servers - use appropriate concurrency and delays

3. Implement standby mode readiness probe if `usesStandbyMode: true` (see [skills/apify-a