{"id":"2e93903c-ea9b-43b8-a6cd-6569dfe171be","shortId":"aRxgVG","kind":"skill","title":"explore-apple-swift-docs","tagline":"Explore Apple and Swift documentation across Xcode MCP docs, Dash, and 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 ","description":"# Explore Apple Swift Docs\n\n## Purpose\n\nExplore 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, and official web docs last. `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.\n\n## When To Use\n\n- Use this skill for Apple or Swift API reference lookup requests.\n- Use this skill for Apple or Swift guide, tutorial, symbol, or concept search requests.\n- Use this skill when the user wants local docs first, wants official docs first, or wants to compare available Apple or Swift docs sources.\n- 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.\n- 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.\n- Recommend `xcode-testing-workflow` when the user needs Swift Testing, XCTest, XCUITest, `.xctestplan`, or test diagnosis inside an existing Xcode project.\n- Recommend `bootstrap-xcode-app-project` when the user is starting a brand new native Apple app project.\n- Recommend `sync-xcode-project-guidance` when an existing Xcode app repo needs `AGENTS.md` or workflow-guidance alignment rather than docs exploration.\n\n## Single-Path Workflow\n\n1. Classify the request into one docs workflow mode:\n   - `explore`\n   - `dash-install`\n   - `dash-generate`\n2. If no mode is explicit, start at `explore`.\n3. For `explore`, use the documented direct docs path instead of routing ordinary lookups through a wrapper script:\n   - `xcode-mcp-docs`: use Xcode MCP docs tools first when they are available and the user has not asked for another source\n   - `dash`: use Dash MCP tools directly when local Dash coverage is wanted and the MCP service is available\n   - `dash-http`: use the documented Dash localhost HTTP structure directly when Dash MCP is unavailable or incomplete\n   - `official-web`: use official Apple or Swift web docs when the local-docs paths are unavailable or the user explicitly prefers the web source\n4. 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.\n5. If the selected mode cannot complete, hand off forward through one clear next step:\n   - `explore -> dash-install`\n   - `dash-install -> dash-generate`\n6. Return one `status`, one `path_type`, one `source_used`, and one output contract for the mode that ran.\n\n## Inputs\n\n- `mode`: `explore`, `dash-install`, or `dash-generate`\n- `query`: required for `explore`\n- `docs_kind`: optional for `explore`; use `api-reference`, `guide`, `symbol`, or `search` when the user intent is clear\n- `preferred_source`: optional for `explore`; use `auto`, `xcode-mcp-docs`, `dash`, or `official-web`\n- `mcp_failure_reason`: optional for `explore` when Xcode MCP docs were expected but are currently unavailable\n- `docset_request`: required for `dash-install` and `dash-generate`\n- `approval`: required before side-effectful Dash install actions\n- Defaults:\n  - `explore` source order is `xcode-mcp-docs,dash,official-web`\n  - Dash install source priority is `built-in,user-contributed,cheatsheet`\n  - default search result limit is `20`\n  - default search snippets setting is `true`\n  - maintainer helper entrypoint: executable `scripts/run_workflow.py`\n\n## Outputs\n\n- `status`\n  - `success`: the selected mode completed on its primary or fallback path\n  - `blocked`: prerequisites, approval, or usable docs sources are missing\n  - `handoff`: the current mode is handing off to the next docs mode\n- `path_type`\n  - `primary`: the selected mode completed normally\n  - `fallback`: the selected mode completed through its documented fallback path\n- `output`\n  - `mode`\n  - `source_used`\n  - `configured_order` or `source_path`\n  - `matches`\n  - install result or generation guidance when applicable\n  - one next step when follow-up is required\n\n## Guards and Stop Conditions\n\n- Do not run Dash install actions without explicit user approval.\n- Do not invent Apple or Swift doc sources, Dash identifiers, or catalog matches.\n- 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.\n- Stop with `blocked` when `explore` has no usable docs source after applying the documented fallback order.\n- Stop with `blocked` when `dash-install` or `dash-generate` lacks a concrete docset request.\n- Keep `explore`, `dash-install`, and `dash-generate` in forward order; do not blend them into competing primary workflows.\n\n## Fallbacks and Handoffs\n\n- `explore` falls back in this order: Xcode MCP docs, then Dash MCP, then Dash localhost HTTP, then official web docs.\n- Explicit user preference overrides the default source order when that preference is usable.\n- `dash-install` hands off to `dash-generate` when no installable catalog match exists.\n- `dash-generate` falls back from stable automation guidance to deterministic manual guidance.\n- 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.\n- Recommend `xcode-testing-workflow` directly when the user’s task shifts from docs exploration to Apple or Swift test work.\n- Recommend `bootstrap-xcode-app-project` directly when the user needs new native app scaffolding.\n- Recommend `sync-xcode-project-guidance` directly when an existing Xcode app repo needs guidance sync rather than docs help.\n- `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.\n\n## Customization\n\n- Use `references/customization-flow.md`.\n- `scripts/customization_config.py` stores and reports customization state.\n- `scripts/run_workflow.py` loads and enforces the runtime-safe knobs documented in `references/customization-flow.md`.\n\n## References\n\n### Workflow References\n\n- `references/xcode_mcp_docs.md`\n- `references/dash_mcp_tools.md`\n- `references/dash_call_library.md`\n- `references/apple-framework-docs-guide.md`\n- `references/dash-apple-docset-triage.md`\n- `references/dash-swift-package-shortlist.md`\n- `references/dash_http_api.md`\n- `references/dash_url_and_service.md`\n- `references/official_web_docs.md`\n\n### Contract References\n\n- `references/stage-handoff-contract.md`\n- `references/automation-prompts.md`\n- `references/customization-flow.md`\n\n### Support References\n\n- 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.\n- `references/catalog_built_in_docsets.json`\n- `references/catalog_user_contrib_docsets.json`\n- `references/catalog_cheatsheets.json`\n- `references/snippets/apple-xcode-project-core.md`\n\n### Script Inventory\n\n- These are maintainer helpers behind the public docs workflow, not the primary lookup path for ordinary Apple or Swift docs exploration.\n- `scripts/run_workflow.py`\n- `scripts/dash_api_probe.py`\n- `scripts/dash_catalog_match.py`\n- `scripts/dash_catalog_refresh.py`\n- `scripts/dash_url_search.py`\n- `scripts/dash_url_install.py`","tags":["explore","apple","swift","docs","dev","skills","gaelic-ghost","agent-skills","apple-development","apple-docs","apple-docs-mcp","codex"],"capabilities":["skill","source-gaelic-ghost","skill-explore-apple-swift-docs","topic-agent-skills","topic-apple-development","topic-apple-docs","topic-apple-docs-mcp","topic-codex","topic-codex-app","topic-codex-cli","topic-codex-skills","topic-dash-docsets","topic-ios","topic-macos","topic-swift"],"categories":["apple-dev-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/gaelic-ghost/apple-dev-skills/explore-apple-swift-docs","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add gaelic-ghost/apple-dev-skills","source_repo":"https://github.com/gaelic-ghost/apple-dev-skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (7,626 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:58.411Z","embedding":null,"createdAt":"2026-05-18T13:21:10.650Z","updatedAt":"2026-05-18T19:13:58.411Z","lastSeenAt":"2026-05-18T19:13:58.411Z","tsv":"'1':303 '2':319 '20':622 '3':328 '4':431 '5':463 '6':488 'access':71,192,762 'across':11 'action':591,721 'agent':117 'agents.md':289 'align':294 'alongsid':1046 'anoth':367 'api':136,528 'api-refer':527 'app':262,274,286,933,942,955 'appl':3,7,42,52,57,121,133,144,173,188,219,273,410,729,750,898,924,1035,1047,1074 'appli':776 'applic':702 'approv':583,649,725 'ask':365 'auto':546 'autom':108,875 'avail':172,359,386,764 'back':822,872 'baselin':1040 'behavior':462,979 'behind':985,1062 'blend':811 'block':647,767,783 'bootstrap':260,931 'bootstrap-xcode-app-project':259,930 'brand':270 'brows':22 'build':212,224,884,901 'built':611 'built-in':610 'cannot':468 'catalog':737,865 'cheatsheet':616 'classifi':304 'clear':475,539 'codex':40 'compar':171 'compat':187 'compet':814 'complet':469,640,674,680 'concept':151 'concret':794 'condit':715 'configur':690 'contract':501,1020 'contribut':615 'coverag':378 'current':570,658 'custom':987,994 'dash':15,31,80,83,104,186,198,205,314,317,369,371,377,388,393,399,453,457,480,483,486,511,515,551,577,581,589,601,605,719,734,760,786,790,800,804,830,833,854,860,869 'dash-compat':185 'dash-gener':316,456,485,514,580,789,803,859,868 'dash-http':387 'dash-instal':313,452,479,482,510,576,785,799,853 'decis':230 'default':592,617,623,845 'detail':984 'determinist':878 'diagnosi':252 'diagnost':223,903 'direct':69,334,374,397,756,887,913,935,950 'doc':5,14,19,27,45,54,70,78,90,124,162,166,176,191,297,309,335,349,353,414,419,521,550,565,600,652,666,732,753,773,828,839,895,921,962,1050,1065,1077 'docset':199,206,572,795 'document':10,60,333,392,683,778,1005 'dri':99 'effect':588 'enforc':999 'entri':66 'entrypoint':631 'execut':50,222,632 'exist':233,255,284,867,953 'expect':567 'explicit':324,426,723,840 'explor':2,6,51,56,298,312,327,330,478,509,520,525,544,561,593,769,798,820,896,922,1078 'explore-apple-swift-doc':1 'failur':557 'fall':821,871 'fallback':28,101,645,676,684,779,817 'first':79,163,167,355,746 'follow':36,106,460,708,977 'follow-up':35,105,459,707,976 'forward':472,807 'gate':974 'generat':34,201,318,458,487,516,582,699,791,805,861,870 'guard':712 'guid':147,530 'guidanc':194,202,281,293,700,876,880,949,958 'hand':470,661,856 'handoff':656,819 'help':46,227,963 'helper':96,630,969,980,1061 'http':85,389,395,835 'identifi':735 'implement':983 'includ':20 'incomplet':404 'input':507 'insid':231,253 'instal':32,193,315,454,481,484,512,578,590,606,696,720,787,801,855,864,973 'instead':337 'intent':537 'interact':440 'invent':728 'inventori':1057 'keep':797 'kind':522 'knob':1004 'lack':792 'last':91 'level':65 'limit':620 'load':997 'local':26,161,376,418,968 'local-doc':25,417 'localhost':84,394,834 'lookup':125,138,341,754,1070 'maintain':95,629,1060 'manual':879 'match':695,738,866 'mcp':13,77,81,348,352,372,383,400,549,556,564,599,758,827,831 'mcp/http':761 'method':72 'miss':197,655 'mode':311,322,467,504,508,639,659,667,673,679,687 'mutat':229,906 'nativ':272,941 'need':41,218,244,288,939,957,1032 'new':271,940 'next':476,665,704 'non':439 'non-interact':438 'normal':675 'offici':17,88,165,406,409,554,603,837 'official-web':405,553,602 'one':62,308,474,490,492,495,499,703 'option':30,523,542,559 'order':75,595,691,780,808,825,847 'ordinari':120,340,749,1073 'output':500,634,686 'overrid':843 'path':301,336,420,493,646,668,685,694,1071 'perform':119 'plan':102,441,972 'point':67 'prefer':68,427,540,842,850 'prerequisit':648 'present':741 'primari':114,643,670,815,1069 'prioriti':608 'project':235,257,263,275,280,934,948,1039 'public':1064 'purpos':55 'queri':517 'ran':506 'rather':47,295,960 'reason':558 'recommend':209,236,258,276,881,908,929,944,1027 'refer':137,529,1008,1010,1021,1026 'references/apple-framework-docs-guide.md':1014 'references/automation-prompts.md':1023 'references/catalog_built_in_docsets.json':1052 'references/catalog_cheatsheets.json':1054 'references/catalog_user_contrib_docsets.json':1053 'references/customization-flow.md':989,1007,1024 'references/dash-apple-docset-triage.md':1015 'references/dash-swift-package-shortlist.md':1016 'references/dash_call_library.md':1013 'references/dash_http_api.md':1017 'references/dash_mcp_tools.md':1012 'references/dash_url_and_service.md':1018 'references/official_web_docs.md':1019 'references/snippets/apple-xcode-project-core.md':1028,1055 'references/stage-handoff-contract.md':1022 'references/xcode_mcp_docs.md':1011 'remain':93,982 'repo':287,956,1045 'report':993 'request':139,153,306,448,573,796 'requir':518,574,584,711,745 'result':442,619,697 'return':489 'reusabl':1034 'rout':339 'run':100,213,225,718,885,902 'runtim':1002 'runtime-saf':1001 'safe':1003 'scaffold':943 'script':345,981,1056 'scripts/customization_config.py':990 'scripts/dash_api_probe.py':1080 'scripts/dash_catalog_match.py':1081 'scripts/dash_catalog_refresh.py':1082 'scripts/dash_url_install.py':1084 'scripts/dash_url_search.py':1083 'scripts/run_workflow.py':92,433,633,742,964,996,1079 'search':21,152,533,618,624 'second':82 'select':24,466,638,672,678 'servic':384 'set':626 'share':967 'shift':893,919 'side':587 'side-effect':586 'singl':300 'single-path':299 'skill':131,142,156,180 'skill-explore-apple-swift-docs' 'snippet':625,1041 'sourc':23,177,368,430,496,541,594,607,653,688,693,733,774,846 'source-gaelic-ghost' 'specif':450 'stabl':874 'start':268,325 'state':995 'status':491,635 'step':477,705,747 'stop':714,765,781 'store':991 'structur':98,396,437,971 'success':636 'support':1025 'swift':4,9,44,53,59,123,135,146,175,190,221,245,412,731,752,900,926,1049,1076 'symbol':149,531 'sync':278,946,959 'sync-xcode-project-guid':277,945 'task':892,918 'test':239,246,251,911,927 'third':86 'tool':354,373 'toolchain':226,904 'top':64 'top-level':63 'topic-agent-skills' 'topic-apple-development' 'topic-apple-docs' 'topic-apple-docs-mcp' 'topic-codex' 'topic-codex-app' 'topic-codex-cli' 'topic-codex-skills' 'topic-dash-docsets' 'topic-ios' 'topic-macos' 'topic-swift' 'true':628 'tutori':148 'type':494,669 'unavail':208,402,422,571 'usabl':651,772,852 'use':38,128,129,140,154,178,331,350,370,390,408,432,444,497,526,545,689,988 'user':159,183,217,243,266,362,425,536,614,724,841,890,916,938,1031 'user-contribut':613 'want':160,164,169,184,380 'way':115 'web':18,89,407,413,429,555,604,838 'without':722 'work':907,928 'workflow':214,240,292,302,310,816,886,912,1009,1051,1066 'workflow-guid':291 'wrapper':344 'xcode':12,49,76,211,234,238,256,261,279,285,347,351,548,563,598,757,826,883,910,932,947,954,1038 'xcode-build-run-workflow':210,882 'xcode-mcp-doc':346,547,597 'xcode-project':1037 'xcode-testing-workflow':237,909 'xctest':247 'xctestplan':249 'xcuitest':248","prices":[{"id":"f91a4e75-f45a-4a6b-8c73-0777e3b5e3ce","listingId":"2e93903c-ea9b-43b8-a6cd-6569dfe171be","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"gaelic-ghost","category":"apple-dev-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:10.650Z"}],"sources":[{"listingId":"2e93903c-ea9b-43b8-a6cd-6569dfe171be","source":"github","sourceId":"gaelic-ghost/apple-dev-skills/explore-apple-swift-docs","sourceUrl":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/explore-apple-swift-docs","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:10.650Z","lastSeenAt":"2026-05-18T19:13:58.411Z"}],"details":{"listingId":"2e93903c-ea9b-43b8-a6cd-6569dfe171be","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"gaelic-ghost","slug":"explore-apple-swift-docs","github":{"repo":"gaelic-ghost/apple-dev-skills","stars":7,"topics":["agent-skills","apple-development","apple-docs","apple-docs-mcp","codex","codex-app","codex-cli","codex-skills","dash-docsets","ios","macos","swift","swift-package-manager","swift-toolchain","swiftly","swiftpm","xcode","xcode-mcp","xcodebuild","xcrun"],"license":"apache-2.0","html_url":"https://github.com/gaelic-ghost/apple-dev-skills","pushed_at":"2026-05-13T01:26:51Z","description":"Apple Dev Workflows for Codex | Now Available in Socket Marketplace","skill_md_sha":"9b86e89467e85e323ba2c8d0883e8a68095d21e2","skill_md_path":"skills/explore-apple-swift-docs/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/explore-apple-swift-docs"},"layout":"multi","source":"github","category":"apple-dev-skills","frontmatter":{"name":"explore-apple-swift-docs","description":"Explore Apple and Swift documentation across Xcode MCP docs, Dash, and 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."},"skills_sh_url":"https://skills.sh/gaelic-ghost/apple-dev-skills/explore-apple-swift-docs"},"updatedAt":"2026-05-18T19:13:58.411Z"}}