From 64caad1004e7bc4fa0c56452aa85200f1e3b2eda Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 12:15:17 +0200
Subject: [PATCH 01/20] docs: add agent skill (SKILL.md) for the Apify CLI

Ships skills/apify/SKILL.md, an agent-discoverable skill that teaches
coding agents how to drive the Apify CLI reliably from automation:
non-interactive use, auth via APIFY_TOKEN, --json structured output,
core create/run/push and call workflows, storage access, and the
`apify api` escape hatch. Mirrors the layout of the gh CLI's skill.

Closes #1232

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 skills/apify/SKILL.md | 91 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 skills/apify/SKILL.md

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
new file mode 100644
index 000000000..c874c5391
--- /dev/null
+++ b/skills/apify/SKILL.md
@@ -0,0 +1,91 @@
+---
+name: apify
+description: Drive the Apify CLI (`apify`) reliably from automation — authenticate, create/run/push Actors, call Actors in the cloud, and read results from datasets and key-value stores. Use when a task involves the Apify CLI, Apify Actors, Apify storage (datasets, key-value stores, request queues), or the Apify platform from the terminal.
+---
+
+# Apify CLI
+
+The `apify` CLI manages the Apify platform and develops, runs, and deploys Actors (serverless cloud programs). This guide covers the non-obvious operational knowledge for driving it from automation. For the exhaustive command list, run `apify help` or read `docs/reference.md`; for any flag, run `apify help <command>`.
+
+## Non-interactive use
+
+Many commands prompt when run interactively. To run without prompts, pass every required argument and flag explicitly:
+
+- `apify create <name> --template <template>` — skip the create wizard.
+- `apify init <name>` or `apify init --yes` — skip the init prompt.
+- `-y` / `--yes` on destructive commands (`apify actors rm`, etc.) — auto-confirm.
+- `apify login --token <token>` — log in without the interactive token prompt.
+
+If a command's help shows an "interactive note", it lists exactly which flags make it non-interactive.
+
+## Auth
+
+- Preferred for automation: set `APIFY_TOKEN` in the environment (no `apify login` needed). Get a token at https://console.apify.com/settings/integrations.
+- Or persist a session once: `apify login --token <token>`.
+- Verify auth: `apify info` (prints the logged-in user; non-zero exit / error if not authenticated).
+- Print the stored token: `apify auth token`.
+
+## Structured output
+
+- `--json` is supported on most list/info commands (`apify actors ls --json`, `apify actors info <id> --json`, `apify datasets info <id> --json`, `apify runs ls --json`, etc.). Use it and parse with `jq`; don't scrape the human table.
+- List commands paginate — control with `--limit` / `--offset` (and `--desc`).
+- Dataset items: `apify datasets get-items <datasetId> --format json` (also `jsonl`, `csv`, `xlsx`, `html`, `rss`, `xml`). Use `--limit` / `--offset`.
+
+## Core workflows
+
+**Develop and deploy a local Actor**
+
+```sh
+apify create my-actor --template <template>     # or run `apify create` and pick interactively
+# template names: https://raw.githubusercontent.com/apify/actor-templates/master/templates/manifest.json
+cd my-actor
+apify run                                        # run locally; --input / --input-file - for input
+apify push                                       # build & deploy to the platform
+```
+
+**Run an Actor in the cloud and get results**
+
+```sh
+apify call apify/website-content-crawler -i '{"startUrls":[{"url":"https://example.com"}]}' --json
+# or non-blocking: apify actors start <actor> --json   (returns run details immediately)
+# inspect input schema first: apify actors info <actor> --input
+```
+
+`apify call` flags: `-i`/`--input` inline JSON, `-f`/`--input-file` (use `-` for stdin), `-o`/`--output-dataset` to print the result dataset, `-s`/`--silent`, `-m`/`--memory`, `-t`/`--timeout`, `-b`/`--build`.
+
+**Wait for and inspect runs/builds**
+
+```sh
+apify runs ls --json
+apify runs info <runId> --json
+apify runs wait <runId>          # block until finished
+apify runs log <runId>
+apify builds wait <buildId>
+```
+
+**Storage**
+
+```sh
+apify datasets get-items <datasetId> --format json
+apify key-value-stores get-value <storeId> <key>
+apify key-value-stores set-value <storeId> <key> <value>
+apify key-value-stores keys <storeId> --json
+```
+
+## Escape hatch: `apify api`
+
+Any platform capability without a dedicated command is reachable via the authenticated API wrapper:
+
+```sh
+apify api --list-endpoints                 # discover endpoints (filter with -s "<tokens>")
+apify api --describe "actor-runs/{runId}"  # methods, summary, path params for an endpoint
+apify api GET /v2/users/me                 # GET is the default method
+apify api POST acts -d '<json>' -p '{"limit":1}'   # -d body (use - for stdin), -p query params
+```
+
+The `v2/` prefix and leading slash are optional.
+
+## Notes
+
+- A second binary, `actor`, is the in-Actor runtime CLI (used inside a running Actor for `get-input`, `push-data`, `set-value`, etc.), not for managing the platform from your machine.
+- Override the API base URL with `APIFY_CLIENT_BASE_URL` (e.g. for staging).

From 1047ae25b709d30f981ce8ac864353bb23fd70ef Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 12:19:18 +0200
Subject: [PATCH 02/20] docs: lead the Apify CLI skill with `apify -h`

