Apify Agent Skills

Use the apify-generate-output-schema skill to create or update Apify Actor output schema files (dataset_schema.json, output_schema.json, and key_value_store_schema.json) by analyzing the Actor's source code. These schemas tell the Apify Console how to display run results.

Core Principles

• Analyze code first: Derive schemas from actual data-pushing calls (e.g., Actor.pushData) or existing type definitions (TypeScript interfaces, Python Pydantic models/dataclasses) rather than guessing.
• Every field is nullable: Set "nullable": true on every field because external APIs and websites are unpredictable.
• Anonymize examples: Use generic values (e.g., "exampleuser", "Example Channel") instead of real user data.
• Reuse patterns: Match the existing repository's description style, naming conventions (camelCase vs snake_case), and JSON formatting.

Standby mode allows Actors to function as API servers that remain ready in the background to handle HTTP requests.

Use Standby mode when your Actor needs to handle interactive, real-time HTTP requests, such as:

• API endpoints
• Webhook receivers
• Real-time data lookups
• MCP servers
• Scraping APIs serving on-demand single-URL requests

To enable this, set usesStandbyMode: true in your .actor/actor.json file and implement an HTTP server within your Actor code.

The Actor output schema specifies where an Actor stores its output and defines templates for accessing that output. Apify Console uses these definitions to display run results. The schema follows a JSON structure containing actorOutputSchemaVersion, a title, and a properties object where you define your specific outputs.

{
    "actorOutputSchemaVersion": 1,
    "title": "<OUTPUT-SCHEMA-TITLE>",
    "properties": {
        /* define your outputs here */
    }
}

It is important to distinguish between these two types of web servers:

• Container web server (ACTOR_WEB_SERVER_URL): Provides a per-run unique URL. It has no load balancing and no auto-scaling. It is primarily useful for viewing live UIs during a specific run.
• Standby mode (ACTOR_STANDBY_URL): Provides a stable hostname that is load-balanced across runs and auto-scaled based on traffic. This should be used for production APIs.

A standard Apify Actor project follows this directory and file structure:

.actor/
├── actor.json           # Actor config: name, version, env vars, runtime
├── input_schema.json    # Input validation & Console form definition
└── output_schema.json   # Output storage and display templates
src/
└── main.js/ts/py       # Actor entry point
storage/                # Local-only storage (NOT synced to Apify Console)
├── datasets/           # Output items (JSON objects)
├── key_value_stores/   # Files, config, INPUT
└── request_queues/     # Pending crawl requests
Dockerfile              # Container image definition

In Standby mode, per-request data is received via HTTP query parameters or the request body.

Important: Do NOT look for per-request data in INPUT.json. The traditional input_schema.json is used only for Actor initialization and configuration, not for individual incoming requests.

The Key-Value Store schema organizes keys into logical groups called collections for easier data management and UI organization. You define these in a JSON file (e.g., .actor/key_value_store_schema.json).

Each collection can be identified by a specific key or a keyPrefix. Collections can also enforce contentTypes or validate JSON data using a jsonSchema.

{
    "actorKeyValueStoreSchemaVersion": 1,
    "title": "Key-Value Store Schema",
    "collections": {
        "documents": {
            "title": "Documents",
            "description": "Text documents stored by the Actor",
            "keyPrefix": "document-"
        },
        "images": {
            "title": "Images",
            "description": "Images stored by the Actor",
            "keyPrefix": "image-",
            "contentTypes": ["image/jpeg"]
        }
    }
}

Actors in the index are categorized into two tiers:

• apify: Maintained by Apify. These should always be preferred for reliability and support.
• community: Maintained by the community. These are used to fill gaps where official Actors may not exist.