docs(skill): add Common pitfalls section (F19+F22+F33+F48+F50+F52+F56)#60
Draft
DaveHanns wants to merge 1 commit into
Draft
docs(skill): add Common pitfalls section (F19+F22+F33+F48+F50+F52+F56)#60DaveHanns wants to merge 1 commit into
DaveHanns wants to merge 1 commit into
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
MAJOR.MINOR;1.0.0fails at platform admission after upload..actor/actor.json+Dockerfile(apify/actor-*base) +src/main.*.apify/actor-templatesvia the rawmanifest.json.apify/actor-node-playwright-chrome(or puppeteer variant), not plainactor-node.curl, notapify call; setdefaultTimeoutSecs.LIMITED_PERMISSIONSbreaks 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
FINDINGS.mdin the eval repo (findings F19, F22, F33, F48, F50, F52, F56).