Update

Pre-computed context

Last upstream sync: !grep -m1 '^- Last sync:' "${CLAUDE_SKILL_DIR}/UPSTREAM.md" >/dev/null 2>&1 && grep -m1 -o 'Last sync:.*' "${CLAUDE_SKILL_DIR}/UPSTREAM.md" 2>/dev/null || echo "never — run this skill with --check"

Purpose

Keep the /firecrawl:firecrawl wrapper skill in sync with its two upstream dependencies: the firecrawl-cli npm package (ships new versions roughly weekly) and the upstream canonical skill at https://www.firecrawl.dev/agent-onboarding/SKILL.md (evolves alongside it). The wrapper skill owns its content. Upstream is a source, not a parallel install.

Maintainer-facing: run this in a working-tree checkout of this plugin (the marketplace clone, or a directory loaded via --plugin-dir), never against an installed marketplace copy, the apply path rewrites UPSTREAM.md inside this skill directory, and consumers receive updates through /plugin marketplace update. Drift detection uses the sidecar UPSTREAM.md (SHA tracking): upstream SKILL.md is fetched fresh on --check and hashed; the sidecar records the prior hash for diff. No vendored snapshot is kept. The action is advisory, the two approval gates in Safety below keep every mutation behind an explicit yes.

Invocation

When to invoke, the modes, and the full update pipeline: read context/update-flow.md. The preservation invariants and safety guarantees below stay inline.

Preservation rules (for any skill-content integration)

These are the invariants an integration run must keep in the /firecrawl:firecrawl wrapper skill, in this exact form:

• Single-line YAML description with Use when: and skip guidance phrase lists
• Frontmatter fields: description, argument-hint, user-invocable: true, disable-model-invocation: false (no name. It defaults to the directory)
• Pre-computed context block at top, using firecrawl --status for the health line
• "Core pattern. Write to disk, Read selectively" rule: every non-trivial example writes to a mktemp-created spill file with -o, Reads selectively, and the spill file is removed after the Read (kept only when the user asked for the file itself)
• "When NOT to use this skill" section with the doc-site-reader-first and synthesis-tool escalation ordering
• The pointer to this maintainer update skill (/firecrawl:update), the wrapper skill delegates its update/drift concern here rather than carrying it inline
• Gotchas section with the "don't run firecrawl init, don't run firecrawl login" prohibitions
• Imperative tone, no marketing language

The helper at scripts/update.sh does the deterministic parts (fetch, SHA, diff); this skill body does the Claude-facing decisions (integration and approval). For a non-trivial content delta, the /skill-creator:skill-creator plugin skill (if installed) can drive the rewrite under the preservation rules above; otherwise inline-edit.

Safety

Nothing destructive happens without explicit approval. Four guarantees:

1. Two approval gates. The update action never runs npm install -g or rewrites SKILL.md without asking first. Gate 1 covers the binary install; Gate 2 covers the skill content. Either No exits cleanly.
2. Atomic fetching. update.sh --check completes all network I/O (npm metadata + upstream fetch) before printing anything. A mid-run 404 or DNS failure leaves state untouched. No partial write.
3. Rollback path. UPSTREAM.md records the previous CLI version before each upgrade. If a new version breaks something, the rollback is one line: npm install -g firecrawl-cli@<previous-version>. Revert the plugin PR for skill-content changes.
4. Post-install verification. After npm install -g, the flow re-runs firecrawl --status and diffs firecrawl --help against the pre-install snapshot. A removed command or auth failure is flagged before the skill-content integration step begins.

Network requirement. The update path needs registry.npmjs.org and www.firecrawl.dev reachable. Some sandboxed/cloud egress proxies intermittently 503 with "DNS cache overflow". Retry after ~30s, or run the update from an unrestricted session.

Idempotency. Running the update action with --check twice with no upstream change: "no drift, current." Running a full update when already at latest: reports "no drift" and exits before Gate 1. Safe to schedule or re-run.

What this skill does NOT do

• Does not run against an installed marketplace copy. Maintainer-facing; the apply path writes UPSTREAM.md in this skill directory. Consumers update via /plugin marketplace update.
• Does not auto-rewrite the wrapper SKILL.md. update.sh owns only the deterministic record (UPSTREAM.md); skill-content integration is Claude's step behind Gate 2, governed by the Preservation rules above.
• Does not run firecrawl init or firecrawl login. Those install a parallel shadow copy / second auth source of truth. This plugin IS the maintained integration.

Related

• UPSTREAM.md (this skill root). Sync-state anchor (last sync date, upstream SHA, previous CLI version for rollback). Updated only by the update action.
• scripts/update.sh. Deterministic helper invoked by the update flow (npm version lookup, upstream fetch + SHA, help diff). Regression tests: scripts/update.test.sh.
• context/update-flow.md, when to invoke, the modes, and the full pipeline.
• The user-facing wrapper skill this maintains: /firecrawl:firecrawl.
• Firecrawl docs: https://docs.firecrawl.dev/sdks/cli. Upstream skill source: https://www.firecrawl.dev/agent-onboarding/SKILL.md.