https://github.com/gaelic-ghost/apple-dev-skills
Codex skills for Apple dev workflows: Xcode MCP-first execution, automatic xcodebuild/xcrun/SwiftPM fallback, swiftly+toolchain guidance, and Dash local-docset docs.
https://github.com/gaelic-ghost/apple-dev-skills
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
Last synced: 8 days ago
JSON representation
Codex skills for Apple dev workflows: Xcode MCP-first execution, automatic xcodebuild/xcrun/SwiftPM fallback, swiftly+toolchain guidance, and Dash local-docset docs.
- Host: GitHub
- URL: https://github.com/gaelic-ghost/apple-dev-skills
- Owner: gaelic-ghost
- License: apache-2.0
- Created: 2026-02-27T18:30:41.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-29T00:18:05.000Z (14 days ago)
- Last Synced: 2026-04-29T01:02:15.229Z (14 days ago)
- 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
- Language: Python
- Homepage:
- Size: 1.91 MB
- Stars: 7
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# apple-dev-skills
Apple, Swift, and Xcode workflow skills for Codex and Claude Code.
## Table of Contents
- [Overview](#overview)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Development](#development)
- [Repo Structure](#repo-structure)
- [Active Skills](#active-skills)
- [Release Notes](#release-notes)
- [License](#license)
## Overview
### Status
This repository is active and available for maintainer use.
### What This Project Is
This repository is the canonical source of truth for Gale's Apple, Swift, and Xcode workflow skills. Treat `productivity-skills` as the default baseline layer for general repo-doc and maintenance work, and use `apple-dev-skills` when Apple-specific assumptions should actively shape the workflow.
### Motivation
It exists to keep Apple-platform workflow guidance in one dedicated repository with explicit requirements around Apple documentation, Xcode-safe workflows, and clear source-of-truth boundaries.
## Quick Start
This repository is primarily the authored source tree for the shipped Apple workflow skills rather than an end-user app with a separate getting-started path. If you want to understand what the repo currently ships, start with [Active Skills](#active-skills) and [`docs/maintainers/workflow-atlas.md`](./docs/maintainers/workflow-atlas.md). If you want to modify the repository, go to [Development](#development) and use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the maintainer workflow.
## Usage
Use this repository's skills when the work is about:
- Swift or SwiftUI implementation
- Apple UI accessibility implementation or review
- SwiftUI app structure, focus design, scene ownership, or command architecture
- Xcode build, run, or test workflows
- DocC symbol comments, articles, catalog structure, or DocC-oriented review
- Swift source cleanup, file-header normalization, or source-organization policy
- Swift package bootstrap or validation
- Apple-project guidance sync
- Apple-platform documentation routing
When installed as a Codex plugin, this repository also registers Xcode's built-in MCP bridge through `xcrun mcpbridge`. Users still need to allow external agents in Xcode's Intelligence settings and keep the relevant project open in Xcode before external Codex sessions can use Xcode-provided tools.
### Codex Plugin Install
This repository can be installed on its own through Codex's Git-backed marketplace flow. The repo-local Codex marketplace lives at [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), and its single plugin entry points at this repository root with `source.path` set to `./` because the root directory is also the plugin root.
Prefer the official Git-backed install and update path:
```bash
codex plugin marketplace add gaelic-ghost/apple-dev-skills
codex plugin marketplace upgrade apple-dev-skills
```
After Codex adds or upgrades the marketplace, restart Codex, open the plugin directory in the Codex GUI, choose the `Apple Dev Skills` marketplace, and install or enable `apple-dev-skills` there. Manual local clone marketplaces and personal copied-payload entries are development, unpublished-testing, and fallback paths rather than the default user install story.
### Companion Plugin Requirements
Most Apple Dev Skills workflows are useful as a standalone plugin. The bootstrap and repo-guidance sync workflows that install or refresh `scripts/repo-maintenance/` also need the companion [`productivity-skills`](https://github.com/gaelic-ghost/productivity-skills) plugin installed alongside this plugin, because `productivity-skills` owns the reusable `maintain-project-repo` implementation while Apple Dev Skills chooses the Apple-specific `swift-package` or `xcode-app` profile.
If an agent has only `apple-dev-skills` installed, it can still use the documentation lookup, SwiftUI architecture, Xcode build/run/test, DocC, formatting, source-structure, and accessibility workflows. It should install `productivity-skills` before running `bootstrap-swift-package`, `bootstrap-xcode-app-project`, `sync-swift-package-guidance`, or `sync-xcode-project-guidance` in mutating mode.
The [`socket`](https://github.com/gaelic-ghost/socket) repository is Gale's plugin superproject and marketplace catalog. Installing from the Git-backed socket marketplace is useful when you want Apple Dev Skills plus Gale's other Codex plugins available from one marketplace instead of wiring each plugin one by one:
```bash
codex plugin marketplace add gaelic-ghost/socket
codex plugin marketplace upgrade socket
```
After adding `socket`, restart Codex, open the plugin directory in the Codex GUI, choose the `Socket` marketplace, and install or enable `apple-dev-skills` plus any companion plugins you want. Standalone Git-backed installs from this repository remain supported for Apple-only workflows that do not call `maintain-project-repo`. Use an explicit ref such as `gaelic-ghost/apple-dev-skills@vX.Y.Z` only when you want a pinned reproducible install rather than the release-aligned default branch.
Use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for maintainer workflow details, and use [`ROADMAP.md`](./ROADMAP.md) for planned and completed milestone-level work.
## Development
### Setup
Sync the maintainer environment before editing skills, tests, or maintainer docs:
```bash
uv sync --dev
```
### Workflow
Treat root [`skills/`](./skills/) as the canonical authored surface. Keep shared reusable assets in [`shared/`](./shared/), maintainer docs in [`docs/`](./docs/), and install metadata in [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json), [`.mcp.json`](./.mcp.json), [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), and [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json).
Keep the repo honest about its Apple docs-first policy. When a skill changes, update the relevant tests and maintainer guidance in the same pass rather than letting the packaging or guidance drift. Use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the normal contributor workflow and review expectations.
### Validation
Run the repository test suite for skill and metadata changes:
```bash
bash .github/scripts/validate_repo_docs.sh
uv run pytest
```
## Repo Structure
```text
.
├── .codex-plugin/
├── .claude-plugin/
├── .mcp.json
├── AGENTS.md
├── CONTRIBUTING.md
├── README.md
├── ROADMAP.md
├── docs/maintainers/
├── shared/
├── skills/
└── tests/
```
## Active Skills
- `bootstrap-swift-package`
- `bootstrap-xcode-app-project`
- `author-swift-docc-docs`
- `explore-apple-swift-docs`
- `apple-ui-accessibility-workflow`
- `format-swift-sources`
- `structure-swift-sources`
- `swiftui-app-architecture-workflow`
- `swift-package-build-run-workflow`
- `swift-package-testing-workflow`
- `swift-package-workflow`
- `sync-swift-package-guidance`
- `sync-xcode-project-guidance`
- `xcode-app-project-workflow`
- `xcode-build-run-workflow`
- `xcode-testing-workflow`
## Release Notes
Use Git history and GitHub releases to track shipped changes for this repository.
## License
See [LICENSE](./LICENSE).