Epic: `apify agent setup` connects local coding agents to Apify plugins, skills, and MCP

[patrikbraborec]

apify agent setup: one command that detects the coding agents installed on a machine and connects each one to Apify at the highest tier it supports. An Apify plugin where one exists, otherwise skills plus the Apify MCP server, otherwise MCP only, otherwise printed instructions. A hint after CLI install points people and agents at it.

Today the pieces exist but the user has to assemble them. apify mcp install <client> requires naming the client and holding a token, has no detection, and covers 7 clients. Skills come from apify help --skill, which the docs describe as a snapshot the user must reinstall on every CLI upgrade. Plugins ship from 15 per-platform repos generated by apify/apify-plugins-internal, and nothing in the CLI knows they exist.

Inspiration: stripe agent setup (detect, plan, prompt, apply, with a tiered fallback to downloaded skills) and Vercel's vercel agent init plus vercel skills.

Repositories

• apify/apify-cli: the apify agent command namespace, detection, plan, apply, state file, bundled catalog, and the post-install hint.
• apify/apify-plugins-internal: publish a catalog.json built from the platform configs that already drive the per-platform plugin sync.
• apify/agent-skills: drop the CLI command tables that duplicate apify help --skill.

Requirements

P0

• apify agent setup detects installed clients, proposes a plan, confirms once, and applies it.
• Tier ladder per client: plugin, then skills plus MCP, then MCP only, then manual instructions. The planner picks the highest tier the client supports and the catalog has an artifact for.
• Non-interactive mode and --json output when stdin is not a TTY, so a local agent can drive it headless.
• Idempotent: an already-configured client reports already_configured and exits 0.
• State file next to auth.json recording what was installed, which client, and at which tier.
• Catalog bundled in the CLI (plugin ids, marketplaces, skills repo, MCP URL), so the command needs no network call.
• The MCP URL the CLI writes carries ?client=apify-cli, matching the ?client=claude+code+plugin tag the Claude plugin already uses.
• apify mcp install <client> stays as the lower-level primitive that setup calls.

P1

• apify agent status and apify agent uninstall, both reading the state file.
• catalog.json fetched from apify/apify-plugins-internal as a best-effort upgrade. A failed fetch falls back to the bundled copy and exits 0 with skipped: offline.
• Migration: when a client gains a plugin, remove the loose skills and the duplicate MCP entry the plugin replaces.
• Post-install hint with the same wording on every surface: bundle install, apify upgrade, npm postinstall, the apify help footer (the only surface Homebrew users see), README, docs/installation.md, and docs/agent-skill.md.
• Sandbox detection (CI, non-TTY stdin, known sandbox env vars): print instructions instead of writing files, because the harness config lives outside the container.
• apify agent init writes an Apify block into the project's AGENTS.md or CLAUDE.md, wrapped in markers so it can be re-applied without touching the rest of the file, following vercel agent init. Content comes from the agentsmd platform in apify/apify-plugins-internal. This replaces the hand-written apify help --skill pointer asked for in ts-crawlee-cheerio ships broken: optional deps stripped, CI needs an uncommitted lockfile actor-templates#941 (section 4) and Agent DX: three help strings route agents to the wrong tool #1424 (section 3).

P2

• Remaining clients from the catalog: Copilot, OpenCode, Devin, Kimi, Factory, Qoder, ZCode, Grok Build, DeepSeek Harness, and MS 365 Copilot.
• Generate the command list in skills/apify/SKILL.md from the command registry during pnpm run update-docs, the way docs/reference.md is already generated.
• CI check in apify/agent-skills that fails when a skill contains a CLI command table.

Success metrics

• Setup runs per week split by client, tier, and outcome (installed, already_configured, skipped: offline, error). Target: success rate above 90%.
• Share of new installs that run setup within 7 days.
• MCP sessions and Actor runs attributable to the ?client=apify-cli tag.
• Duplicate configurations reported by apify agent status (a plugin plus loose skills, or two Apify MCP entries), trending to zero after migration ships.

Key unknowns / to be discussed

• One umbrella Apify plugin per ecosystem, or one plugin per skill? apify/agent-skills publishes per skill today, the generated plugin repos publish one.
• Does setup run apify login when there is no token, or only print the hint? Stripe does not touch auth, Vercel provisions a key inline.
• Default skills scope: project or user? Stripe and skills.sh default to project, the CLI docs say user.
• Keeping skills fresh without a plugin: npx skills add symlinks, a stub SKILL.md that loads current content on demand, or a hash-checked download.
• Do we apply to claude-plugins-official and openai-curated? Membership is what makes Stripe's plugin tier self-updating, and Apify is in neither.
• Unverified: whether the Apify MCP docs tools work fully anonymously, and how codex plugin add behaves for third-party git marketplaces.

References

• Prior art: stripe agent setup, vercel agent init, Vercel agent resources
• Plugin build pipeline: apify/apify-plugins-internal
• Related: feat: apify mcp install — one-command MCP setup for Claude, Cursor, Windsurf, and Copilot #1438 (detection ask this supersedes), AI Agent Integration — MCP install, Actor-as-tool, AI scaffolding, schema gen, diagnose #1443, Ship an agent skill (SKILL.md) for the Apify CLI #1232, Surface apify help --skill in the apify help output #1301
• Overlapping signposting work: Agent DX: three help strings route agents to the wrong tool #1424 (shares the apify help footer edit with the post-install hint above) and ts-crawlee-cheerio ships broken: optional deps stripped, CI needs an uncommitted lockfile actor-templates#941 (section 4)

Sub-issues to follow.

[patrikbraborec]

One item from the Stripe comparison that the epic does not cover yet: the skills index.

Stripe publishes https://docs.stripe.com/.well-known/skills/index.json, so npx skills add https://docs.stripe.com installs their skills with no CLI involved. https://docs.apify.com/.well-known/skills/index.json returned 404 on September 9, 2026. The docs site already serves Markdown (/llms.txt and the .md variant of any page return text/markdown), so this is a small change in apify/apify-docs. Worth adding under Repositories, and it is one answer to "Keeping skills fresh without a plugin": npx skills update handles it once the index exists.

Headless mode for agent setup (P0 above) should come from the global flag in #1451 rather than its own stdin check.