{"id":"c5acb785-3f03-4bef-a8d5-7e1e25a2e6c3","shortId":"aVmrF4","kind":"skill","title":"author-swift-docc-docs","tagline":"Author and review DocC content for Swift package and Xcode app or framework repositories, including symbol comments, articles, extension files, landing pages, topic groups, and light tutorial-aware review. Use when the user wants help writing or reviewing DocC content, checking D","description":"# Author Swift DocC Docs\n\n## Purpose\n\nProvide the canonical DocC authoring-and-review workflow for Swift package and Xcode app or framework repositories. `scripts/run_workflow.py` is the runtime wrapper for repo-shape detection, task classification, tutorial-depth boundaries, and clean handoffs to the Apple docs and execution skills.\n\n## When To Use\n\n- Use this skill for in-source symbol documentation work that is meant to compile into DocC output.\n- Use this skill for DocC article writing and review.\n- Use this skill for DocC extension-file, landing-page, topic-group, and catalog-structure work.\n- Use this skill when the user wants a DocC-oriented review pass for clarity, content accuracy, or DocC-specific structure quality.\n- Use this skill when the user wants help deciding whether content belongs in source comments, articles, extension files, or landing pages.\n- Use this skill for tutorial-aware DocC review when the user clearly wants DocC tutorial help but the task is still mainly about authoring shape and conceptual flow rather than directive-deep mechanics.\n- Recommend `explore-apple-swift-docs` when the user really needs broader Apple or Swift documentation lookup, WWDC-material lookup, or directive-reference lookup instead of DocC authoring or review work.\n- Recommend `swift-package-build-run-workflow` when a Swift package repo needs `swift package` or build-oriented DocC follow-through such as generation, export, archive inspection, or package-shape execution work.\n- Recommend `xcode-build-run-workflow` when an Xcode app or framework repo needs `Product > Build Documentation`, `xcodebuild docbuild`, export, archive, or project-integrity follow-through.\n\n## Single-Path Workflow\n\n1. Classify the repo shape:\n   - `swift-package`\n   - `xcode-app-framework`\n2. Classify the DocC task:\n   - `symbol-docs`\n   - `article`\n   - `structure`\n   - `review`\n   - `tutorial-aware-review`\n3. Run `scripts/run_workflow.py` so the repo-shape heuristics, task inference, tutorial-depth boundary, and handoff rules resolve into one JSON contract.\n4. If the request is actually broad Apple-docs lookup, hand off to `explore-apple-swift-docs`.\n5. If the request is actually DocC generation, export, hosting, archive, or project-integrity follow-through, hand off to the matching build-run skill for the detected repo shape.\n6. Otherwise stay local to DocC authoring and review:\n   - revise or review source comments\n   - revise or review articles and extension files\n   - review landing-page and topic-group structure\n   - explain the difference between content correctness, DocC correctness, and project correctness\n7. Return one `status`, one `path_type`, one resolved repo shape, one resolved task type, and one next-step contract.\n\n## Inputs\n\n- `repo_path`: optional filesystem root to inspect for `Package.swift`, `.xcodeproj`, `.xcworkspace`, and `.docc` surfaces\n- `repo_shape`: optional explicit override; use `swift-package` or `xcode-app-framework`\n- `task_type`: optional explicit override; use `symbol-docs`, `article`, `structure`, `review`, or `tutorial-aware-review`\n- `request`: optional free-text task description used for inference and handoff decisions\n- `needs_generation`: optional explicit flag for generation, export, archive, hosting, or other execution-heavy DocC follow-through\n- Defaults:\n  - runtime entrypoint: executable `scripts/run_workflow.py`\n  - tutorial handling defaults to the configured first-pass policy in `references/customization-flow.md`\n  - repo-shape inference prefers an explicit override, then on-disk detection, then request wording\n  - task inference prefers an explicit override, then request wording\n\n## Outputs\n\n- `status`\n  - `success`: the request belongs to this DocC authoring-and-review workflow\n  - `handoff`: the request belongs to another skill after DocC-aware classification\n  - `blocked`: the request lacks enough repo-shape or task information to proceed honestly\n- `path_type`\n  - `primary`: the DocC authoring-and-review path completed or the direct handoff decision is ready\n  - `fallback`: the result depended on request-only inference because repo inspection was unavailable\n- `output`\n  - resolved `repo_shape`\n  - resolved `task_type`\n  - detected repo surfaces\n  - tutorial support level\n  - correctness model guidance\n  - recommended skill when handing off\n  - one concise next step\n\n## Guards and Stop Conditions\n\n- Do not pretend the skill has already validated DocC generation or export success unless the work hands off and those steps actually run.\n- Do not silently absorb broad Apple-docs lookup that belongs in `explore-apple-swift-docs`.\n- Do not silently absorb build, export, archive, hosting, or project-integrity work that belongs in the execution skills.\n- Stop with `blocked` when neither repo shape nor task type can be inferred honestly.\n- Keep tutorial support phase-one light; do not imply full tutorial-directive expertise unless the deeper DocC references are consulted explicitly.\n\n## Fallbacks and Handoffs\n\n- Prefer explicit `repo_shape` and `task_type` when the user provides them.\n- Fall back to repo inspection when `repo_path` is available.\n- Fall back to request-text inference when repo inspection is missing or incomplete.\n- Hand off to `explore-apple-swift-docs` when the request is primarily about finding DocC or Apple documentation rather than writing or reviewing DocC content.\n- Hand off to `swift-package-build-run-workflow` when a package repo needs generation, export, archive, or build-oriented DocC follow-through.\n- Hand off to `xcode-build-run-workflow` when an Xcode repo needs generation, export, archive, `docbuild`, or project-integrity follow-through.\n- `scripts/run_workflow.py` is the top-level runtime entrypoint and converts repo inspection plus request inference into the documented JSON contract.\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 the runtime-safe tutorial-depth setting before shaping the final workflow contract.\n\n## References\n\n### Workflow References\n\n- `references/xcode-docc-sources.md`\n- `references/swift-docc-sources.md`\n- `references/repo-shape-and-handoffs.md`\n\n### Contract References\n\n- `references/automation-prompts.md`\n- `references/customization-flow.md`\n\n### Support References\n\n- `references/docc-correctness-model.md`\n\n### Script Inventory\n\n- `scripts/run_workflow.py`\n- `scripts/customization_config.py`","tags":["author","swift","docc","docs","apple","dev","skills","gaelic-ghost","agent-skills","apple-development","apple-docs","apple-docs-mcp"],"capabilities":["skill","source-gaelic-ghost","skill-author-swift-docc-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/author-swift-docc-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 (6,508 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.148Z","embedding":null,"createdAt":"2026-05-18T13:21:10.156Z","updatedAt":"2026-05-18T19:13:58.148Z","lastSeenAt":"2026-05-18T19:13:58.148Z","tsv":"'1':326 '2':338 '3':353 '4':376 '5':395 '6':427 '7':468 'absorb':736,753 'accuraci':163 'actual':381,400,731 'alreadi':716 'anoth':628 'app':16,68,303,336,516 'appl':93,229,238,384,392,739,747,850,862 'apple-doc':383,738 'archiv':286,314,405,556,756,887,911 'articl':23,124,185,346,444,527 'author':2,6,49,59,215,255,433,619,655 'author-swift-docc-doc':1 'authoring-and-review':58,618,654 'avail':830 'awar':34,197,351,533,633 'back':822,832 'belong':181,614,626,743,764 'block':635,771 'boundari':87,367 'broad':382,737 'broader':237 'build':263,276,297,309,419,754,877,890,901 'build-ori':275,889 'build-run':418 'canon':56 'catalog':144 'catalog-structur':143 'check':47 'clariti':161 'classif':83,634 'classifi':327,339 'clean':89 'clear':203 'comment':22,184,440 'compil':115 'complet':659 'conceptu':218 'concis':703 'condit':709 'configur':577 'consult':804 'content':10,46,162,180,461,870 'contract':375,488,939,964,971 'convert':929 'correct':462,464,467,694 'custom':940,947 'd':48 'decid':178 'decis':547,664 'deep':224 'deeper':800 'default':567,574 'depend':670 'depth':86,366,957 'descript':541 'detect':81,424,596,688 'differ':459 'direct':223,249,662,796 'directive-deep':222 'directive-refer':248 'disk':595 'doc':5,52,94,231,345,385,394,526,740,749,852 'docbuild':312,912 'docc':4,9,45,51,57,117,123,132,156,166,198,205,254,278,341,401,432,463,502,563,617,632,653,718,801,860,869,892 'docc-awar':631 'docc-ori':155 'docc-specif':165 'document':109,241,310,863,937 'enough':639 'entrypoint':569,927 'execut':96,292,561,570,767 'execution-heavi':560 'expertis':797 'explain':457 'explicit':507,521,551,590,604,805,810 'explor':228,391,746,849 'explore-apple-swift-doc':227,390,745,848 'export':285,313,403,555,721,755,886,910 'extens':24,134,186,446 'extension-fil':133 'fall':821,831 'fallback':667,806 'file':25,135,187,447 'filesystem':493 'final':962 'find':859 'first':579 'first-pass':578 'flag':552 'flow':219 'follow':280,320,411,565,894,918 'follow-through':279,319,410,564,893,917 'framework':18,70,305,337,517 'free':538 'free-text':537 'full':793 'generat':284,402,549,554,719,885,909 'group':29,141,455 'guard':706 'guidanc':696 'hand':387,413,700,726,845,871,896 'handl':573 'handoff':90,369,546,623,663,808 'heavi':562 'help':41,177,207 'heurist':361 'honest':648,782 'host':404,557,757 'impli':792 'in-sourc':105 'includ':20 'incomplet':844 'infer':363,544,587,601,675,781,837,934 'inform':645 'input':489 'inspect':287,496,678,825,840,931 'instead':252 'integr':318,409,761,916 'inventori':979 'json':374,938 'keep':783 'lack':638 'land':26,137,189,450 'landing-pag':136,449 'level':693,925 'light':31,789 'load':950 'local':430 'lookup':242,246,251,386,741 'main':213 'match':417 'materi':245 'meant':113 'mechan':225 'miss':842 'model':695 'need':236,271,307,548,884,908 'neither':773 'next':486,704 'next-step':485 'on-disk':593 'one':373,470,472,475,479,484,702,788 'option':492,506,520,536,550 'orient':157,277,891 'otherwis':428 'output':118,609,681 'overrid':508,522,591,605 'packag':13,65,262,269,273,290,333,512,876,882 'package-shap':289 'package.swift':498 'page':27,138,190,451 'pass':159,580 'path':324,473,491,649,658,828 'phase':787 'phase-on':786 'plus':932 'polici':581 'prefer':588,602,809 'pretend':712 'primari':651 'primarili':857 'proceed':647 'product':308 'project':317,408,466,760,915 'project-integr':316,407,759,914 'provid':54,819 'purpos':53 'qualiti':169 'rather':220,864 'readi':666 'realli':235 'recommend':226,259,294,697 'refer':250,802,965,967,972,976 'references/automation-prompts.md':973 'references/customization-flow.md':583,942,974 'references/docc-correctness-model.md':977 'references/repo-shape-and-handoffs.md':970 'references/swift-docc-sources.md':969 'references/xcode-docc-sources.md':968 'repo':79,270,306,329,359,425,477,490,504,585,641,677,683,689,774,811,824,827,839,883,907,930 'repo-shap':78,358,584,640 'report':946 'repositori':19,71 'request':379,398,535,598,607,613,625,637,673,835,855,933 'request-on':672 'request-text':834 'resolv':371,476,480,682,685 'result':669 'return':469 'review':8,35,44,61,127,158,199,257,348,352,435,438,443,448,529,534,621,657,868 'revis':436,441 'root':494 'rule':370 'run':264,298,354,420,732,878,902 'runtim':75,568,926,953 'runtime-saf':952 'safe':954 'script':978 'scripts/customization_config.py':943,981 'scripts/run_workflow.py':72,355,571,920,949,980 'set':958 'shape':80,216,291,330,360,426,478,505,586,642,684,775,812,960 'silent':735,752 'singl':323 'single-path':322 'skill':97,103,121,130,149,172,193,421,629,698,714,768 'skill-author-swift-docc-docs' 'sourc':107,183,439 'source-gaelic-ghost' 'specif':167 'state':948 'status':471,610 'stay':429 'step':487,705,730 'still':212 'stop':708,769 'store':944 'structur':145,168,347,456,528 'success':611,722 'support':692,785,975 'surfac':503,690 'swift':3,12,50,64,230,240,261,268,272,332,393,511,748,851,875 'swift-packag':331,510 'swift-package-build-run-workflow':260,874 'symbol':21,108,344,525 'symbol-doc':343,524 'task':82,210,342,362,481,518,540,600,644,686,777,814 'text':539,836 'top':924 'top-level':923 'topic':28,140,454 '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-group':139,453 'topic-ios' 'topic-macos' 'topic-swift' 'tutori':33,85,196,206,350,365,532,572,691,784,795,956 'tutorial-awar':32,195 'tutorial-aware-review':349,531 'tutorial-depth':84,364,955 'tutorial-direct':794 'type':474,482,519,650,687,778,815 'unavail':680 'unless':723,798 'use':36,100,101,119,128,147,170,191,509,523,542,941 'user':39,152,175,202,234,818 'valid':717 'want':40,153,176,204 'whether':179 'word':599,608 'work':110,146,258,293,725,762 'workflow':62,265,299,325,622,879,903,963,966 'wrapper':76 'write':42,125,866 'wwdc':244 'wwdc-materi':243 'xcode':15,67,296,302,335,515,900,906 'xcode-app-framework':334,514 'xcode-build-run-workflow':295,899 'xcodebuild':311 'xcodeproj':499 'xcworkspac':500","prices":[{"id":"491afe1b-438a-40cd-805d-345cdfa87e61","listingId":"c5acb785-3f03-4bef-a8d5-7e1e25a2e6c3","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.156Z"}],"sources":[{"listingId":"c5acb785-3f03-4bef-a8d5-7e1e25a2e6c3","source":"github","sourceId":"gaelic-ghost/apple-dev-skills/author-swift-docc-docs","sourceUrl":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/author-swift-docc-docs","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:10.156Z","lastSeenAt":"2026-05-18T19:13:58.148Z"}],"details":{"listingId":"c5acb785-3f03-4bef-a8d5-7e1e25a2e6c3","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"gaelic-ghost","slug":"author-swift-docc-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":"01d31e92876b75e8d3eeaf5b6f2634e050c7e6a7","skill_md_path":"skills/author-swift-docc-docs/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/author-swift-docc-docs"},"layout":"multi","source":"github","category":"apple-dev-skills","frontmatter":{"name":"author-swift-docc-docs","description":"Author and review DocC content for Swift package and Xcode app or framework repositories, including symbol comments, articles, extension files, landing pages, topic groups, and light tutorial-aware review. Use when the user wants help writing or reviewing DocC content, checking DocC structure or content correctness, or deciding when DocC work should hand off to Apple docs lookup or build and export workflows."},"skills_sh_url":"https://skills.sh/gaelic-ghost/apple-dev-skills/author-swift-docc-docs"},"updatedAt":"2026-05-18T19:13:58.148Z"}}