Explore Apple Swift Docs

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 docs first, Dash MCP second, Dash localhost HTTP third, open source Swift repositories or generated DocC when the relevant project is available there, and official web docs last only when they are actually readable through a capable source. 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

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

• xcode-mcp-docs: use Xcode MCP docs tools first when they are available and the user has not asked for another source
• dash: use Dash MCP tools directly when local Dash coverage is wanted and the MCP service is available
• 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

1. 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.
2. If the selected mode cannot complete, hand off forward through one clear next step:

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

1. 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 docs, then Dash MCP, then Dash localhost HTTP, then open source Swift repositories or generated docs when applicable, then readable official web docs.
• 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gaelic-ghost
• Source: gaelic-ghost/socket
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.