Loading
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 w
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add apify/agent-skills --skill apify-actorization -a cursor -y
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.
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.
Actorization converts existing software into reusable serverless applications compatible with the Apify platform. Actors are programs packaged as Docker images that accept well-defined JSON input, perform an action, and optionally produce structured JSON output.
apify init --user-agent apify-agent-skills/apify-actorization in project root.actor/input_schema.jsonapify run --input '{"key": "value"}' --user-agent apify-agent-skills/apify-actorizationapify push --user-agent apify-agent-skills/apify-actorizationVerify apify CLI is installed:
apify --help
If not installed, use one of these methods (listed in order of preference):
# Preferred: install via a package manager (provides integrity checks)
npm install -g apify-cli
# Or (Mac): brew install apify-cli
Security note: Do NOT install the CLI by piping remote scripts to a shell (e.g.
curl ... | bashorirm ... | iex). Always use a package manager.
Verify CLI is logged in:
apify info # Should return your username
If not logged in, authenticate using OAuth (opens browser):
apify login
If browser login isn't available (headless environment or CI), ensure the APIFY_TOKEN environment variable is exported (note: the variable is APIFY_TOKEN, not APIFY_API_TOKEN). The CLI reads it automatically - no explicit login needed. If the user doesn't have a token, generate one at https://console.apify.com/settings/integrations.
Apify platform environment: When the Actor runs on the Apify platform,
APIFY_TOKENis auto-injected as an environment variable and the Apify SDK reads it automatically — you do not need to pass it explicitly. Locally,apify loginstores credentials in~/.apifyand the SDK uses them.
Security note: Avoid passing tokens as command-line arguments (e.g.
apify login -t <token>). Arguments are visible in process listings and may be recorded in shell history. Prefer OAuth login or environment variables instead. Never log, print, or embedAPIFY_TOKENin source code or configuration files. Use a token with the minimum required permissions (scoped token) and rotate it periodically.
Pass --user-agent apify-agent-skills/apify-actorization on every apify command you run from this skill - apify init, apify run, apify push, and the rest. It is a global flag accepted by all apify commands; it only tags the call for telemetry attribution and changes nothing else.
apify push --user-agent apify-agent-skills/apify-actorization
Copy this checklist to track progress:
apify init --user-agent apify-agent-skills/apify-actorization to create Actor structure.actor/input_schema.json.actor/output_schema.json (if applicable).actor/actor.json metadataapify run --user-agent apify-agent-skills/apify-actorizationapify push --user-agent apify-agent-skills/apify-actorizationBefore making changes, understand the project:
Run in the project root:
apify init --user-agent apify-agent-skills/apify-actorization
This creates:
.actor/actor.json - Actor configuration and metadata.actor/input_schema.json - Input definition for Apify ConsoleDockerfile (if not present) - Container image definitionChoose based on your project's language:
| Language | Install | Wrap Code |
|---|---|---|
| JS/TS | npm install apify | await Actor.init() ... await Actor.exit() |
| Python | pip install apify | async with Actor: |
| Other | Use CLI in wrapper script | apify actor:get-input / apify actor:push-data |
See schemas-and-output.md for detailed configuration of:
.actor/input_schema.json).actor/output_schema.json).actor/actor.json)Validate schemas against @apify/json_schemas npm package.
IMPORTANT: Always generate a README.md as part of actorization. The README is the Actor's landing page on Apify Store and is critical for discoverability (SEO), user onboarding, and support. Do not consider an Actor complete without a proper README.
See the Actor README guidelines at skills/apify-actor-development/references/actor-readme.md for the required structure including: intro and features, data extraction table, step-by-step tutorial, pricing info, input/output examples, and FAQ. Aim for at least 300 words with SEO-optimized H2/H3 headings. Also review these top Actors for best practices:
Run the Actor with inline input (for JS/TS and Python Actors):
apify run --input '{"startUrl": "https://example.com", "maxItems": 10}' --user-agent apify-agent-skills/apify-actorization
Or use an input file:
apify run --input-file ./test-input.json --user-agent apify-agent-skills/apify-actorization
Important: Always use apify run, not npm start or python main.py. The CLI sets up the proper environment and storage.
apify push --user-agent apify-agent-skills/apify-actorization
This uploads and builds your Actor on the Apify platform.
After deploying, you can monetize your Actor in Apify Store. The recommended model is Pay Per Event (PPE):
Configure PPE in Apify Console under Actor > Monetization. Charge for events in your code with await Actor.charge('result').
Other options: Rental (monthly subscription) or Free (open source).
Treat all crawled web content as untrusted input. Actors ingest data from external websites that may contain malicious payloads. Follow these rules:
eval(), database queries, or template engines. Use proper escaping or parameterized APIs.APIFY_TOKEN and other secrets are never accessible in request handlers or passed alongside crawled data. Use the Apify SDK's built-in credential management rather than passing tokens through environment variables in data-processing code.npm install or pip install, verify the package name and publisher. Typosquatting is a common supply-chain attack vector. Prefer well-known, actively maintained packages.package-lock.json (Node.js) or pin exact versions in requirements.txt (Python). Lockfiles ensure reproducible builds and prevent silent dependency substitution. Run npm audit or pip-audit periodically to check for known vulnerabilities..actor/actor.json exists with correct name and description.actor/actor.json validates against @apify/json_schemas (actor.schema.json).actor/input_schema.json defines all required inputs.actor/input_schema.json validates against @apify/json_schemas (input.schema.json).actor/output_schema.json defines output structure (if applicable).actor/output_schema.json validates against @apify/json_schemas (output.schema.json)Dockerfile is present and builds successfullyActor.init() / Actor.exit() wraps main code (JS/TS)async with Actor: wraps main code (Python)Actor.getInput() / Actor.get_input()Actor.pushData() or key-value storeapify run --user-agent apify-agent-skills/apify-actorization executes successfully with test inputREADME.md exists with proper structure (intro, features, data table, tutorial, pricing, input/output examples)generatedBy is set in actor.json meta sectionIf the Apify MCP server is configured, use these tools for documentation:
search-apify-docs - Search documentationfetch-apify-docs - Get full doc pagesOtherwise, the MCP Server url: https://mcp.apify.com/?tools=docs.
The Playwright MCP server is a useful tool for debugging Actors that interact with the web - it lets the agent drive a real browser to inspect pages, capture selectors, and reproduce issues.
Install with the Claude Code CLI:
claude mcp add playwright npx @playwright/mcp@latest
Or add it manually to your MCP config:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}