{"id":"074096e6-eb8b-4dc2-8788-f5b02e221536","shortId":"HrjCKg","kind":"skill","title":"swift-package-workflow","tagline":"Compatibility workflow surface for broad or legacy Swift Package Manager execution requests. Use when older references still point at swift-package-workflow and route the request into swift-package-build-run-workflow or swift-package-testing-workflow while preserving SwiftPM-firs","description":"# Swift Package Workflow\n\n## Purpose\n\nUse this skill as a compatibility surface for older references to `swift-package-workflow` while the repo transitions to narrower package execution skills. The real long-term owners are `swift-package-build-run-workflow` for build/run and manifest work and `swift-package-testing-workflow` for testing work. `scripts/run_workflow.py` now stays intentionally thin: it performs repo-shape checks, preserves mixed-root and Xcode handoff boundaries, and returns routing context rather than trying to keep a second full execution-planning surface alive.\n\n## When To Use\n\n- Use this skill when older docs, prompts, or install surfaces still name `swift-package-workflow`.\n- Use this skill when the request is broad and the first job is deciding between the narrower package build/run and testing skills.\n- Use this skill when the user is working in a terminal or in editors such as Zed, VS Code, Neovim, Sublime Text, or other non-Xcode environments and the package-specific surface is obvious but the narrower skill has not yet been named.\n- Do not use this skill for brand-new package bootstrap from nothing.\n- Do not use this skill for repo-guidance alignment in an existing package repo.\n- Do not use this skill as the default path for Xcode workspace, scheme, preview, simulator, or navigator-driven work.\n- Recommend `swift-package-build-run-workflow` when the request is primarily about manifest, dependencies, plugins, package resources, Metal distribution, build, or run work.\n- Recommend `swift-package-testing-workflow` when the request is primarily about Swift Testing, XCTest, `.xctestplan`, fixtures, flake diagnosis, or package test execution.\n- Recommend `bootstrap-swift-package` when the package repo does not exist yet.\n- Recommend `sync-swift-package-guidance` when the repo guidance needs to be added, refreshed, or merged.\n- Recommend `xcode-build-run-workflow` when the task depends on active Xcode workspace state, scheme-aware execution, previews, navigator diagnostics, simulator or device flows, or guarded mutation inside Xcode-managed scope.\n- Recommend `xcode-testing-workflow` when the task depends primarily on Xcode-native test execution, XCUITest, or `.xctestplan` handling.\n- Recommend `explore-apple-swift-docs` when the user needs Apple or Swift docs exploration before implementation or package changes.\n\n## Single-Path Workflow\n\n1. Classify the request into one operation type:\n   - package inspection\n   - read or search\n   - manifest or dependency changes\n   - build\n   - test\n   - run\n   - plugin\n   - toolchain management\n   - mutation\n2. Apply the Apple and Swift docs gate before any design, architecture, implementation, or refactor guidance:\n   - use `explore-apple-swift-docs` to gather the relevant SwiftPM, Swift, or Apple documentation first\n   - state the documented API behavior, package rule, or workflow requirement being relied on before proposing changes\n   - do not rely on memory as the primary source when docs exist\n   - if the docs and the current code conflict, stop and report that conflict\n   - if no relevant docs can be found, say that explicitly before proceeding\n3. Apply the shared Swift-package policy before giving implementation guidance:\n   - apply the detailed local policy in `references/snippets/apple-swift-package-core.md` when package-policy wording is needed\n   - preserve its simplicity-first, shape-preserving, and anti-ceremony Swift guidance\n   - preserve its explicit `swiftLanguageModes: [.v6]` package-manifest default and prefer that spelling over the legacy `swiftLanguageVersions` alias on current manifest surfaces\n   - preserve its package-appropriate logging, telemetry, and testing guidance\n4. Run `scripts/run_workflow.py` to resolve repo shape, detect whether the root is a plain package repo, and route the request toward the narrower package build/run or testing skill.\n5. Use `references/cli-command-matrix.md` and `references/package-resources-testing-and-builds.md` only to explain why the narrower skill should take over; do not rebuild a second command-planning surface here.\n6. If the repo root is ambiguous because Xcode-managed markers are present at the same root, use `references/xcode-handoff-conditions.md` and hand off cleanly to `xcode-build-run-workflow` or `xcode-testing-workflow` as appropriate.\n7. Report the docs relied on, the repo-shape result, and the recommended narrower skill or Xcode handoff.\n\n## Inputs\n\n- `operation_type`: one of the operation types listed above.\n- `request`: optional short natural-language request text used to infer `operation_type` when the explicit operation is omitted.\n- `repo_root`: optional absolute path for the target package repo.\n- `mixed_root_opt_in`: optional explicit opt-in when the user wants a SwiftPM-first plan for a mixed root even though Xcode markers are present.\n- Defaults:\n  - runtime entrypoint: executable `scripts/run_workflow.py`\n  - `repo_root=.` when omitted\n  - the runtime may infer `operation_type` from `--request` text when the request wording is clear enough\n  - package execution prefers `swift package`, `swift build`, `swift test`, and `swift run`\n  - mixed roots hand off by default unless `--mixed-root-opt-in` is passed\n\n## Outputs\n\n- `status`\n  - `success`: the workflow completed on the SwiftPM-first path\n  - `handoff`: the workflow is handing off to `xcode-build-run-workflow` or `xcode-testing-workflow`\n  - `blocked`: prerequisites or repo-shape rules prevented completion\n- `path_type`\n  - `primary`: the SwiftPM-first path completed\n  - `fallback`: a non-mutating planned command path was returned\n- `output`\n  - operation type\n  - resolved repo root\n  - repo-shape result\n  - `routing_summary`\n  - inferred context that helps the narrower skill or the caller understand why the handoff happened\n  - `recommended_skill`\n  - one concise next step or handoff payload\n\n## Guards and Stop Conditions\n\n- Stop with `blocked` when the repo root cannot be resolved.\n- Stop with `blocked` when the repo does not contain `Package.swift`.\n- Stop with `handoff` when the request should move into `swift-package-build-run-workflow`, `swift-package-testing-workflow`, `xcode-build-run-workflow`, or `xcode-testing-workflow`.\n- Stop with `handoff` when the requested work crosses into Xcode project membership, scheme, preview, simulator, or other Xcode-managed concerns.\n- Stop with `blocked` when no safe SwiftPM-first command path exists for the requested operation.\n\n## Fallbacks and Handoffs\n\n- The primary job of this skill now is to route to the narrower package skills while preserving the mixed-root Xcode handoff boundary.\n- Do not keep a second package command matrix alive in this compatibility surface; the narrower skill should own concrete execution planning.\n- The only current compatibility payload here is routing context, inferred repo shape, and one concise next step.\n- Hand off to `swift-package-build-run-workflow` when the request is primarily about package build/run, manifest, dependency, plugin, resource, or Metal-distribution work.\n- Hand off to `swift-package-testing-workflow` when the request is primarily about tests, test plans, fixtures, or package test diagnosis.\n- Hand off to `xcode-build-run-workflow` when package work depends on:\n  - active Xcode workspace or scheme state\n  - previews, snippet execution, simulator, or device flows\n  - navigator issues or Xcode build-log inspection\n  - Xcode MCP mutation tools\n  - Metal shader compilation, Apple-managed Metal toolchain inspection, or package distribution that depends on Xcode-managed Apple SDK integration\n  - direct changes inside `.xcodeproj`, `.xcworkspace`, or `.pbxproj` managed scope\n- Hand off to `xcode-testing-workflow` when package work depends primarily on Xcode-native test execution, XCUITest, or `.xctestplan` handling.\n- Recommend `sync-swift-package-guidance` when the request is really about repo guidance instead of execution.\n- Recommend `bootstrap-swift-package` when the repository still needs to be created from scratch.\n- When maintaining this repository itself, refresh guidance-sync consumers after substantial package-policy changes and keep the top-level export-surface docs aligned. Do not tell users to rely on repo-local installer workflows; this repository does not ship them.\n\n## Customization\n\n- Use `references/customization.template.yaml`.\n- `scripts/customization_config.py` stores and reports customization state.\n- `scripts/run_workflow.py` reads customization state, but the current workflow keeps a fixed routing policy and does not expose ordinary user-facing knobs.\n- Run the Python wrapper and customization entrypoints through `uv`, because they rely on inline `PyYAML` script metadata rather than a repo-global Python environment.\n\n## References\n\n### Workflow References\n\n- `references/workflow-policy.md`\n- `references/repo-shape-detection.md`\n- `references/cli-command-matrix.md`\n- `references/package-resources-testing-and-builds.md`\n- `references/xcode-handoff-conditions.md`\n\n### Contract References\n\n- `references/customization.template.yaml`\n\n### Support References\n\n- Recommend `references/snippets/apple-swift-package-core.md` when the user needs reusable SwiftPM baseline policy wording in an end-user repo.\n- `references/snippets/apple-swift-package-core.md`\n\n### Script Inventory\n\n- `scripts/run_workflow.py`\n- `scripts/customization_config.py`","tags":["swift","package","workflow","apple","dev","skills","gaelic-ghost","agent-skills","apple-development","apple-docs","apple-docs-mcp","codex"],"capabilities":["skill","source-gaelic-ghost","skill-swift-package-workflow","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/swift-package-workflow","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 (9,412 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.957Z","embedding":null,"createdAt":"2026-05-18T13:21:11.343Z","updatedAt":"2026-05-18T19:13:58.957Z","lastSeenAt":"2026-05-18T19:13:58.957Z","tsv":"'1':430 '2':454 '3':539 '4':611 '5':639 '6':664 '7':701 'absolut':752 'activ':363,1148 'ad':348 'alia':596 'align':249,1283 'aliv':140,1057 'ambigu':670 'anti':575 'anti-ceremoni':574 'api':489 'appl':409,416,457,473,483,1177,1191 'apple-manag':1176 'appli':455,540,551 'appropri':605,700 'architectur':465 'awar':369 'baselin':1379 'behavior':490 'block':867,937,947,1008 'bootstrap':237,324,1244 'bootstrap-swift-packag':323,1243 'boundari':123,1048 'brand':234 'brand-new':233 'broad':9,167 'build':36,88,279,295,355,447,691,818,859,967,977,1093,1140,1166 'build-log':1165 'build/run':92,178,635,1103 'caller':916 'cannot':942 'ceremoni':576 'chang':425,446,501,1195,1272 'check':115 'classifi':431 'clean':687 'clear':810 'code':200,520 'command':660,891,1015,1055 'command-plan':659 'compat':5,59,1060,1073 'compil':1175 'complet':843,875,884 'concern':1005 'concis':925,1084 'concret':1067 'condit':934 'conflict':521,526 'consum':1266 'contain':953 'context':127,908,1078 'contract':1366 'creat':1254 'cross':992 'current':519,598,1072,1317 'custom':1302,1309,1313,1338 'decid':173 'default':262,587,787,829 'depend':289,361,394,445,1105,1146,1186,1213 'design':464 'detail':553 'detect':618 'devic':376,1159 'diagnosi':317,1134 'diagnost':373 'direct':1194 'distribut':294,1111,1184 'doc':149,411,419,460,475,512,516,530,704,1282 'document':484,488 'driven':273 'editor':195 'end':1385 'end-us':1384 'enough':811 'entrypoint':789,1339 'environ':209,1357 'even':781 'execut':15,76,137,321,370,401,790,813,1068,1156,1220,1241 'execution-plan':136 'exist':252,333,513,1017 'explain':646 'explicit':536,581,745,764 'explor':408,420,472 'explore-apple-swift-doc':407,471 'export':1280 'export-surfac':1279 'expos':1327 'face':1331 'fallback':885,1022 'fir':49 'first':170,485,569,775,848,882,1014 'fix':1321 'fixtur':315,1130 'flake':316 'flow':377,1160 'found':533 'full':135 'gate':461 'gather':477 'give':548 'global':1355 'guard':379,931 'guidanc':248,340,344,469,550,578,610,1230,1238,1264 'guidance-sync':1263 'hand':685,826,854,1087,1113,1135,1203 'handl':405,1224 'handoff':122,719,850,920,929,957,987,1024,1047 'happen':921 'help':910 'implement':422,466,549 'infer':740,799,907,1079 'inlin':1346 'input':720 'insid':381,1196 'inspect':439,1168,1181 'instal':152,1294 'instead':1239 'integr':1193 'intent':108 'inventori':1390 'issu':1162 'job':171,1027 'keep':132,1051,1274,1319 'knob':1332 'languag':735 'legaci':11,594 'level':1278 'list':728 'local':554,1293 'log':606,1167 'long':81 'long-term':80 'maintain':1258 'manag':14,384,452,674,1004,1178,1190,1201 'manifest':94,288,443,586,599,1104 'marker':675,784 'matrix':1056 'may':798 'mcp':1170 'membership':996 'memori':506 'merg':351 'metadata':1349 'metal':293,1110,1173,1179 'metal-distribut':1109 'mix':118,759,779,824,832,1044 'mixed-root':117,1043 'mixed-root-opt-in':831 'move':962 'mutat':380,453,889,1171 'name':155,226 'narrow':74,176,220,633,649,715,912,1037,1063 'nativ':399,1218 'natur':734 'natural-languag':733 'navig':272,372,1161 'navigator-driven':271 'need':345,415,564,1251,1376 'neovim':201 'new':235 'next':926,1085 'non':207,888 'non-mut':887 'non-xcod':206 'noth':239 'obvious':217 'older':19,62,148 'omit':748,795 'one':435,723,924,1083 'oper':436,721,726,741,746,800,896,1021 'opt':761,766,834 'opt-in':765 'option':731,751,763 'ordinari':1328 'output':838,895 'owner':83 'packag':3,13,26,35,42,51,67,75,87,99,158,177,213,236,253,278,291,302,319,326,329,339,424,438,491,545,560,585,604,625,634,757,812,816,966,972,1038,1054,1092,1102,1118,1132,1144,1183,1211,1229,1246,1270 'package-appropri':603 'package-manifest':584 'package-polici':559,1269 'package-specif':212 'package.swift':954 'pass':837 'path':263,428,753,849,876,883,892,1016 'payload':930,1074 'pbxproj':1200 'perform':111 'plain':624 'plan':138,661,776,890,1069,1129 'plugin':290,450,1106 'point':22 'polici':546,555,561,1271,1323,1380 'prefer':589,814 'prerequisit':868 'present':677,786 'preserv':46,116,565,572,579,601,1041 'prevent':874 'preview':268,371,998,1154 'primari':509,878,1026 'primarili':286,309,395,1100,1125,1214 'proceed':538 'project':995 'prompt':150 'propos':500 'purpos':53 'python':1335,1356 'pyyaml':1347 'rather':128,1350 'read':440,1312 'real':79 'realli':1235 'rebuild':656 'recommend':275,299,322,335,352,386,406,714,922,1225,1242,1371 'refactor':468 'refer':20,63,1358,1360,1367,1370 'references/cli-command-matrix.md':641,1363 'references/customization.template.yaml':1304,1368 'references/package-resources-testing-and-builds.md':643,1364 'references/repo-shape-detection.md':1362 'references/snippets/apple-swift-package-core.md':557,1372,1388 'references/workflow-policy.md':1361 'references/xcode-handoff-conditions.md':683,1365 'refresh':349,1262 'relev':479,529 'reli':497,504,705,1289,1344 'repo':71,113,247,254,330,343,616,626,667,709,749,758,792,871,899,902,940,950,1080,1237,1292,1354,1387 'repo-glob':1353 'repo-guid':246 'repo-loc':1291 'repo-shap':112,708,870,901 'report':524,702,1308 'repositori':1249,1260,1297 'request':16,31,165,284,307,433,630,730,736,803,807,960,990,1020,1098,1123,1233 'requir':495 'resolv':615,898,944 'resourc':292,1107 'result':711,904 'return':125,894 'reusabl':1377 'root':119,621,668,681,750,760,780,793,825,833,900,941,1045 'rout':29,126,628,905,1034,1077,1322 'rule':492,873 'run':37,89,280,297,356,449,612,692,823,860,968,978,1094,1141,1333 'runtim':788,797 'safe':1011 'say':534 'scheme':267,368,997,1152 'scheme-awar':367 'scope':385,1202 'scratch':1256 'script':1348,1389 'scripts/customization_config.py':1305,1392 'scripts/run_workflow.py':105,613,791,1311,1391 'sdk':1192 'search':442 'second':134,658,1053 'shader':1174 'shape':114,571,617,710,872,903,1081 'shape-preserv':570 'share':542 'ship':1300 'short':732 'simplic':568 'simplicity-first':567 'simul':269,374,999,1157 'singl':427 'single-path':426 'skill':56,77,146,162,181,184,221,231,244,259,638,650,716,913,923,1030,1039,1064 'skill-swift-package-workflow' 'snippet':1155 'sourc':510 'source-gaelic-ghost' 'specif':214 'spell':591 'state':366,486,1153,1310,1314 'status':839 'stay':107 'step':927,1086 'still':21,154,1250 'stop':522,933,935,945,955,985,1006 'store':1306 'sublim':202 'substanti':1268 'success':840 'summari':906 'support':1369 'surfac':7,60,139,153,215,600,662,1061,1281 'swift':2,12,25,34,41,50,66,86,98,157,277,301,311,325,338,410,418,459,474,481,544,577,815,817,819,822,965,971,1091,1117,1228,1245 'swift-packag':543 'swift-package-build-run-workflow':33,85,276,964,1090 'swift-package-testing-workflow':40,97,300,970,1116 'swift-package-workflow':1,24,65,156 'swiftlanguagemod':582 'swiftlanguagevers':595 'swiftpm':48,480,774,847,881,1013,1378 'swiftpm-fir':47 'swiftpm-first':773,846,880,1012 'sync':337,1227,1265 'sync-swift-package-guid':336,1226 'take':652 'target':756 'task':360,393 'telemetri':607 'tell':1286 'term':82 'termin':192 'test':43,100,103,180,303,312,320,389,400,448,609,637,697,820,865,973,983,1119,1127,1128,1133,1208,1219 'text':203,737,804 'thin':109 'though':782 'tool':1172 'toolchain':451,1180 'top':1277 'top-level':1276 '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' 'toward':631 'transit':72 'tri':130 'type':437,722,727,742,801,877,897 'understand':917 'unless':830 'use':17,54,143,144,160,182,229,242,257,470,640,682,738,1303 'user':187,414,770,1287,1330,1375,1386 'user-fac':1329 'uv':1341 'v6':583 'vs':199 'want':771 'whether':619 'word':562,808,1381 'work':95,104,189,274,298,991,1112,1145,1212 'workflow':4,6,27,38,44,52,68,90,101,159,281,304,357,390,429,494,693,698,842,852,861,866,969,974,979,984,1095,1120,1142,1209,1295,1318,1359 'workspac':266,365,1150 'wrapper':1336 'xcode':121,208,265,354,364,383,388,398,673,690,696,718,783,858,864,976,982,994,1003,1046,1139,1149,1164,1169,1189,1207,1217 'xcode-build-run-workflow':353,689,857,975,1138 'xcode-manag':382,672,1002,1188 'xcode-n':397,1216 'xcode-testing-workflow':387,695,863,981,1206 'xcodeproj':1197 'xctest':313 'xctestplan':314,404,1223 'xcuitest':402,1221 'xcworkspac':1198 'yet':224,334 'zed':198","prices":[{"id":"ac77f4a8-fd55-4dcc-a6b2-44690802be1f","listingId":"074096e6-eb8b-4dc2-8788-f5b02e221536","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:11.343Z"}],"sources":[{"listingId":"074096e6-eb8b-4dc2-8788-f5b02e221536","source":"github","sourceId":"gaelic-ghost/apple-dev-skills/swift-package-workflow","sourceUrl":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/swift-package-workflow","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:11.343Z","lastSeenAt":"2026-05-18T19:13:58.957Z"}],"details":{"listingId":"074096e6-eb8b-4dc2-8788-f5b02e221536","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"gaelic-ghost","slug":"swift-package-workflow","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":"527a6c6eeab8522ac1a0f2978f6ca4a7f316dd58","skill_md_path":"skills/swift-package-workflow/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/swift-package-workflow"},"layout":"multi","source":"github","category":"apple-dev-skills","frontmatter":{"name":"swift-package-workflow","description":"Compatibility workflow surface for broad or legacy Swift Package Manager execution requests. Use when older references still point at swift-package-workflow and route the request into swift-package-build-run-workflow or swift-package-testing-workflow while preserving SwiftPM-first mixed-root handoff behavior."},"skills_sh_url":"https://skills.sh/gaelic-ghost/apple-dev-skills/swift-package-workflow"},"updatedAt":"2026-05-18T19:13:58.957Z"}}