Add a "Start here" section telling agents to run `apify -h` (and
`apify <command> -h`) first as the source of truth for commands and flags.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 skills/apify/SKILL.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index c874c5391..e98eff540 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -1,11 +1,15 @@
 ---
 name: apify
-description: Drive the Apify CLI (`apify`) reliably from automation — authenticate, create/run/push Actors, call Actors in the cloud, and read results from datasets and key-value stores. Use when a task involves the Apify CLI, Apify Actors, Apify storage (datasets, key-value stores, request queues), or the Apify platform from the terminal.
+description: Patterns for invoking the Apify CLI (`apify`) from agents. Covers authentication, creating/running/pushing Actors, calling Actors in the cloud, and reading results from datasets and key-value stores.
 ---
 
 # Apify CLI
 
-The `apify` CLI manages the Apify platform and develops, runs, and deploys Actors (serverless cloud programs). This guide covers the non-obvious operational knowledge for driving it from automation. For the exhaustive command list, run `apify help` or read `docs/reference.md`; for any flag, run `apify help <command>`.
+The `apify` CLI manages the Apify platform and develops, runs, and deploys Actors (serverless cloud programs). This guide covers the non-obvious operational knowledge for driving it from automation.
+
+## Start here
+
+Run `apify -h` first to see the available commands and global options, then `apify <command> -h` (e.g. `apify call -h`) for the args and flags of a specific command. This is the source of truth — prefer it over assumptions.
 
 ## Non-interactive use
 

From 10de86baa85cb9ab8e380e774187aaa81aad22ed Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 12:21:06 +0200
Subject: [PATCH 03/20] docs: drop Notes section from the Apify CLI skill

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 skills/apify/SKILL.md | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index e98eff540..6595104ad 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -88,8 +88,3 @@ apify api POST acts -d '<json>' -p '{"limit":1}'   # -d body (use - for stdin),
 ```
 
 The `v2/` prefix and leading slash are optional.
-
-## Notes
-
-- A second binary, `actor`, is the in-Actor runtime CLI (used inside a running Actor for `get-input`, `push-data`, `set-value`, etc.), not for managing the platform from your machine.
-- Override the API base URL with `APIFY_CLIENT_BASE_URL` (e.g. for staging).

From 92d8964151b4999cbb143065b64144f7d2450e9a Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 12:24:11 +0200
Subject: [PATCH 04/20] docs: document installing the Apify CLI agent skill in
 the README

Add an "Agent skill" section with `npx skills add apify/apify-cli`
install instructions (project-level and global).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/README.md b/README.md
index 740eb0158..32bd25ef6 100644
--- a/README.md
+++ b/README.md
@@ -94,6 +94,20 @@ The table below lists the most common commands. For the full reference, see the
 
 Actor configuration lives in `.actor/actor.json`. See the [Actor configuration docs](https://docs.apify.com/platform/actors/development/actor-definition/actor-json) for the full schema (name, version, build tag, environment variables, Dockerfile, input schema, storages).
 
+## Agent skill
+
+This repo ships an [agent skill](./skills/apify/SKILL.md) that teaches AI coding agents (Claude Code, Cursor, etc.) how to drive the Apify CLI reliably. Install it into your project with the [`skills`](https://www.npmjs.com/package/skills) CLI:
+
+```bash
+# install into the current project
+npx skills add apify/apify-cli
+
+# or install globally for all projects
+npx skills add apify/apify-cli --global
+```
+
+This is optional — the CLI works the same with or without it. The skill just gives your agent the operational know-how (non-interactive flags, `--json` output, auth, common workflows) so it uses the CLI correctly.
+
 ## Documentation
 
 - [Apify CLI documentation](https://docs.apify.com/cli)

From bcfa29e26e8abff175eef4aa8524a51e58dd997c Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 12:26:59 +0200
Subject: [PATCH 05/20] docs: lead quick start with an `apify call` example

Replace the create/run/push flow in the quick start with a single
`apify call apify/hello-world --output-dataset` example so new users
can run an Actor and see results immediately. The create wizard is
still mentioned for building your own Actor.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md | 37 ++++++++++++++++++-------------------
 1 file changed, 18 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 32bd25ef6..f844d6046 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,20 @@ Apify CLI is the command-line tool for creating, developing, and deploying [Apif
 - Manage secret environment variables used by your Actors
 - Works with any programming language — Actors run as Docker containers on the platform
 
+## Agent skill
+
+This repo ships an [agent skill](./skills/apify/SKILL.md) that teaches AI coding agents (Claude Code, Cursor, etc.) how to drive the Apify CLI reliably. Install it into your project with the [`skills`](https://www.npmjs.com/package/skills) CLI:
+
+```bash
+# install into the current project
+npx skills add apify/apify-cli
+
+# or install globally for all projects
+npx skills add apify/apify-cli --global
+```
+
+This is optional — the CLI works the same with or without it. The skill just gives your agent the operational know-how (non-interactive flags, `--json` output, auth, common workflows) so it uses the CLI correctly.
+
 ## Quick start
 
 1. **Install the CLI** (macOS / Linux):
@@ -29,15 +43,14 @@ Apify CLI is the command-line tool for creating, developing, and deploying [Apif
    apify login
    ```
 
-3. **Create, run, and deploy** your first Actor:
+3. **Run an Actor** on the Apify cloud:
 
    ```bash
-   apify create # it will walk you through an interactive wizard
-   cd my-actor
-   apify run
-   apify push
+   apify call apify/hello-world --output-dataset
    ```
 
