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 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.py 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-app-project when the user is starting a brand new native Apple app project.
Recommend sync-xcode-project-guidance when an existing Xcode app repo needs AGENTS.md or workflow-guidance alignment rather than docs exploration.
Single-Path Workflow
Classify the request into one docs workflow mode:
explore
dash-install
dash-generate
If no mode is explicit, start at explore.
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
Use scripts/run_workflow.py 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.
If the selected mode cannot complete, hand off forward through one clear next step:
explore -> dash-install
dash-install -> dash-generate
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
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.py 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.
Stop with blocked when explore has no usable docs source after applying the documented fallback order.
Stop with blocked when dash-install or dash-generate lacks a concrete docset request.
Keep explore, dash-install, and dash-generate in forward order; do not blend them into competing primary workflows.
Fallbacks and Handoffs
explore falls back in this order: Xcode MCP DocumentationSearch, then Dash.app MCP, then Dash localhost HTTP only when its MCP is unavailable or incomplete, then checked-out source, generated DocC, GitHub/source repositories, or release notes, then readable online documentation.
Explicit user preference overrides the default source order when that preference is usable.
dash-install hands off to dash-generate when no installable catalog match exists.
dash-generate falls back from stable automation guidance to deterministic manual guidance.
Recommend xcode-build-run-workflow directly when the user’s task shifts from docs exploration to Apple or Swift build, run, diagnostics, toolchain, or mutation work.
Recommend xcode-testing-workflow directly when the user’s task shifts from docs exploration to Apple or Swift test work.
Recommend bootstrap-xcode-app-project directly when the user needs new native app scaffolding.
Recommend sync-xcode-project-guidance directly when an existing Xcode app repo needs guidance sync rather than docs help.
scripts/run_workflow.py is the shared local helper for structured planning, install gating, and follow-up behavior; helper scripts remain implementation details behind it.
Customization
Use references/customization-flow.md.
scripts/customization_config.py stores and reports customization state.
scripts/run_workflow.py loads and enforces the runtime-safe knobs documented in references/customization-flow.md.
References
Workflow References
references/xcode_mcp_docs.md
references/dash_mcp_tools.md
references/dash_call_library.md
references/apple-framework-docs-guide.md
references/dash-apple-docset-triage.md
references/dash-swift-package-shortlist.md
references/dash_http_api.md
references/dash_url_and_service.md
references/official_web_docs.md
Contract References
references/stage-handoff-contract.md
references/automation-prompts.md
references/customization-flow.md
Support References
Recommend references/snippets/apple-xcode-project-core.md when the user needs a reusable Apple and Xcode-project baseline snippet in their own repo alongside Apple or Swift docs workflows.
references/catalog_built_in_docsets.json
references/catalog_user_contrib_docsets.json
references/catalog_cheatsheets.json
references/snippets/apple-xcode-project-core.md
Script Inventory
These are maintainer helpers behind the public docs workflow, not the primary lookup path for ordinary Apple or Swift docs exploration.
