docs: add agent skill (SKILL.md) for the Apify CLI by patrikbraborec · Pull Request #1233 · apify/apify-cli

patrikbraborec · 2026-06-29T10:15:34Z

What

Adds skills/apify/SKILL.md — an agent-discoverable skill for the Apify CLI, mirroring the GitHub CLI's skills/gh/SKILL.md.

It's a markdown file (YAML frontmatter + guidance) that coding agents auto-load when a task touches the Apify CLI. It doesn't change CLI behavior — it encodes the non-obvious operational knowledge needed to drive apify reliably from automation.

Non-interactive use — bypassing the create/init/login wizards; -y/--yes confirmations.
Auth — APIFY_TOKEN for automation; apify info to verify; apify auth token.
Structured output — --json on list/info commands; --limit/--offset; apify datasets get-items --format json.
Core workflows — create → run → push; apify call / apify actors start; runs/builds wait, info, log.
Storage — datasets and key-value stores.
Escape hatch — apify api with --list-endpoints / --describe.

Every flag and command was verified against docs/reference.md. The skill points to docs/reference.md and apify help <command> for exhaustive detail rather than duplicating it.

Notes

Doc-only addition in a new skills/ folder — no command registration or update-docs regeneration needed.
Formatted with Prettier (passes prettier --check).

Closes #1232

🤖 Generated with Claude Code

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>

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>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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>

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>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

l2ysho

This seems nice. I got some nits from my review with this skill, mainly it suggest to not provide a list of option as part of skill, rather let agent get the actual list by him self. Seems legit for me, but nonblocking.

Co-authored-by: Richard Solar <solar.richard@gmail.com>

patrikbraborec · 2026-06-29T12:56:17Z

Thanks @l2ysho! Good comments.

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>

Co-authored-by: Cursor <cursoragent@cursor.com>

DaveHanns · 2026-06-30T09:09:34Z

 ARGUMENTS
  commandString  The command to get help for.
+
+FLAGS


Suggestion: the --skills read as if it should list all available skills or provide a skills for a certain command. It is a bit misleading.

What about --agent-guide?
-> apify help --agent-guide

Or, to be at least in sync with mcpc, it should be singular --skill.
https://apify.slack.com/archives/C0ANU2AFS3D/p1782748998055599?thread_ts=1782728951.631509&cid=C0ANU2AFS3D

DaveHanns · 2026-06-30T09:11:12Z

  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 


Super nit: is this really better? 🤔

That was my suggestion, so I can answer: jumping from "executes" and "reads" to an imperative creates some dissonance. We still have human readers :D

Co-authored-by: Cursor <cursoragent@cursor.com>

DaveHanns · 2026-06-30T09:31:22Z

+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):
+
+```bash
+mkdir -p ~/.agents/skills/apify
+apify help --skills > ~/.agents/skills/apify/SKILL.md


Nit: the skill should be named more specific, e.g.: ~/.claude/skills/apify-cli and ~/.agents/skills/apify-cli or even apify-cli-agentic-guide or apify-cli-agentic-help.

DaveHanns · 2026-06-30T14:57:59Z

+
+		const parent = dirname(dir);
+
+		if (parent === dir) {


Nit: worth adding a comment here that that dirname of the root (/ in UNIX and C:\) returns the root itself.

DaveHanns · 2026-06-30T15:03:38Z

+
+## Auth
+
+- Preferred for automation: set `APIFY_TOKEN` in the environment (no `apify login` needed). Get a token at https://console.apify.com/settings/integrations.


Suggestion: this might be potentially dangerous. If user, for any reason, has the APIFY_TOKEN already present in their environment, it would use it implicitly and possibly silently.

Overall, we should, instead, refer to https://apify.com/auth.md here.

Additional instructions on authentication bellow are fine, but also not ideal as we are going to have 2 sources of truth. The auth.md should have a CLI section instead (working on one currently).

DaveHanns · 2026-06-30T15:09:02Z

+
+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`).


prefer a FREE Actor when one covers the task.

Might lead to agents picking FREE over well supported, popular and well rated Actors. We might need more clarification that it is a combination of all above that matters.

DaveHanns

Mostly nits, some suggestions (mainly the flag name).
Otherwise looks good 🚀

patrikbraborec requested review from DaveHanns and l2ysho as code owners June 29, 2026 10:15

patrikbraborec and others added 7 commits June 29, 2026 12:19

docs: lead the Apify CLI skill with apify -h

e5cd6d1

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>

docs: drop Notes section from the Apify CLI skill

55f9f44

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs: document installing the Apify CLI agent skill in the README

a7bfa5e

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>

docs: tighten the Agent skill section in the README

16b3bdf

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs: rename agent skill to apify-cli

54af37e

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs: drop redundant title and intro from the apify-cli skill

004a6c2

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

l2ysho approved these changes Jun 29, 2026

View reviewed changes

Comment thread skills/apify/SKILL.md Outdated

Comment thread skills/apify/SKILL.md Outdated

patrikbraborec and others added 3 commits June 29, 2026 14:43

Merge branch 'master' into feat/apify-cli-agent-skill

0e67e30

Update skills/apify/SKILL.md

4ee7c47

Co-authored-by: Richard Solar <solar.richard@gmail.com>

Update skills/apify/SKILL.md

92eb99c

Co-authored-by: Richard Solar <solar.richard@gmail.com>

patrikbraborec requested a review from szaganek as a code owner June 30, 2026 08:34

fix: embed apify skill in bundled CLI

078a167

Co-authored-by: Cursor <cursoragent@cursor.com>

DaveHanns reviewed Jun 30, 2026

View reviewed changes

fix: remove misleading init guidance from apify skill

c78e550

Co-authored-by: Cursor <cursoragent@cursor.com>

DaveHanns reviewed Jun 30, 2026

View reviewed changes

patrikbraborec mentioned this pull request Jun 30, 2026

Add link to Apify CLI skill from the docs #1242

Open

DaveHanns reviewed Jun 30, 2026

View reviewed changes

DaveHanns requested changes Jun 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add agent skill (SKILL.md) for the Apify CLI#1233

docs: add agent skill (SKILL.md) for the Apify CLI#1233
patrikbraborec wants to merge 14 commits into
masterfrom
feat/apify-cli-agent-skill

patrikbraborec commented Jun 29, 2026

Uh oh!

l2ysho left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

patrikbraborec commented Jun 29, 2026

Uh oh!

DaveHanns Jun 30, 2026 •

edited

Loading

Uh oh!

DaveHanns Jun 30, 2026

Uh oh!

DaveHanns Jun 30, 2026

Uh oh!

szaganek Jun 30, 2026

Uh oh!

DaveHanns Jun 30, 2026

Uh oh!

DaveHanns Jun 30, 2026

Uh oh!

DaveHanns Jun 30, 2026

Uh oh!

DaveHanns Jun 30, 2026 •

edited

Loading

Uh oh!

DaveHanns left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		## Auth

		- Preferred for automation: set `APIFY_TOKEN` in the environment (no `apify login` needed). Get a token at https://console.apify.com/settings/integrations.


		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`).

Uh oh!

Conversation

patrikbraborec commented Jun 29, 2026

What

Contents

Notes

Uh oh!

l2ysho left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

patrikbraborec commented Jun 29, 2026

Uh oh!

DaveHanns Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DaveHanns Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

DaveHanns Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

szaganek Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

DaveHanns Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

DaveHanns Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

DaveHanns Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

DaveHanns Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DaveHanns left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

l2ysho left a comment •

edited

Loading

DaveHanns Jun 30, 2026 •

edited

Loading

DaveHanns Jun 30, 2026 •

edited

Loading