+   This runs the public [`apify/hello-world`](https://apify.com/apify/hello-world) Actor and prints its results. To build your own Actor instead, run `apify create` and follow the interactive wizard.
+
 ## Installation
 
 ### macOS / Linux (bundle, recommended)
@@ -94,20 +107,6 @@ The table below lists the most common commands. For the full reference, see the
 
 Actor configuration lives in `.actor/actor.json`. See the [Actor configuration docs](https://docs.apify.com/platform/actors/development/actor-definition/actor-json) for the full schema (name, version, build tag, environment variables, Dockerfile, input schema, storages).
 
-## Agent skill
-
-This repo ships an [agent skill](./skills/apify/SKILL.md) that teaches AI coding agents (Claude Code, Cursor, etc.) how to drive the Apify CLI reliably. Install it into your project with the [`skills`](https://www.npmjs.com/package/skills) CLI:
-
-```bash
-# install into the current project
-npx skills add apify/apify-cli
-
-# or install globally for all projects
-npx skills add apify/apify-cli --global
-```
-
-This is optional — the CLI works the same with or without it. The skill just gives your agent the operational know-how (non-interactive flags, `--json` output, auth, common workflows) so it uses the CLI correctly.
-
 ## Documentation
 
 - [Apify CLI documentation](https://docs.apify.com/cli)

From 13870c7373ba72d4a21331689cb5c013f7207a39 Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 12:29:12 +0200
Subject: [PATCH 06/20] docs: tighten the Agent skill section in the README

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/README.md b/README.md
index f844d6046..44eddb402 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ Apify CLI is the command-line tool for creating, developing, and deploying [Apif
 
 ## Agent skill
 
-This repo ships an [agent skill](./skills/apify/SKILL.md) that teaches AI coding agents (Claude Code, Cursor, etc.) how to drive the Apify CLI reliably. Install it into your project with the [`skills`](https://www.npmjs.com/package/skills) CLI:
+This repo ships an [agent skill](./skills/apify/SKILL.md) that teaches AI coding agents (Claude Code, Cursor, etc.) how to work with the Apify CLI reliably. Install it into your project with the [`skills`](https://www.npmjs.com/package/skills) CLI:
 
 ```bash
 # install into the current project
@@ -25,8 +25,6 @@ npx skills add apify/apify-cli
 npx skills add apify/apify-cli --global
 ```
 
-This is optional — the CLI works the same with or without it. The skill just gives your agent the operational know-how (non-interactive flags, `--json` output, auth, common workflows) so it uses the CLI correctly.
-
 ## Quick start
 
 1. **Install the CLI** (macOS / Linux):

From 5350c15d9320a72f199397df4168662e329356da Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 12:30:48 +0200
Subject: [PATCH 07/20] docs: rename agent skill to apify-cli

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 skills/apify/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index 6595104ad..56b39a965 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: apify
+name: apify-cli
 description: Patterns for invoking the Apify CLI (`apify`) from agents. Covers authentication, creating/running/pushing Actors, calling Actors in the cloud, and reading results from datasets and key-value stores.
 ---
 

From b467df9fd662a555e1d1219aef938a3df7fbbaf9 Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 12:31:41 +0200
Subject: [PATCH 08/20] docs: drop redundant title and intro from the apify-cli
 skill

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 skills/apify/SKILL.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index 56b39a965..2ea145255 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -3,10 +3,6 @@ name: apify-cli
 description: Patterns for invoking the Apify CLI (`apify`) from agents. Covers authentication, creating/running/pushing Actors, calling Actors in the cloud, and reading results from datasets and key-value stores.
 ---
 
-# Apify CLI
-
-The `apify` CLI manages the Apify platform and develops, runs, and deploys Actors (serverless cloud programs). This guide covers the non-obvious operational knowledge for driving it from automation.
-
 ## Start here
 
 Run `apify -h` first to see the available commands and global options, then `apify <command> -h` (e.g. `apify call -h`) for the args and flags of a specific command. This is the source of truth — prefer it over assumptions.

From c35a6269e8e7ff4cf39d8185b8dbb919e7f4461c Mon Sep 17 00:00:00 2001
From: Patrik Braborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 14:55:50 +0200
Subject: [PATCH 09/20] Update skills/apify/SKILL.md

Co-authored-by: Richard Solar <solar.richard@gmail.com>
---
 skills/apify/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index 2ea145255..6511548ef 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -29,7 +29,7 @@ If a command's help shows an "interactive note", it lists exactly which flags ma
 
 - `--json` is supported on most list/info commands (`apify actors ls --json`, `apify actors info <id> --json`, `apify datasets info <id> --json`, `apify runs ls --json`, etc.). Use it and parse with `jq`; don't scrape the human table.
 - List commands paginate — control with `--limit` / `--offset` (and `--desc`).
-- Dataset items: `apify datasets get-items <datasetId> --format json` (also `jsonl`, `csv`, `xlsx`, `html`, `rss`, `xml`). Use `--limit` / `--offset`.
+- Dataset items: `apify datasets get-items <datasetId> --format json`. Use `--limit` / `--offset`.
 
 ## Core workflows
 

From 615699877d1c1358efd9485fac81a5f74102b3e8 Mon Sep 17 00:00:00 2001
From: Patrik Braborec <patrikbraborec@gmail.com>
Date: Mon, 29 Jun 2026 14:55:57 +0200
Subject: [PATCH 10/20] Update skills/apify/SKILL.md

Co-authored-by: Richard Solar <solar.richard@gmail.com>
---
 skills/apify/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index 6511548ef..6fd09ebb2 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -51,7 +51,7 @@ apify call apify/website-content-crawler -i '{"startUrls":[{"url":"https://examp
 # inspect input schema first: apify actors info <actor> --input
 ```
 
-`apify call` flags: `-i`/`--input` inline JSON, `-f`/`--input-file` (use `-` for stdin), `-o`/`--output-dataset` to print the result dataset, `-s`/`--silent`, `-m`/`--memory`, `-t`/`--timeout`, `-b`/`--build`.
+Non-obvious `apify call` flags: `-f -` reads input from stdin; `-o`/`--output-dataset` prints the result dataset. Run `apify call -h` for the full list.
 
 **Wait for and inspect runs/builds**
 

From 123f77c87b53ad96f5cc88b5871dc36ba6b08a9d Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Tue, 30 Jun 2026 10:31:51 +0200
Subject: [PATCH 11/20] feat: add `apify help --skills` to print the agent
 skill

Add a `--skills` flag to `apify help` that prints the bundled
`skills/apify/SKILL.md`, so agents always get guidance matching the
installed CLI version. Ship the `skills/` directory in the package,
update the README install instructions (Claude Code, Codex/.agents), and
expand the skill with Actor discovery, pricing, and scheduling workflows.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md                      | 26 +++++++++++++----
 docs/reference.md              | 13 ++++++---
 package.json                   |  3 +-
 skills/apify/SKILL.md          | 27 +++++++++++++++++-
 src/commands/help.ts           | 52 +++++++++++++++++++++++++++++++++-
 test/e2e/commands/help.test.ts |  6 ++++
 6 files changed, 115 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 44eddb402..ccda6c754 100644
--- a/README.md
+++ b/README.md
@@ -15,16 +15,32 @@ Apify CLI is the command-line tool for creating, developing, and deploying [Apif
 
 ## Agent skill
 
-This repo ships an [agent skill](./skills/apify/SKILL.md) that teaches AI coding agents (Claude Code, Cursor, etc.) how to work with the Apify CLI reliably. Install it into your project with the [`skills`](https://www.npmjs.com/package/skills) CLI:
+This repo ships an [agent skill](./skills/apify/SKILL.md) that teaches AI coding agents (Claude Code, Cursor, etc.) how to work with the Apify CLI reliably. You can print the skill straight from the CLI — it always matches your installed version:
 
 ```bash
-# install into the current project
-npx skills add apify/apify-cli
+apify help --skills
+```
+
+If you'd rather have the skill installed persistently, `apify help --skills` prints a valid `SKILL.md` that you can redirect into your agent's skills directory. The location depends on the agent:
+
+### Claude Code
+
+```bash
+mkdir -p ~/.claude/skills/apify
+apify help --skills > ~/.claude/skills/apify/SKILL.md
+```
+
+### Codex and other agents
+
+Codex and most other agents follow the [Agent Skills open standard](https://developers.openai.com/codex/skills), which loads skills from `.agents/skills` (per repo) or `~/.agents/skills` (per user):
 
-# or install globally for all projects
-npx skills add apify/apify-cli --global
+```bash
+mkdir -p ~/.agents/skills/apify
+apify help --skills > ~/.agents/skills/apify/SKILL.md
 ```
 
+That copy is a snapshot; re-run it after upgrading the Apify CLI to refresh it.
+
 ## Quick start
 
 1. **Install the CLI** (macOS / Linux):
diff --git a/docs/reference.md b/docs/reference.md
index ca2b9fe31..3bc59c58a 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -21,10 +21,14 @@ DESCRIPTION
   Prints out help about a command, or all available commands.
 
 USAGE
-  $ apify help [commandString]
+  $ apify help [commandString] [--skills]
 
 ARGUMENTS
   commandString  The command to get help for.
+
+FLAGS
+      --skills  Print the Apify CLI agent skill (guidance for driving
+                `apify` from agents).
 ```
 
 ##### `apify upgrade`
@@ -782,7 +786,8 @@ FLAGS
 DESCRIPTION
   Executes Actor remotely using your authenticated account.
   Reads input from local key-value store by default.
-  Inspect the input schema first with "apify actors info <actor> --input".
+  To inspect the input schema before creating a JSON input, use "apify actors 
+  info <actor> --input".
 
 USAGE
   $ apify actors call [actorId] [-b <value>]
@@ -799,8 +804,8 @@ FLAGS
   -b, --build=<value>       Tag or number of the build to
                             run (e.g. "latest" or "1.2.34").
   -i, --input=<value>       Optional inline JSON object
-                            input for the Actor. Wrap the JSON in quotes to avoid
-                            shell parsing issues. For JSON files, use --input-file.
+                            input for the Actor. To avoid shell parsing issues, wrap
+                            the JSON in quotes. For JSON files, use --input-file.
   -f, --input-file=<value>  Optional path to a file with
                             JSON input to be given to the Actor. The file must be a
                             valid JSON file. You can also specify `-` to read from
diff --git a/package.json b/package.json
index 9ef746bcd..021c77a38 100644
--- a/package.json
+++ b/package.json
@@ -27,7 +27,8 @@
 		"prepare": "husky"
 	},
 	"files": [
-		"dist"
+		"dist",
+		"skills"
 	],
 	"bin": {
 		"actor": "./dist/actor.js",
diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index 6fd09ebb2..e36c22864 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -33,6 +33,19 @@ If a command's help shows an "interactive note", it lists exactly which flags ma
 
 ## Core workflows
 
+**Discover Actors in the Apify Store**
+
+Before assuming an Actor name or scripting a raw Store query, search for an existing Actor:
+
+```sh
+apify actors search "jobs scraper" --json                 # no auth required
+apify actors search "ai" --pricing-model FREE --sort-by popularity --limit 5
+```
+
+Run `apify actors search -h` to see the available filters (pricing model, category, username, sort order, pagination) and their accepted values.
+
+Pricing matters: prefer a `FREE` Actor when one covers the task. Check an Actor's pricing before running it with `apify actors info <actor> --json` (look at `currentPricingInfo`).
+
 **Develop and deploy a local Actor**
 
 ```sh
@@ -72,9 +85,21 @@ apify key-value-stores set-value <storeId> <key> <value>
 apify key-value-stores keys <storeId> --json
 ```
 
+## Scheduling and recurring runs
+
+For anything recurring or unattended (e.g. "run every 15 minutes"), use the Apify platform — **not** local `cron`, a `while` loop, or GitHub Actions. Apify Schedules run in the cloud, so they keep firing after your laptop, terminal, or agent session is shut down.
+
+- Save a reusable input config as a **task**, then run it: `apify task run <taskId>`.
+- There is no dedicated `apify schedules` command yet — manage schedules via `apify api` against the `schedules` endpoint, or in the Console (https://console.apify.com/schedules):
+
+```sh
+apify api GET schedules
+apify api POST schedules -d '{"name":"jobs-every-15m","cronExpression":"*/15 * * * *","isEnabled":true,"actions":[{"type":"RUN_ACTOR","actorId":"<actorId>","runInput":{"body":"<json>","contentType":"application/json"}}]}'
+```
+
 ## Escape hatch: `apify api`
 
-Any platform capability without a dedicated command is reachable via the authenticated API wrapper:
+Any platform capability without a dedicated command is reachable via the authenticated API wrapper (use this instead of hand-rolling `curl` against `api.apify.com` — it injects auth for you):
 
 ```sh
 apify api --list-endpoints                 # discover endpoints (filter with -s "<tokens>")
diff --git a/src/commands/help.ts b/src/commands/help.ts
index 568966797..1ae63545e 100644
--- a/src/commands/help.ts
+++ b/src/commands/help.ts
@@ -1,10 +1,39 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 import chalk from 'chalk';
 
 import { ApifyCommand, commandRegistry } from '../lib/command-framework/apify-command.js';
 import { Args } from '../lib/command-framework/args.js';
+import { Flags } from '../lib/command-framework/flags.js';
 import { renderHelpForCommand, renderMainHelpMenu } from '../lib/command-framework/help.js';
 import { useCommandSuggestions } from '../lib/hooks/useCommandSuggestions.js';
-import { error } from '../lib/outputs.js';
+import { error, simpleLog } from '../lib/outputs.js';
+
+const SKILL_RELATIVE_PATH = join('skills', 'apify', 'SKILL.md');
+
+// Walk up from this file until we find the `skills/apify/SKILL.md` shipped with the package.
+// This resolves both when running from source (`src/commands`) and from the built `dist`.
+function readApifySkill(): string | null {
+	let dir = dirname(fileURLToPath(import.meta.url));
+
+	while (true) {
+		const candidate = join(dir, SKILL_RELATIVE_PATH);
+
+		if (existsSync(candidate)) {
+			return readFileSync(candidate, 'utf-8');
+		}
+
+		const parent = dirname(dir);
+
+		if (parent === dir) {
+			return null;
+		}
+
+		dir = parent;
+	}
+}
 
 export class HelpCommand extends ApifyCommand<typeof HelpCommand> {
 	static override name = 'help' as const;
@@ -21,9 +50,30 @@ export class HelpCommand extends ApifyCommand<typeof HelpCommand> {
 		}),
 	};
 
+	static override flags = {
+		skills: Flags.boolean({
+			description: 'Print the Apify CLI agent skill (guidance for driving `apify` from agents).',
+			default: false,
+		}),
+	};
+
 	async run() {
 		const { commandString } = this.args;
 
+		if (this.flags.skills) {
+			const skill = readApifySkill();
+
+			if (!skill) {
+				error({ message: 'Could not find the Apify CLI skill file.' });
+
+				return;
+			}
+
+			simpleLog({ stdout: true, message: skill.trimEnd() });
+
+			return;
+		}
+
 		if (!commandString || commandString.toLowerCase().startsWith('help')) {
 			const helpMenu = renderMainHelpMenu(this.entrypoint);
 
diff --git a/test/e2e/commands/help.test.ts b/test/e2e/commands/help.test.ts
index 4b4893665..3ef9217f7 100644
--- a/test/e2e/commands/help.test.ts
+++ b/test/e2e/commands/help.test.ts
@@ -36,4 +36,10 @@ describe.concurrent('[e2e] help command', () => {
 		expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
 		expect(result.stdout).toContain('Executes Actor locally with simulated Apify environment variables.');
 	});
+
+	it('apify help --skills prints the Apify CLI agent skill', async () => {
+		const result = await runCli('apify', ['help', '--skills']);
+		expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
+		expect(result.stdout).toContain('name: apify-cli');
+	});
 });

From 14d6681a254f2164354528af5ca29b75f37f4059 Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Tue, 30 Jun 2026 11:04:50 +0200
Subject: [PATCH 12/20] fix: embed apify skill in bundled CLI

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 scripts/build-cli-bundles.ts | 4 ++++
 src/commands/help.ts         | 8 ++++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/scripts/build-cli-bundles.ts b/scripts/build-cli-bundles.ts
index e710ab5cc..f021f40ca 100644
--- a/scripts/build-cli-bundles.ts
+++ b/scripts/build-cli-bundles.ts
@@ -68,6 +68,7 @@ const entryPoints = [
 // target below to the matching `@napi-rs/keyring-<platform>` subpackage so Bun's `--compile`
 // embeds that one native `.node`. Must match the specifier in `src/lib/credentials.ts`.
 const KEYRING_PLACEHOLDER = '__APIFY_KEYRING_NATIVE_SUBPACKAGE__';
+const APIFY_CLI_SKILL = readFileSync(new URL('../skills/apify/SKILL.md', import.meta.url), 'utf-8');
 
 // Maps the compiled (os, arch, libc) to the napi-rs keyring subpackage that ships its `.node`.
 // `supportedArchitectures` (pnpm-workspace.yaml) forces all of these into node_modules at build
@@ -110,6 +111,9 @@ for (const entryPoint of entryPoints) {
 		files: {
 			[entryPoint]: lines.join('\n'),
 		},
+		define: {
+			__APIFY_CLI_SKILL__: JSON.stringify(APIFY_CLI_SKILL),
+		},
 		outdir: fileURLToPath(new URL(`../bundles/fat-clis`, import.meta.url)),
 		conditions: 'node',
 		target: 'bun',
diff --git a/src/commands/help.ts b/src/commands/help.ts
index 1ae63545e..2ece28c42 100644
--- a/src/commands/help.ts
+++ b/src/commands/help.ts
@@ -11,11 +11,15 @@ import { renderHelpForCommand, renderMainHelpMenu } from '../lib/command-framewo
 import { useCommandSuggestions } from '../lib/hooks/useCommandSuggestions.js';
 import { error, simpleLog } from '../lib/outputs.js';
 
+declare const __APIFY_CLI_SKILL__: string | undefined;
+
 const SKILL_RELATIVE_PATH = join('skills', 'apify', 'SKILL.md');
 
-// Walk up from this file until we find the `skills/apify/SKILL.md` shipped with the package.
-// This resolves both when running from source (`src/commands`) and from the built `dist`.
 function readApifySkill(): string | null {
+	if (typeof __APIFY_CLI_SKILL__ === 'string' && __APIFY_CLI_SKILL__) {
+		return __APIFY_CLI_SKILL__;
+	}
+
 	let dir = dirname(fileURLToPath(import.meta.url));
 
 	while (true) {

From 6a441a4e13f7319afa7bce9fa4515a974ebfdb56 Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Tue, 30 Jun 2026 11:13:28 +0200
Subject: [PATCH 13/20] fix: remove misleading init guidance from apify skill

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 skills/apify/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index e36c22864..1b9284f58 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -12,7 +12,7 @@ Run `apify -h` first to see the available commands and global options, then `api
 Many commands prompt when run interactively. To run without prompts, pass every required argument and flag explicitly:
 
 - `apify create <name> --template <template>` — skip the create wizard.
-- `apify init <name>` or `apify init --yes` — skip the init prompt.
+- `apify init <name>` — skip the init prompt.
 - `-y` / `--yes` on destructive commands (`apify actors rm`, etc.) — auto-confirm.
 - `apify login --token <token>` — log in without the interactive token prompt.
 

From f5e52dfacf3afce4a96f3447fc87a7fb9c288e7a Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Wed, 1 Jul 2026 12:31:08 +0200
Subject: [PATCH 14/20] fix: rename `apify help --skills` flag to `--skill`

---
 README.md                      | 8 ++++----
 docs/reference.md              | 6 +++---
 src/commands/help.ts           | 4 ++--
 test/e2e/commands/help.test.ts | 4 ++--
 4 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index ccda6c754..58a497679 100644
--- a/README.md
+++ b/README.md
@@ -18,16 +18,16 @@ Apify CLI is the command-line tool for creating, developing, and deploying [Apif
 This repo ships an [agent skill](./skills/apify/SKILL.md) that teaches AI coding agents (Claude Code, Cursor, etc.) how to work with the Apify CLI reliably. You can print the skill straight from the CLI — it always matches your installed version:
 
 ```bash
-apify help --skills
+apify help --skill
 ```
 
-If you'd rather have the skill installed persistently, `apify help --skills` prints a valid `SKILL.md` that you can redirect into your agent's skills directory. The location depends on the agent:
+If you'd rather have the skill installed persistently, `apify help --skill` prints a valid `SKILL.md` that you can redirect into your agent's skills directory. The location depends on the agent:
 
 ### Claude Code
 
 ```bash
 mkdir -p ~/.claude/skills/apify
-apify help --skills > ~/.claude/skills/apify/SKILL.md
+apify help --skill > ~/.claude/skills/apify/SKILL.md
 ```
 
 ### Codex and other agents
@@ -36,7 +36,7 @@ Codex and most other agents follow the [Agent Skills open standard](https://deve
 
 ```bash
 mkdir -p ~/.agents/skills/apify
-apify help --skills > ~/.agents/skills/apify/SKILL.md
+apify help --skill > ~/.agents/skills/apify/SKILL.md
 ```
 
 That copy is a snapshot; re-run it after upgrading the Apify CLI to refresh it.
diff --git a/docs/reference.md b/docs/reference.md
index 3bc59c58a..09af9be11 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -21,14 +21,14 @@ DESCRIPTION
   Prints out help about a command, or all available commands.
 
 USAGE
-  $ apify help [commandString] [--skills]
+  $ apify help [commandString] [--skill]
 
 ARGUMENTS
   commandString  The command to get help for.
 
 FLAGS
-      --skills  Print the Apify CLI agent skill (guidance for driving
-                `apify` from agents).
+      --skill  Print the Apify CLI agent skill (guidance for driving
+               `apify` from agents).
 ```
 
 ##### `apify upgrade`
diff --git a/src/commands/help.ts b/src/commands/help.ts
index 2ece28c42..3a34d3e4f 100644
--- a/src/commands/help.ts
+++ b/src/commands/help.ts
@@ -55,7 +55,7 @@ export class HelpCommand extends ApifyCommand<typeof HelpCommand> {
 	};
 
 	static override flags = {
-		skills: Flags.boolean({
+		skill: Flags.boolean({
 			description: 'Print the Apify CLI agent skill (guidance for driving `apify` from agents).',
 			default: false,
 		}),
@@ -64,7 +64,7 @@ export class HelpCommand extends ApifyCommand<typeof HelpCommand> {
 	async run() {
 		const { commandString } = this.args;
 
-		if (this.flags.skills) {
+		if (this.flags.skill) {
 			const skill = readApifySkill();
 
 			if (!skill) {
diff --git a/test/e2e/commands/help.test.ts b/test/e2e/commands/help.test.ts
index 3ef9217f7..f57d562bb 100644
--- a/test/e2e/commands/help.test.ts
+++ b/test/e2e/commands/help.test.ts
@@ -37,8 +37,8 @@ describe.concurrent('[e2e] help command', () => {
 		expect(result.stdout).toContain('Executes Actor locally with simulated Apify environment variables.');
 	});
 
-	it('apify help --skills prints the Apify CLI agent skill', async () => {
-		const result = await runCli('apify', ['help', '--skills']);
+	it('apify help --skill prints the Apify CLI agent skill', async () => {
+		const result = await runCli('apify', ['help', '--skill']);
 		expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
 		expect(result.stdout).toContain('name: apify-cli');
 	});

From 4c31b32cd170966dbcfa2e1e3c8c970a70df6f55 Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Wed, 1 Jul 2026 12:33:31 +0200
Subject: [PATCH 15/20] fix: rephrase actors call description for consistent
 tone

Avoid an abrupt shift into imperative phrasing after "Executes..."/"Reads...".

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/reference.md           | 4 ++--
 src/commands/actors/call.ts | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/reference.md b/docs/reference.md
index 09af9be11..a76b9853a 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -786,8 +786,8 @@ FLAGS
 DESCRIPTION
   Executes Actor remotely using your authenticated account.
   Reads input from local key-value store by default.
-  To inspect the input schema before creating a JSON input, use "apify actors 
-  info <actor> --input".
+  Input schema can be inspected with "apify actors info <actor> --input" before 
+  creating a JSON input.
 
 USAGE
   $ apify actors call [actorId] [-b <value>]
diff --git a/src/commands/actors/call.ts b/src/commands/actors/call.ts
index e5f31e25d..779d1b537 100644
--- a/src/commands/actors/call.ts
+++ b/src/commands/actors/call.ts
@@ -28,7 +28,7 @@ export class ActorsCallCommand extends ApifyCommand<typeof ActorsCallCommand> {
 	static override description =
 		'Executes Actor remotely using your authenticated account.\n' +
 		'Reads input from local key-value store by default.\n' +
-		'To inspect the input schema before creating a JSON input, use "apify actors info <actor> --input".';
+		'Input schema can be inspected with "apify actors info <actor> --input" before creating a JSON input.';
 
 	static override group = 'Apify Console';
 

From 48037dbf9060a551d3799abc59c8d894f8b28866 Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Wed, 1 Jul 2026 12:34:10 +0200
Subject: [PATCH 16/20] Revert "fix: rephrase actors call description for
 consistent tone"

This reverts commit 4c31b32cd170966dbcfa2e1e3c8c970a70df6f55.
---
 docs/reference.md           | 4 ++--
 src/commands/actors/call.ts | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/reference.md b/docs/reference.md
index a76b9853a..09af9be11 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -786,8 +786,8 @@ FLAGS
 DESCRIPTION
   Executes Actor remotely using your authenticated account.
   Reads input from local key-value store by default.
-  Input schema can be inspected with "apify actors info <actor> --input" before 
-  creating a JSON input.
+  To inspect the input schema before creating a JSON input, use "apify actors 
+  info <actor> --input".
 
 USAGE
   $ apify actors call [actorId] [-b <value>]
diff --git a/src/commands/actors/call.ts b/src/commands/actors/call.ts
index 779d1b537..e5f31e25d 100644
--- a/src/commands/actors/call.ts
+++ b/src/commands/actors/call.ts
@@ -28,7 +28,7 @@ export class ActorsCallCommand extends ApifyCommand<typeof ActorsCallCommand> {
 	static override description =
 		'Executes Actor remotely using your authenticated account.\n' +
 		'Reads input from local key-value store by default.\n' +
-		'Input schema can be inspected with "apify actors info <actor> --input" before creating a JSON input.';
+		'To inspect the input schema before creating a JSON input, use "apify actors info <actor> --input".';
 
 	static override group = 'Apify Console';
 

From 8e7c7e9364dcae5838649f64494c33db64d16ed7 Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Wed, 1 Jul 2026 12:36:44 +0200
Subject: [PATCH 17/20] fix: use more specific skill directory name in README
 examples

Rename install target from ~/.claude/skills/apify to
~/.claude/skills/apify-cli (and the Codex equivalent) so it doesn't
collide with other "apify" skills.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 58a497679..c981c53f3 100644
--- a/README.md
+++ b/README.md
@@ -26,8 +26,8 @@ If you'd rather have the skill installed persistently, `apify help --skill` prin
 ### Claude Code
 
 ```bash
-mkdir -p ~/.claude/skills/apify
-apify help --skill > ~/.claude/skills/apify/SKILL.md
+mkdir -p ~/.claude/skills/apify-cli
+apify help --skill > ~/.claude/skills/apify-cli/SKILL.md
 ```
 
 ### Codex and other agents
@@ -35,8 +35,8 @@ apify help --skill > ~/.claude/skills/apify/SKILL.md
 Codex and most other agents follow the [Agent Skills open standard](https://developers.openai.com/codex/skills), which loads skills from `.agents/skills` (per repo) or `~/.agents/skills` (per user):
 
 ```bash
-mkdir -p ~/.agents/skills/apify
-apify help --skill > ~/.agents/skills/apify/SKILL.md
+mkdir -p ~/.agents/skills/apify-cli
+apify help --skill > ~/.agents/skills/apify-cli/SKILL.md
 ```
 
 That copy is a snapshot; re-run it after upgrading the Apify CLI to refresh it.

From a38499fd2351ea56c5d52ba11acc73fe107b494b Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Wed, 1 Jul 2026 12:38:25 +0200
Subject: [PATCH 18/20] fix: clarify root-dir termination check in help.ts

Address PR review nit from DaveHanns.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/commands/help.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/commands/help.ts b/src/commands/help.ts
index 3a34d3e4f..565d23ad3 100644
--- a/src/commands/help.ts
+++ b/src/commands/help.ts
@@ -31,6 +31,7 @@ function readApifySkill(): string | null {
 
 		const parent = dirname(dir);
 
+		// dirname of the root ("/" on UNIX, "C:\" on Windows) returns the root itself
 		if (parent === dir) {
 			return null;
 		}

From 285aee6e46207a54e24e46e150d511b07ac5b57d Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Wed, 1 Jul 2026 12:42:40 +0200
Subject: [PATCH 19/20] fix: don't encourage implicit APIFY_TOKEN use in skill
 auth section

Silently relying on a pre-existing APIFY_TOKEN could act on the wrong
account without the user knowing. Point to apify.com/auth.md instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 skills/apify/SKILL.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index 1b9284f58..35acb06c8 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -20,8 +20,9 @@ If a command's help shows an "interactive note", it lists exactly which flags ma
 
 ## Auth
 
-- Preferred for automation: set `APIFY_TOKEN` in the environment (no `apify login` needed). Get a token at https://console.apify.com/settings/integrations.
-- Or persist a session once: `apify login --token <token>`.
+See https://apify.com/auth.md for how to authenticate. Do not assume `APIFY_TOKEN` is already set in the environment and use it implicitly — confirm with the user first.
+
+- Persist a session explicitly: `apify login --token <token>`.
 - Verify auth: `apify info` (prints the logged-in user; non-zero exit / error if not authenticated).
 - Print the stored token: `apify auth token`.
 

From ffebf5ba3ed00cd575efc4d2f9c923b3fdc4998c Mon Sep 17 00:00:00 2001
From: patrikbraborec <patrikbraborec@gmail.com>
Date: Wed, 1 Jul 2026 12:44:07 +0200
Subject: [PATCH 20/20] fix: clarify pricing guidance in skill isn't a
 FREE-over-quality override

Address review feedback that "prefer FREE" could lead to picking a free
Actor over a well-supported, popular, highly-rated one.
---
 skills/apify/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/apify/SKILL.md b/skills/apify/SKILL.md
index 35acb06c8..fe697dbb8 100644
--- a/skills/apify/SKILL.md
+++ b/skills/apify/SKILL.md
@@ -45,7 +45,7 @@ apify actors search "ai" --pricing-model FREE --sort-by popularity --limit 5
 
 Run `apify actors search -h` to see the available filters (pricing model, category, username, sort order, pagination) and their accepted values.
 
-Pricing matters: prefer a `FREE` Actor when one covers the task. Check an Actor's pricing before running it with `apify actors info <actor> --json` (look at `currentPricingInfo`).
+Pricing matters, but weigh it alongside popularity, rating, and how well-maintained the Actor is — don't pick a `FREE` Actor over a well-supported, popular, highly-rated one just because it's free. Check an Actor's pricing before running it with `apify actors info <actor> --json` (look at `currentPricingInfo`).
 
 **Develop and deploy a local Actor**