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.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

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.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.
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.py

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.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.
• scripts/run_workflow.py
• scripts/dash_api_probe.py
• scripts/dash_catalog_match.py
• scripts/dash_catalog_refresh.py
• scripts/dash_url_search.py
• scripts/dash_url_install.py