claude-plugins/README.md

claude-plugins

PDAT's Claude Code plugin marketplace. One plugin so far, covering Apple platform work; the marketplace is named pdat rather than after a platform so the rest can join it later without a second one.

What is here

pdat-swift-practice — two skills.

apple-findings is a curated file of APIs worth adopting that we found elsewhere: what each one is, what it would replace in our code, whether it is genuinely a step forward, and where we read about it. Written in our own words with sources named — see Sourcing.

xcode-practice is the opposite direction: practices for SwiftUI, Core Data, XcodeGen and Swift Testing that came out of shipping apps: work that must not happen in a view body, blobs that must stay off the main thread, derived collections computed once, Keychain access outside view init, keeping every target of a multi-platform project building, and reading test output correctly.

It deliberately does not restate Apple's own guidance. Where the two overlap, Apple wins.

bin/export-apple-skills.sh — Xcode ships its own skills, written by the framework teams. They are Apple's material, so this repository carries a script to export them rather than a copy of them. Everyone exports from the Xcode they have, which keeps the guidance matched to their SDK.

bin/export-apple-skills.sh .claude/skills

Xcode must be running or the export hangs.

Install

/plugin marketplace add https://git.pda.cz/PDAT/claude-plugins.git
/plugin install pdat-swift-practice@pdat

The repository is public, so the HTTPS URL clones without credentials. Use it rather than the SSH one: /plugin marketplace add rejects an ssh://host:port/... URL, and SSH's shorter git@host:path form has nowhere to put our non-standard port 2222. Pushing here still goes over SSH as usual.

Install at user scope and it applies to every project, including ones that do not exist yet.

To hand it to a team through a repository instead, put this in that project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "pdat": {
      "source": { "source": "url", "url": "https://git.pda.cz/PDAT/claude-plugins.git" }
    }
  },
  "enabledPlugins": { "pdat-swift-practice@pdat": true }
}

The git-based source types are github, url and git-subdir; there is no git type. For a self-hosted host, url is the one.

Anyone who clones that project gets the skill without installing anything.

Updating

Push a change, bump version in both .claude-plugin/marketplace.json and pdat-swift-practice/.claude-plugin/plugin.json, then /plugin marketplace update locally. Without the version bump, installs will not notice.

Sourcing

apple-findings collects other people's discoveries, so it follows rules that keep it honest and lawful:

• Write the entry yourself. An API signature is a fact and facts are free to restate. The paragraph explaining it is the author's work, and crediting them does not make copying it acceptable — attribution answers plagiarism, not copyright.
• Name the source — author, title, publication, date — and link it. Partly courtesy, partly so a stale entry can be checked against the original later.
• Say what it replaces in our code. This is the half no external article can write, and the reason the file is worth keeping at all.
• Prefer the vendor's own material where it exists. When Apple's shipped skills cover the same API, defer to them and keep only the "what of ours does this replace" note.

Adding to xcode-practice

The bar is deliberately high: something that actually went wrong, more than once, and whose fix is not obvious from the framework documentation. A rule nobody has been burned by is a rule nobody will follow.