create-actor

# 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-actor-development/references/standby-mode.md](skills/apify-actor-development/references/standby-mode.md))
4. Use proper logging (see [skill