Skip to content

docs(skill): add Common pitfalls section (F19+F22+F33+F48+F50+F52+F56)#60

Draft
DaveHanns wants to merge 1 commit into
apify:mainfrom
DaveHanns:skill-add-common-pitfalls-section
Draft

docs(skill): add Common pitfalls section (F19+F22+F33+F48+F50+F52+F56)#60
DaveHanns wants to merge 1 commit into
apify:mainfrom
DaveHanns:skill-add-common-pitfalls-section

Conversation

@DaveHanns

Copy link
Copy Markdown

Summary

Add a Common pitfalls (from real agent runs) section to skills/apify-actor-development/SKILL.md, sitting right before Best practices. Seven concrete teachings distilled from a 14-scenario × 5-stack eval sweep.

Teachings included

Finding Teaching
F22 Actor version must be MAJOR.MINOR; 1.0.0 fails at platform admission after upload.
F19 Prefer the default dataset for single-shape output; only create named datasets for multi-stream outputs.
F33 Always start from a template; signal for a valid scaffold is .actor/actor.json + Dockerfile (apify/actor-* base) + src/main.*.
F56 Without CLI, fetch templates from apify/actor-templates via the raw manifest.json.
F48 Browser scenarios use apify/actor-node-playwright-chrome (or puppeteer variant), not plain actor-node.
F50 Smoke-test Standby Actors with curl, not apify call; set defaultTimeoutSecs.
F52 Default key-value store scoping is per-run; LIMITED_PERMISSIONS breaks cross-run state.

Why now

These are all failure modes with high observed occurrence across eval runs (multiple scenarios × multiple stacks each). The Skill overlay in the eval harness already carries a local version of these — this PR upstreams the general-audience subset so every Skill consumer benefits, not just the eval runner.

Test plan

  • Render the SKILL.md locally and verify the new section appears where expected.
  • Cross-check each teaching against FINDINGS.md in the eval repo (findings F19, F22, F33, F48, F50, F52, F56).
  • Confirm no wording contradicts existing Best practices / Don't sections.

Add a new "Common pitfalls" section to the Apify Actor development
skill, ahead of Best practices. These are all failure modes we observed
repeatedly across cli-only / api-only / mcp-only / all / none stacks
in the 2026-06 eval sweep — each costs at least one wasted deploy or
build cycle when missed:

- Actor version must be MAJOR.MINOR — patch versions like 1.0.0 fail
  at platform admission after upload.
- Prefer the default dataset for single-shape output.
- Always scaffold from a template; hand-rolled files miss fields.
- Without CLI, fetch the template from apify/actor-templates via raw
  GitHub URLs and the manifest.
- Browser scenarios need apify/actor-node-playwright-chrome as the
  base image, not plain actor-node.
- Smoke-test Standby Actors with curl, not `apify call`; set
  defaultTimeoutSecs.
- Key-value store scoping changes under LIMITED_PERMISSIONS.

Every Skill consumer (Claude Desktop, Claude Code, other MCP hosts
loading the public skill) benefits from these teachings, not just the
eval harness.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants