Raycast Extension Dev Publish Capability Pack Skill

Knowledge Freshness

This capability pack is pinned to documentation verified on 2026-04-10. When upstream docs change, refresh endpoint contracts, examples, and constraints before using this skill for production changes.

Retrieval Sources

• https://developers.raycast.com/
• https://developers.raycast.com/basics/getting-started
• https://developers.raycast.com/basics/publish-an-extension

Always prefer direct retrieval from official docs/API references over model memory for limits, endpoint signatures, and behavior guarantees.

Core Workflow

1. Confirm target version/runtime and pull latest official docs for the task scope.
2. Build an execution plan with explicit read-only discovery before any mutation.
3. Validate contracts, permissions, and safety constraints before applying changes.
4. Execute with deterministic checkpoints and rollback criteria.
5. Produce a verification report with evidence, caveats, and next actions.

Overview

This capability pack teaches agents how to design and ship Raycast extensions that are useful in real workflows. It focuses on maintainable architecture and store submission quality.

Capability Scope

• Command and UX architecture
• External API integration and auth handling
• Local state and cache strategy
• Error/fallback UX patterns
• Publish and post-release maintenance workflow

Compatibility

Native

• Claude Code / Claude: native skill usage via SKILL.md.
• Codex/OpenAI workflows: compatible with Agent Skills-style SKILL.md content as reusable workflow instructions.

Manual Adaptation

• Gemini CLI: native skill usage via .gemini/skills/<skill-name>/SKILL.md or .agents/skills/<skill-name>/SKILL.md where supported.
• Cursor: use the generated .cursor/rules/*.mdc adapter for project rules.
• OpenClaw and similar agents: use the same skill content as a reusable prompt/workflow file when native skill import is unavailable.

Production Rules

• Keep command scope explicit and focused.
• Protect API tokens and sensitive user data.
• Design for graceful degradation on API failures.
• Validate extension behavior on cold and warm starts.

Troubleshooting

Issue: Extension feels slow or brittle
Fix: Add caching and request timeouts with clear fallback UI states.

Issue: Store review rejects submission
Fix: Audit metadata, permissions, and UX consistency against Raycast guidelines.

Issue: External API changes break commands
Fix: Add schema guards and compatibility adapters for remote responses.

Output Contract

1. Provide an implementation plan ordered by risk and dependency.
2. Provide exact production-ready config/commands with no placeholders.
3. Call out secrets, permissions, and least-privilege requirements.
4. Include rollback and recovery guidance for each risky step.

Validation Checklist

• Verify all referenced docs/versions before applying changes.
• Run regression checks for core user flow and error paths.
• Confirm observability/logging is enabled for changed components.
• Confirm security controls (auth, rate limits, input validation) still pass.
• Record final known limitations and follow-up actions.