docs(skills): add common Actor patterns to apify-actor-development SKILL.md

[DaveHanns]

Summary

The apify-actor-development skill currently omits several patterns that come up in almost every non-trivial Actor. Agents (both human and LLM) authoring Actors from this skill repeatedly rediscover them the hard way — with a stack trace or a data leak.

This PR adds a Common patterns section to skills/apify-actor-development/SKILL.md covering six such gaps, each with a copy-pasteable snippet. Two larger reference implementations go under references/, following the existing layout.

The six gaps

1. Network robustness — wrap fetch in try/catch + retry

Unwrapped fetch() turns a transient upstream 503 into an Actor-level RUNTIME_ERROR. The skill mentions "Implement retry strategies with exponential backoff" in the best-practices bullet list but never shows what that looks like for a plain fetch call outside a Crawlee crawler. New snippet + full reference at references/robust-fetch.ts.

2. API keys and secrets — isSecret: true

references/input-schema.md does not mention isSecret. Without it, an apiKey field is stored in plaintext in the run object and shown in the Console UI. New snippet demonstrates the input-schema declaration + reading it via Actor.getInput().

3. Persisting state across scheduled / cron runs

Each run gets its own default key-value store, so Actor.setValue(key, val) does not survive to the next run. Two documented patterns:

• Named KV store (Actor.openKeyValueStore('my-actor-state')) — requires a full-scope token.
• Previous-run lookup via REST — for LIMITED_PERMISSIONS scheduled runs where opening a named store fails with Permission denied. Lists the Actor's previous SUCCEEDED runs and reads the newest one's default KV store.

Also documents .actor/actor.json's environmentVariables object form (I've seen the array form attempted and silently ignored) and the @secretName reference syntax with apify secrets add. Full reference at references/cross-run-state.ts.

4. Key-value store key charset

KV keys must match /^[a-zA-Z0-9!\-_.'()]{1,256}$/. A natural key like user:${userId}:${timestamp} throws:

ArgumentError: (string `key`) must be at most 256 characters long and only contain: a-zA-Z0-9!-_.'()

from setValue(). New snippet gives the regex explicitly + a one-line sanitizer.

5. Progress reporting — Actor.setStatusMessage

Long-running Actors should surface progress so the Console UI shows what phase they're in. New snippet demonstrates both the normal call and the isStatusTerminal: true option for terminal failure states.

6. Prefer MCP tools over raw REST

The existing "MCP tools" section only lists search-apify-docs and fetch-apify-docs. In practice agents fall back to hand-rolled curl calls against api.apify.com because they don't know an MCP tool covers what they need. New enumeration of the common mcp__apify__* tools (search-actors, get-actor, call-actor, get-actor-run, get-actor-run-log, get-dataset-items, get-key-value-store-record) with one-line descriptions.

Files changed

• skills/apify-actor-development/SKILL.md — new "Common patterns" section between "Best practices" and "Logging"; six subsections as above.
• skills/apify-actor-development/references/robust-fetch.ts — new file, full retry helper with timeouts and configurable retry statuses.
• skills/apify-actor-development/references/cross-run-state.ts — new file, helpers for both cross-run KV patterns plus a sanitizeKvKey utility.

Test plan

• SKILL.md renders on GitHub — each of the six subsections has a working code snippet.
• The "Prefer MCP tools over raw REST" list shows concrete mcp__apify__* tool names with one-line descriptions.
• references/robust-fetch.ts compiles under the skill's TypeScript target (no top-level imports beyond apify).
• references/cross-run-state.ts compiles under the skill's TypeScript target; both the named-store and previous-run patterns are exercised.

---

Surfaced during an evaluation of Apify surfaces for agent-driven Actor development.