{"id":"e7cbc0d1-3be9-4818-aad2-7c0652766f6f","shortId":"rAaaUE","kind":"skill","title":"xcode-build-run-workflow","tagline":"Guide build, run, preview-adjacent, workspace-inspection, diagnostics, toolchain, and guarded mutation work in existing Xcode-managed projects and workspaces. Use when Xcode-aware execution is needed and the task is primarily about build, run, or project-integrity work rather tha","description":"# Xcode Build Run Workflow\n\n## Purpose\n\nUse this skill as the primary execution workflow for non-testing work in or around Xcode-managed projects and workspaces. Keep it focused on workspace inspection, read/search diagnostics, builds, runs, previews, toolchain management, file membership, Release-versus-Debug validation, and the `.pbxproj` warning boundary. `scripts/run_workflow.py` is the runtime entrypoint for MCP-first build/run execution, official CLI fallback planning, and direct `.pbxproj` warning enforcement.\n\n## When To Use\n\n- Use this skill for Xcode workspace inspection, project discovery, read/search diagnostics, build, run, preview, and navigator-issue tasks.\n- Use this skill for Xcode MCP operations, scheme-aware execution, and official Apple CLI fallback when the work is primarily about build/run rather than tests.\n- Use this skill when direct filesystem mutation around an Xcode-managed project may be required.\n- Use this skill for file-membership and target-membership verification after on-disk edits.\n- Use this skill for Debug/Release build-configuration work, artifacts, archives, toolchain checks, and Metal-toolchain-aware build execution.\n- Do not use this skill as the default path for Swift Testing, XCTest, XCUITest, `.xctestplan`, flaky-test diagnosis, retries, or test filtering.\n- Recommend `xcode-testing-workflow` when the task is primarily about tests or test diagnosis.\n- Recommend `explore-apple-swift-docs` when the user needs Apple or Swift documentation lookup rather than execution work.\n- Recommend `swift-package-build-run-workflow` or `swift-package-testing-workflow` when the task is ordinary SwiftPM package work outside Xcode-managed execution.\n- Recommend `sync-xcode-project-guidance` when an existing Xcode app repo needs `AGENTS.md` or workflow-guidance alignment rather than active engineering work.\n\n## Single-Path Workflow\n\n1. Classify the request into one operation type:\n   - workspace or session inspection\n   - read, search, or diagnostics\n   - build or run\n   - package or toolchain management\n   - mutation\n2. Apply the Apple docs gate before any Apple design, architecture, implementation, or refactor guidance:\n   - use `explore-apple-swift-docs` to gather the relevant Apple documentation first\n   - state the documented API behavior, lifecycle rule, or workflow requirement being relied on before proposing changes\n   - do not rely on memory as the primary source when Apple docs exist\n   - if the docs and the current code conflict, stop and report that conflict\n   - if no relevant Apple docs can be found, say that explicitly before proceeding\n3. Apply the shared Swift policy before giving implementation guidance:\n   - apply the detailed local policy in `references/snippets/apple-xcode-project-core.md`\n   - preserve its simplicity-first, shape-preserving, and anti-ceremony Swift guidance\n   - preserve its project-appropriate logging, telemetry, and SwiftUI architecture guidance\n4. Run `scripts/run_workflow.py` to apply runtime configuration, `.pbxproj` warning safeguards, and CLI fallback planning.\n5. Use the guidance in `references/mcp-tool-matrix.md` for agent-executed MCP operations.\n6. Use `references/xcodegen-project-maintenance.md` when the repo is XcodeGen-backed and the task touches generated targets, schemes, build settings, packages, file membership, resource membership, or generation options.\n7. Use `references/testing-plans-file-membership-and-configurations.md` when the task touches file membership after filesystem edits or Debug/Release validation.\n8. If MCP fails, use the structured fallback output from `scripts/run_workflow.py` together with `references/cli-fallback-matrix.md`.\n9. Report which parts were agent-executed, which parts were locally enforced by script, the Apple docs relied on, any tracked `.pbxproj` diff that must be staged and committed with the branch, and any required next step.\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- `workspace_path`: optional absolute path for the target Xcode or Swift workspace.\n- `tab_identifier`: optional MCP tab identifier when already known.\n- `mcp_failure_reason`: optional input when continuing from an earlier MCP failure.\n- `direct_pbxproj_edit`: optional flag when the requested mutation would directly edit a `.pbxproj` file.\n- `direct_pbxproj_edit_opt_in`: optional explicit opt-in after the user has been warned about direct `.pbxproj` edit risks.\n- Defaults:\n  - runtime entrypoint: executable `scripts/run_workflow.py`\n  - the runtime may infer `operation_type` from `--request` text when the request wording is clear enough\n  - agent-side MCP retries once for transient failures\n  - direct edits are allowed by default when they do not directly edit `.pbxproj`\n\n## Outputs\n\n- `status`\n  - `success`: the workflow completed on its primary or fallback path\n  - `handoff`: the workflow is handing off to another skill because the request is actually test-focused\n  - `blocked`: prerequisites, policy, or mutation safeguards prevented completion\n- `path_type`\n  - `primary`: the guided agent-side MCP path completed successfully\n  - `fallback`: the official CLI fallback path completed successfully\n- `output`\n  - operation type\n  - `guard_result`\n  - `fallback_commands`\n  - one next step payload when needed\n\n## Guards and Stop Conditions\n\n- Apply the mutation safeguard from `references/mutation-risk-policy.md` only when the operation type is `mutation`.\n- Do not skip the explicit warning path for direct `.pbxproj` edits.\n- In XcodeGen-backed repos, edit the XcodeGen spec set and regenerate the project instead of hand-editing generated `.pbxproj` files.\n- Stop with `handoff` when the request is really test-focused work.\n- Stop with `blocked` when the required workspace context cannot be resolved and the operation cannot safely continue.\n- Stop with `blocked` when allowlist or sandbox rules prevent the official CLI fallback and no safe alternative exists.\n\n## Fallbacks and Handoffs\n\n- Official CLI execution is the only fallback path when the primary agent-side MCP path cannot complete.\n- Use `references/mcp-failure-handoff.md` for the canonical fallback and handoff payload.\n- Use `references/allowlist-guidance.md` when a safe official CLI fallback is blocked by local rules.\n- Hand off to `xcode-testing-workflow` when the request becomes primarily about Swift Testing, XCTest, XCUITest, `.xctestplan`, flaky tests, test retries, or test filtering.\n- Recommend `explore-apple-swift-docs` directly when the task becomes Apple or Swift docs exploration work.\n- Recommend `swift-package-build-run-workflow` or `swift-package-testing-workflow` directly when the task becomes ordinary SwiftPM package work.\n- Recommend `format-swift-sources` directly when the task becomes SwiftLint or SwiftFormat setup, config export, or style-tooling maintenance work.\n- Recommend `structure-swift-sources` directly when the task becomes structural source cleanup work.\n- Recommend `bootstrap-swift-package` directly when the task becomes new-package scaffolding.\n- Recommend `sync-xcode-project-guidance` directly when the repo needs Xcode-specific guidance sync rather than execution.\n- `scripts/run_workflow.py` plans fallback commands; MCP execution itself remains agent-side tool usage guided by this skill.\n- When maintaining this repository itself, refresh repo-guidance consumers after substantial Xcode-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-flow.md`.\n- `scripts/customization_config.py` stores and reports customization state.\n- `scripts/run_workflow.py` reads customization state for the remaining user-facing execution knobs.\n- MCP tool execution itself remains agent-side and is not performed by the local runtime entrypoint or by the skill as a direct runtime.\n\n## References\n\n### Workflow References\n\n- `references/workflow-policy.md`\n- `references/mcp-tool-matrix.md`\n- `references/cli-fallback-matrix.md`\n- `references/toolchain-management.md`\n- `references/testing-plans-file-membership-and-configurations.md`\n- `references/xcodegen-project-maintenance.md`\n- `references/mutation-risk-policy.md`\n- `references/mutation-via-mcp.md`\n\n### Contract References\n\n- `references/mcp-failure-handoff.md`\n- `references/customization-flow.md`\n\n### Support References\n\n- Recommend `explore-apple-swift-docs` when the user needs Apple or Swift docs exploration or Dash-compatible docs access.\n- Recommend `format-swift-sources` when the user needs SwiftLint or SwiftFormat setup rather than active Xcode execution.\n- Recommend `structure-swift-sources` when the user needs structural Swift source cleanup rather than active Xcode execution.\n- Recommend `sync-xcode-project-guidance` when the user needs repo guidance aligned inside an existing Xcode app repo.\n- Recommend `references/snippets/apple-xcode-project-core.md` when the user needs to add or merge the shared Xcode-project guidance into an end-user repo.\n- `references/allowlist-guidance.md`\n- `references/skills-installation.md`\n- `references/skills-discovery.md`\n- `references/snippets/apple-xcode-project-core.md`\n\n### Script Inventory\n\n- `scripts/run_workflow.py`\n- `scripts/detect_xcode_managed_scope.sh`\n- `scripts/customization_config.py`","tags":["xcode","build","run","workflow","apple","dev","skills","gaelic-ghost","agent-skills","apple-development","apple-docs","apple-docs-mcp"],"capabilities":["skill","source-gaelic-ghost","skill-xcode-build-run-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/xcode-build-run-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,519 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:59.417Z","embedding":null,"createdAt":"2026-05-18T13:21:11.997Z","updatedAt":"2026-05-18T19:13:59.417Z","lastSeenAt":"2026-05-18T19:13:59.417Z","tsv":"'1':336 '2':360 '3':443 '4':485 '5':499 '6':511 '7':538 '8':553 '9':567 'absolut':637 'access':1234 'activ':329,1250,1268 'actual':771 'add':1297 'adjac':11 'agent':507,573,725,789,928,1098,1178 'agent-execut':506,572 'agent-sid':724,788,927,1097,1177 'agents.md':321 'align':326,1132,1283 'allow':736 'allowlist':899 'alreadi':653 'altern':911 'anoth':765 'anti':470 'anti-ceremoni':469 'api':391 'app':318,1288 'appl':159,266,273,363,368,378,385,414,433,583,984,992,1217,1224 'appli':361,444,453,489,820 'appropri':478 'architectur':370,483 'archiv':215 'around':72,179 'artifact':214 'awar':33,155,222 'back':520,847 'becom':966,991,1015,1029,1051,1065 'behavior':392 'block':775,880,897,952 'bootstrap':1058 'bootstrap-swift-packag':1057 'boundari':103 'branch':599 'build':3,7,43,53,87,138,211,223,286,352,528,1002 'build-configur':210 'build/run':113,168 'cannot':886,892,932 'canon':938 'ceremoni':471 'chang':403,1121 'check':217 'classifi':337 'cleanup':1054,1265 'clear':722 'cli':116,160,496,798,906,917,949 'code':423 'command':809,1092 'commit':596 'compat':1232 'complet':751,782,793,801,933 'condit':819 'config':1034 'configur':212,491 'conflict':424,429 'consum':1115 'context':885 'continu':661,894 'contract':1208 'current':422 'custom':1151,1158,1162 'dash':1231 'dash-compat':1230 'debug':97 'debug/release':209,551 'default':232,703,738 'design':369 'detail':455 'diagnosi':243,262 'diagnost':15,86,137,351 'diff':590 'direct':120,176,667,677,682,699,733,743,841,987,1011,1025,1047,1061,1076,1195 'discoveri':135 'disk':203 'doc':268,364,380,415,419,434,584,986,995,1131,1219,1227,1233 'document':276,386,390 'earlier':664 'edit':204,549,669,678,684,701,734,744,843,849,862 'end':1309 'end-us':1308 'enforc':123,579 'engin':330 'enough':723 'entrypoint':108,705,1188 'execut':34,63,114,156,224,280,307,508,574,706,918,1088,1094,1170,1174,1252,1270 'exist':22,316,416,912,1286 'explicit':440,630,688,837 'explor':265,377,983,996,1216,1228 'explore-apple-swift-doc':264,376,982,1215 'export':1035,1129 'export-surfac':1128 'face':1169 'fail':556 'failur':656,666,732 'fallback':117,161,497,560,756,795,799,808,907,913,922,939,950,1091 'file':92,193,531,545,681,865 'file-membership':192 'filesystem':177,548 'filter':247,980 'first':112,387,464 'flag':671 'flaki':241,974 'flaky-test':240 'focus':81,774,876 'format':1022,1237 'format-swift-sourc':1021,1236 'found':437 'gate':365 'gather':382 'generat':525,536,863 'give':450 'guard':18,806,816 'guid':6,787,1102 'guidanc':313,325,374,452,473,484,502,1075,1084,1114,1276,1282,1305 'hand':762,861,956 'hand-edit':860 'handoff':758,868,915,941 'identifi':647,651 'implement':371,451 'infer':625,711 'input':605,659 'insid':1284 'inspect':14,84,133,347 'instal':1143 'instead':858 'integr':48 'inventori':1317 'issu':144 'keep':79,1123 'knob':1171 'known':654 'languag':620 'level':1127 'lifecycl':393 'list':613 'local':456,578,954,1142,1186 'log':479 'lookup':277 'maintain':1107 'mainten':1040 'manag':25,75,91,183,306,358 'may':185,710 'mcp':111,151,509,555,649,655,665,727,791,930,1093,1172 'mcp-first':110 'membership':93,194,198,532,534,546 'memori':408 'merg':1299 'metal':220 'metal-toolchain-awar':219 'must':592 'mutat':19,178,359,675,779,822,832 'natur':619 'natural-languag':618 'navig':143 'navigator-issu':142 'need':36,272,320,815,1080,1223,1243,1261,1280,1295 'new':1067 'new-packag':1066 'next':603,811 'non':67 'non-test':66 'offici':115,158,797,905,916,948 'omit':633 'on-disk':201 'one':341,608,810 'oper':152,342,510,606,611,626,631,712,804,829,891 'opt':685,690 'opt-in':689 'option':537,616,636,648,658,670,687 'ordinari':299,1016 'output':561,746,803 'outsid':303 'packag':285,292,301,355,530,1001,1008,1018,1060,1068 'part':570,576 'path':233,334,635,638,757,783,792,800,839,923,931 'payload':813,942 'pbxproj':101,121,492,589,668,680,683,700,745,842,864 'perform':1183 'plan':118,498,1090 'polici':448,457,777,1120 'prerequisit':776 'preserv':460,467,474 'prevent':781,903 'preview':10,89,140 'preview-adjac':9 'primari':62,411,754,785,926 'primarili':41,166,257,967 'proceed':442 'project':26,47,76,134,184,312,477,857,1074,1275,1304 'project-appropri':476 'project-integr':46 'propos':402 'purpos':56 'rather':50,169,278,327,1086,1248,1266 'read':348,1161 'read/search':85,136 'realli':873 'reason':657 'recommend':248,263,282,308,981,998,1020,1042,1056,1070,1214,1235,1253,1271,1290 'refactor':373 'refer':1197,1199,1209,1213 'references/allowlist-guidance.md':944,1312 'references/cli-fallback-matrix.md':566,1202 'references/customization-flow.md':1153,1211 'references/mcp-failure-handoff.md':935,1210 'references/mcp-tool-matrix.md':504,1201 'references/mutation-risk-policy.md':825,1206 'references/mutation-via-mcp.md':1207 'references/skills-discovery.md':1314 'references/skills-installation.md':1313 'references/snippets/apple-xcode-project-core.md':459,1291,1315 'references/testing-plans-file-membership-and-configurations.md':540,1204 'references/toolchain-management.md':1203 'references/workflow-policy.md':1200 'references/xcodegen-project-maintenance.md':513,1205 'refresh':1111 'regener':855 'releas':95 'release-versus-debug':94 'relev':384,432 'reli':399,406,585,1138 'remain':1096,1166,1176 'repo':319,516,848,1079,1113,1141,1281,1289,1311 'repo-guid':1112 'repo-loc':1140 'report':427,568,1157 'repositori':1109,1146 'request':339,615,621,674,715,719,769,871,965 'requir':187,397,602,883 'resolv':888 'resourc':533 'result':807 'retri':244,728,977 'risk':702 'rule':394,902,955 'run':4,8,44,54,88,139,287,354,486,1003 'runtim':107,490,704,709,1187,1196 'safe':893,910,947 'safeguard':494,780,823 'sandbox':901 'say':438 'scaffold':1069 'scheme':154,527 'scheme-awar':153 'script':581,1316 'scripts/customization_config.py':1154,1320 'scripts/detect_xcode_managed_scope.sh':1319 'scripts/run_workflow.py':104,487,563,707,1089,1160,1318 'search':349 'session':346 'set':529,853 'setup':1033,1247 'shape':466 'shape-preserv':465 'share':446,1301 'ship':1149 'short':617 'side':726,790,929,1099,1179 'simplic':463 'simplicity-first':462 'singl':333 'single-path':332 'skill':59,129,148,174,190,207,229,766,1105,1192 'skill-xcode-build-run-workflow' 'skip':835 'sourc':412,1024,1046,1053,1239,1257,1264 'source-gaelic-ghost' 'spec':852 'specif':1083 'stage':594 'state':388,1159,1163 'status':747 'step':604,812 'stop':425,818,866,878,895 'store':1155 'structur':559,1044,1052,1255,1262 'structure-swift-sourc':1043,1254 'style':1038 'style-tool':1037 'substanti':1117 'success':748,794,802 'support':1212 'surfac':1130 'swift':235,267,275,284,291,379,447,472,644,969,985,994,1000,1007,1023,1045,1059,1218,1226,1238,1256,1263 'swift-package-build-run-workflow':283,999 'swift-package-testing-workflow':290,1006 'swiftformat':1032,1246 'swiftlint':1030,1244 'swiftpm':300,1017 'swiftui':482 'sync':310,1072,1085,1273 'sync-xcode-project-guid':309,1071,1272 'tab':646,650 'target':197,526,641 'target-membership':196 'task':39,145,255,297,523,543,990,1014,1028,1050,1064 'telemetri':480 'tell':1135 'test':68,171,236,242,246,251,259,261,293,773,875,961,970,975,976,979,1009 'test-focus':772,874 'text':622,716 'tha':51 'togeth':564 'tool':1039,1100,1173 'toolchain':16,90,216,221,357 'top':1126 'top-level':1125 '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' 'touch':524,544 'track':588 'transient':731 'type':343,607,612,627,713,784,805,830 'usag':1101 'use':29,57,126,127,146,172,188,205,227,375,500,512,539,557,623,934,943,1152 'user':271,694,1136,1168,1222,1242,1260,1279,1294,1310 'user-fac':1167 'valid':98,552 'verif':199 'versus':96 'warn':102,122,493,697,838 'word':720 'work':20,49,69,164,213,281,302,331,877,997,1019,1041,1055 'workflow':5,55,64,252,288,294,324,335,396,750,760,962,1004,1010,1144,1198 'workflow-guid':323 'workspac':13,28,78,83,132,344,634,645,884 'workspace-inspect':12 'would':676 'xcode':2,24,32,52,74,131,150,182,250,305,311,317,642,960,1073,1082,1119,1251,1269,1274,1287,1303 'xcode-awar':31 'xcode-build-run-workflow':1 'xcode-manag':23,73,181,304 'xcode-polici':1118 'xcode-project':1302 'xcode-specif':1081 'xcode-testing-workflow':249,959 'xcodegen':519,846,851 'xcodegen-back':518,845 'xctest':237,971 'xctestplan':239,973 'xcuitest':238,972","prices":[{"id":"4fb463bf-0e6e-4eab-b813-a1e2ec50a6c8","listingId":"e7cbc0d1-3be9-4818-aad2-7c0652766f6f","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.997Z"}],"sources":[{"listingId":"e7cbc0d1-3be9-4818-aad2-7c0652766f6f","source":"github","sourceId":"gaelic-ghost/apple-dev-skills/xcode-build-run-workflow","sourceUrl":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/xcode-build-run-workflow","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:11.997Z","lastSeenAt":"2026-05-18T19:13:59.417Z"}],"details":{"listingId":"e7cbc0d1-3be9-4818-aad2-7c0652766f6f","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"gaelic-ghost","slug":"xcode-build-run-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":"8307c4fe60c0fe9c733005f63ba490931bc564b0","skill_md_path":"skills/xcode-build-run-workflow/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/xcode-build-run-workflow"},"layout":"multi","source":"github","category":"apple-dev-skills","frontmatter":{"name":"xcode-build-run-workflow","description":"Guide build, run, preview-adjacent, workspace-inspection, diagnostics, toolchain, and guarded mutation work in existing Xcode-managed projects and workspaces. Use when Xcode-aware execution is needed and the task is primarily about build, run, or project-integrity work rather than testing."},"skills_sh_url":"https://skills.sh/gaelic-ghost/apple-dev-skills/xcode-build-run-workflow"},"updatedAt":"2026-05-18T19:13:59.417Z"}}