/explore-apple-swift-docs

name: explore-apple-swift-docs
description: Explore Apple and Swift documentation across Xcode MCP docs, Dash, source repositories, generated docs, and readable official web docs, including search, browse, source selection, local-docs fallback, and optional Dash install or generation follow-up. Use when Codex needs Apple or Swift docs help rather than Xcode execution or repo-guidance sync work.

Explore Apple Swift Docs

Purpose

Explore Apple and Swift documentation through one top-level entry point. Prefer direct docs access methods in this order: Xcode MCP `DocumentationSearch` first, Dash.app MCP second, Dash localhost HTTP only when the Dash.app MCP is unavailable or incomplete, then checked-out source, generated DocC, GitHub/source repositories, or release notes, and finally readable online documentation. `scripts/run-workflow.fsx` remains a maintainer helper for structured dry runs, fallback planning, and Dash follow-up automation, but it is not the primary way the agent should perform ordinary Apple or Swift docs lookup.

When To Use

• Use this skill for Apple or Swift API reference lookup requests.
• Use this skill for Apple or Swift guide, tutorial, symbol, or concept search requests.
• Use this skill when the user wants local docs first, wants official docs first, or wants to compare available Apple or Swift docs sources.
• Use this skill when the user wants Dash-compatible Apple or Swift docs access, install guidance for a missing Dash docset, or generation guidance when a Dash docset is unavailable.
• Recommend `xcode-build-run-workflow` when the user needs Apple or Swift execution, diagnostics, build, run, toolchain help, or mutation decisions inside an existing Xcode project.
• Recommend `xcode-testing-workflow` when the user needs Swift Testing, XCTest, XCUITest, `.xctestplan`, or test diagnosis inside an existing Xcode project.
• Recommend `bootstrap-xcode-workspace` when the user is starting a native Apple product or aligning an existing canonical workspace.

Single-Path Workflow

1. Classify the request into one docs workflow mode:

• `explore`
• `dash-install`
• `dash-generate`

2. If no mode is explicit, start at `explore`. 3. For `explore`, use the documented direct docs path instead of routing ordinary lookups through a wrapper script:

• `xcode-mcp-docs`: use Xcode MCP `DocumentationSearch` first when it is available and the user has not asked for another source
• `dash`: use the Dash.app MCP directly after Xcode MCP when its installed docsets cover the question
• `dash-http`: use the documented Dash localhost HTTP structure directly when Dash MCP is unavailable or incomplete
• `source-repo`: use GitHub/source repositories, generated DocC, release notes, or checked-out source when the request is about open source Swift projects, tools, or packages
• `official-web`: use official Apple or Swift web docs when the local-docs and source-repo paths are unavailable, the user explicitly prefers the web source, and the page content is actually readable through the available tool

4. Use `scripts/run-workflow.fsx` only when a structured non-interactive planning result is useful, or when the request is specifically about `dash-install` or `dash-generate` follow-up behavior. 5. If the selected mode cannot complete, hand off forward through one clear next step:

• `explore -> dash-install`
• `dash-install -> dash-generate`

6. Return one `status`, one `path_type`, one `source_used`, and one output contract for the mode that ran.

Inputs

• `mode`: `explore`, `dash-install`, or `dash-generate`
• `query`: required for `explore`
• `docs_kind`: optional for `explore`; use `api-reference`, `guide`, `symbol`, or `search` when the user intent is clear
• `preferred_source`: optional for `explore`; use `auto`, `xcode-mcp-docs`, `dash`, `dash-http`, `source-repo`, or `official-web`
• `mcp_failure_reason`: optional for `explore` when Xcode MCP docs were expected but are currently unavailable
• `docset_request`: required for `dash-install` and `dash-generate`
• `approval`: required before side-effectful Dash install actions
• Defaults:
• `explore` source order is `xcode-mcp-docs,dash,dash-http,source-repo,official-web`
• Dash install source priority is `built-in,user-contributed,cheatsheet`
• default search result limit is `20`
• default search snippets setting is `true`
• maintainer helper entrypoint: executable `scripts/run-workflow.fsx`

Outputs

• `status`
• `success`: the selected mode completed on its primary or fallback path
• `blocked`: prerequisites, approval, or usable docs sources are missing
• `handoff`: the current mode is handing off to the next docs mode
• `path_type`
• `primary`: the selected mode completed normally
• `fallback`: the selected mode completed through its documented fallback path
• `output`
• `mode`
• `source_used`
• `configured_order` or `source_path`
• `matches`
• install result or generation guidance when applicable
• one next step when follow-up is required

Guards and Stop Conditions

• Do not run Dash install actions without explicit user approval.
• Do not invent Apple or Swift doc sources, Dash identifiers, or catalog matches.
• Do not present `scripts/run-workflow.fsx` as the required first step for ordinary Apple or Swift docs lookup when direct Xcode MCP or Dash MCP/HTTP access is available.
• Do not treat generic no-JS web search or no-JS page extraction as a readable source for Apple Developer documentation. Apple Developer pages often require JavaScript-rendered payloads; if the content cannot be read through Xcode MCP, Dash, source repositories, generated docs, or a capable browser/source path, say that plainly instead of claiming the docs were checked.
• Do not cite an Apple Developer URL as evidence unless the relevant documentation text was actually read through a usable source. A URL alone is only a citation target, not proof that the guidance was verified.