diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8fcda80..f5c5b94 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", "name": "swift-testing-agent-skill", - "version": "1.2.0", + "version": "1.3.0", "owner": { "name": "Antoine van der Lee", "email": "contact@avanderlee.com" @@ -14,7 +14,7 @@ "name": "swift-testing-expert", "description": "Expert Swift Testing guidance for #expect/#require macros, traits and tags, parameterized tests, async testing patterns, parallel execution, and XCTest migration workflows.", "repository": "https://github.com/AvdLee/Swift-Testing-Agent-Skill", - "version": "1.2.0", + "version": "1.3.0", "author": { "name": "Antoine van der Lee", "email": "contact@avanderlee.com" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 3bcfff4..997b3d0 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "swift-testing-expert", - "version": "1.2.0", + "version": "1.3.0", "description": "Expert Swift Testing guidance for test structure, #expect/#require usage, traits and tags, parameterized tests, async waiting patterns, parallel execution, and XCTest migration.", "author": { "name": "Antoine van der Lee", @@ -25,6 +25,6 @@ "apple" ], "skills": [ - "./swift-testing-expert" + "./skills/swift-testing-expert" ] } diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json new file mode 100644 index 0000000..28b3337 --- /dev/null +++ b/.cursor-plugin/plugin.json @@ -0,0 +1,32 @@ +{ + "name": "swift-testing-expert", + "version": "1.3.0", + "description": "Expert Swift Testing guidance for test structure, #expect/#require usage, traits and tags, parameterized tests, async waiting patterns, parallel execution, and XCTest migration.", + "author": { + "name": "Antoine van der Lee", + "email": "contact@avanderlee.com" + }, + "homepage": "https://github.com/AvdLee/Swift-Testing-Agent-Skill", + "repository": "https://github.com/AvdLee/Swift-Testing-Agent-Skill", + "license": "MIT", + "logo": "skills/swift-testing-expert/assets/logo.png", + "keywords": [ + "swift", + "swift-testing", + "testing", + "xctest", + "unit-testing", + "parameterized-tests", + "traits", + "tags", + "parallel-testing", + "async-await", + "xcode", + "ios", + "macos", + "apple" + ], + "skills": [ + "skills/swift-testing-expert" + ] +} diff --git a/.github/scripts/sync-readme.js b/.github/scripts/sync-readme.js index 524cfba..50bb051 100644 --- a/.github/scripts/sync-readme.js +++ b/.github/scripts/sync-readme.js @@ -33,7 +33,7 @@ const referenceFiles = fs const lines = []; lines.push("```text"); -lines.push("swift-testing-expert/"); +lines.push("skills/swift-testing-expert/"); lines.push(" SKILL.md"); lines.push(" references/"); diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 91c91ea..2af92a6 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -68,17 +68,21 @@ jobs: exit 1 fi - - name: Bump plugin.json version + - name: Bump manifest versions run: | set -euo pipefail - jq --arg v "$VERSION" '.version = $v' .claude-plugin/plugin.json > .claude-plugin/plugin.json.tmp - if [ -s .claude-plugin/plugin.json.tmp ]; then - mv .claude-plugin/plugin.json.tmp .claude-plugin/plugin.json - else - echo "Error: Failed to generate updated .claude-plugin/plugin.json" - exit 1 - fi + for manifest in plugin.json .claude-plugin/plugin.json .cursor-plugin/plugin.json; do + jq --arg v "$VERSION" '.version = $v' "$manifest" > "$manifest.tmp" + if [ -s "$manifest.tmp" ]; then + mv "$manifest.tmp" "$manifest" + else + echo "Error: Failed to generate updated $manifest" + exit 1 + fi + done + + sed -i -E "s/^version: \".*\"$/version: \"$VERSION\"/" agents/openai.yaml - name: Bump marketplace.json versions run: | @@ -96,7 +100,8 @@ jobs: run: | set -euo pipefail - if git diff --quiet .claude-plugin/plugin.json .claude-plugin/marketplace.json; then + version_files="plugin.json .claude-plugin/plugin.json .claude-plugin/marketplace.json .cursor-plugin/plugin.json agents/openai.yaml" + if git diff --quiet $version_files; then echo "Error: No changes detected after version bump. Is the repo already at version $VERSION?" exit 1 fi diff --git a/.github/workflows/sync-readme-references.yml b/.github/workflows/sync-readme-references.yml index 2846549..0c688a0 100644 --- a/.github/workflows/sync-readme-references.yml +++ b/.github/workflows/sync-readme-references.yml @@ -3,7 +3,7 @@ name: Sync README reference structure on: pull_request: paths: - - "swift-testing-expert/references/**" + - "skills/swift-testing-expert/references/**" jobs: sync-readme: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34fcd89..bb35cda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,7 +18,7 @@ If you use the `skill-creator` skill, you can: ## Alternative Workflows ### Without skill-creator -- Make changes directly in `SKILL.md` or `swift-testing-expert/references/` +- Make changes directly in `SKILL.md` or `skills/swift-testing-expert/references/` - Keep content concise and focused on Swift Testing ### Manual edits @@ -40,7 +40,7 @@ If you use the `skill-creator` skill, you can: - Avoid broad IDE/tooling walkthroughs beyond essential workflow context - Use modern Swift Testing APIs and flag outdated XCTest-only patterns when relevant - Prefer clear, direct language over opinionated phrasing -- Keep `SKILL.md` concise; place detailed examples in `swift-testing-expert/references/` +- Keep `SKILL.md` concise; place detailed examples in `skills/swift-testing-expert/references/` ## Pull Request Process diff --git a/README.md b/README.md index 746b54d..ad6e3b0 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ Expert guidance for any AI coding tool that supports the [Agent Skills open form This repository distills practical Swift Testing best practices into actionable, concise references for agents and code review workflows. +This repository is packaged as a portable [Agent Plugin](https://agent-plugins.org) (spec 1.0.0): compatible clients discover the skill automatically from the root `plugin.json` manifest and the `skills/` directory. Client-specific manifests for Claude Code, Cursor, Codex, and pi are included as well. + ## Who this is for - Teams adopting Swift Testing who want quick, correct defaults - Developers migrating existing XCTest suites incrementally @@ -20,11 +22,13 @@ This repository distills practical Swift Testing best practices into actionable, Install this skill with a single command: ```bash -npx skills add https://github.com/avdlee/swift-testing-agent-skill --skill swift-testing-expert +npx skills@latest add https://github.com/avdlee/swift-testing-agent-skill --skill swift-testing-expert ``` For more information, visit the [skills.sh platform page](https://skills.sh/avdlee/swift-testing-agent-skill/swift-testing-expert). +> Installed before the Agent Plugins migration? Run `npx skills@latest update` using skills CLI 1.5.24 or newer. It migrates the saved skill path without treating the skill as deleted. + Then use the skill in your AI agent, for example: > Use the swift testing skill and review this test target for migration opportunities and flaky parallel behavior. @@ -75,11 +79,17 @@ To automatically provide this Skill to everyone working in a repository, configu When team members open the project, Claude Code will prompt them to install the Skill. -### Option C: Manual install +### Option C: Cursor Plugin + +Load the plugin from a local clone by placing it in `~/.cursor/plugins/local`, or install it from the Cursor Marketplace once listed. Cursor supports both the portable Agent Plugins manifest (`plugin.json`) and the Cursor Plugin manifest (`.cursor-plugin/plugin.json`) included in this repository. + +### Option D: Manual install 1) **Clone** this repository. -2) **Install or symlink** the `swift-testing-expert/` folder following your tool's official skills installation docs (see links below). +2) **Install or symlink** the `skills/swift-testing-expert/` folder following your tool's official skills installation docs (see links below). 3) **Use your AI tool** as usual and ask it to use the "swift-testing-expert" skill for Swift Testing tasks. +> Note: the skill folder moved from the repository root to `skills/swift-testing-expert/` when adopting the Agent Plugins format. A symlink at the old `swift-testing-expert/` path keeps existing local clones and scripts working; it will be removed in the next major version. + #### Where to Save Skills Follow your tool's official documentation, here are a few popular ones: - **Codex:** [Where to save skills](https://developers.openai.com/codex/skills/#where-to-save-skills) @@ -88,7 +98,7 @@ Follow your tool's official documentation, here are a few popular ones: **How to verify**: -Your agent should reference the routing/playbook in `swift-testing-expert/SKILL.md` and jump into the relevant file in `swift-testing-expert/references/`. +Your agent should reference the routing/playbook in `skills/swift-testing-expert/SKILL.md` and jump into the relevant file in `skills/swift-testing-expert/references/`. ## What This Skill Offers @@ -132,19 +142,19 @@ This skill gives your AI coding tool practical Swift Testing guidance. It can: ```text -swift-testing-expert/ - SKILL.md - references/ - _index.md - async-testing-and-waiting.md - Async waiting, continuations, and callback-event testing - expectations.md - #expect, #require, throw checks, and known issues - fundamentals.md - @Test, suites, structure, and naming patterns - migration-from-xctest.md - Incremental XCTest coexistence and migration strategy - parallelization-and-isolation.md - Parallel defaults, randomized order, and .serialized usage - parameterized-testing.md - Single/multi-argument tests, zip pairing, and scaling - performance-and-best-practices.md - High-signal testing defaults for speed, determinism, and flakiness prevention - traits-and-tags.md - Traits, tags, conditions, bug links, and test-plan filtering - xcode-workflows.md - Test navigator/report workflows and diagnostics practices +skills/swift-testing-expert/ + SKILL.md + references/ + _index.md + async-testing-and-waiting.md - Async waiting, continuations, and callback-event testing + expectations.md - #expect, #require, throw checks, and known issues + fundamentals.md - @Test, suites, structure, and naming patterns + migration-from-xctest.md - Incremental XCTest coexistence and migration strategy + parallelization-and-isolation.md - Parallel defaults, randomized order, and .serialized usage + parameterized-testing.md - Single/multi-argument tests, zip pairing, and scaling + performance-and-best-practices.md - High-signal testing defaults for speed, determinism, and flakiness prevention + traits-and-tags.md - Traits, tags, conditions, bug links, and test-plan filtering + xcode-workflows.md - Test navigator/report workflows and diagnostics practices ``` diff --git a/agents/openai.yaml b/agents/openai.yaml new file mode 100644 index 0000000..0ea5ed4 --- /dev/null +++ b/agents/openai.yaml @@ -0,0 +1,24 @@ +name: swift-testing-expert +version: "1.3.0" +description: >- + Expert Swift Testing guidance for test structure, #expect/#require usage, + traits and tags, parameterized tests, async waiting patterns, parallel + execution, and XCTest migration. +author: + name: Antoine van der Lee + email: contact@avanderlee.com +repository: https://github.com/AvdLee/Swift-Testing-Agent-Skill +license: MIT +logo: skills/swift-testing-expert/assets/logo.png +keywords: + - swift + - swift-testing + - testing + - xctest + - parameterized-tests + - parallel-testing + - xcode + - ios + - macos +skills: + - skills/swift-testing-expert diff --git a/package.json b/package.json new file mode 100644 index 0000000..a2731bf --- /dev/null +++ b/package.json @@ -0,0 +1,6 @@ +{ + "keywords": ["pi-package"], + "pi": { + "skills": ["./skills/swift-testing-expert"] + } +} diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000..2ff83c1 --- /dev/null +++ b/plugin.json @@ -0,0 +1,30 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "swift-testing-expert", + "version": "1.3.0", + "description": "Expert Swift Testing guidance for test structure, #expect/#require usage, traits and tags, parameterized tests, async waiting patterns, parallel execution, and XCTest migration.", + "author": { + "name": "Antoine van der Lee", + "email": "contact@avanderlee.com", + "url": "https://www.avanderlee.com" + }, + "homepage": "https://github.com/AvdLee/Swift-Testing-Agent-Skill", + "repository": "https://github.com/AvdLee/Swift-Testing-Agent-Skill", + "license": "MIT", + "keywords": [ + "swift", + "swift-testing", + "testing", + "xctest", + "unit-testing", + "parameterized-tests", + "traits", + "tags", + "parallel-testing", + "async-await", + "xcode", + "ios", + "macos", + "apple" + ] +} diff --git a/swift-testing-expert/SKILL.md b/skills/swift-testing-expert/SKILL.md similarity index 100% rename from swift-testing-expert/SKILL.md rename to skills/swift-testing-expert/SKILL.md diff --git a/skills/swift-testing-expert/agents/openai.yaml b/skills/swift-testing-expert/agents/openai.yaml new file mode 100644 index 0000000..f6b1e9d --- /dev/null +++ b/skills/swift-testing-expert/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Swift Testing Expert" + short_description: "Write and modernize Swift tests: #expect/#require, traits, parameterized tests, and XCTest migration." + icon_small: "./assets/logo-small.png" + icon_large: "./assets/logo.png" + brand_color: "#30D158" diff --git a/skills/swift-testing-expert/assets/logo-small.png b/skills/swift-testing-expert/assets/logo-small.png new file mode 100644 index 0000000..9f58617 Binary files /dev/null and b/skills/swift-testing-expert/assets/logo-small.png differ diff --git a/skills/swift-testing-expert/assets/logo.png b/skills/swift-testing-expert/assets/logo.png new file mode 100644 index 0000000..34cddb6 Binary files /dev/null and b/skills/swift-testing-expert/assets/logo.png differ diff --git a/swift-testing-expert/references/_index.md b/skills/swift-testing-expert/references/_index.md similarity index 100% rename from swift-testing-expert/references/_index.md rename to skills/swift-testing-expert/references/_index.md diff --git a/swift-testing-expert/references/async-testing-and-waiting.md b/skills/swift-testing-expert/references/async-testing-and-waiting.md similarity index 100% rename from swift-testing-expert/references/async-testing-and-waiting.md rename to skills/swift-testing-expert/references/async-testing-and-waiting.md diff --git a/swift-testing-expert/references/expectations.md b/skills/swift-testing-expert/references/expectations.md similarity index 100% rename from swift-testing-expert/references/expectations.md rename to skills/swift-testing-expert/references/expectations.md diff --git a/swift-testing-expert/references/fundamentals.md b/skills/swift-testing-expert/references/fundamentals.md similarity index 100% rename from swift-testing-expert/references/fundamentals.md rename to skills/swift-testing-expert/references/fundamentals.md diff --git a/swift-testing-expert/references/migration-from-xctest.md b/skills/swift-testing-expert/references/migration-from-xctest.md similarity index 100% rename from swift-testing-expert/references/migration-from-xctest.md rename to skills/swift-testing-expert/references/migration-from-xctest.md diff --git a/swift-testing-expert/references/parallelization-and-isolation.md b/skills/swift-testing-expert/references/parallelization-and-isolation.md similarity index 100% rename from swift-testing-expert/references/parallelization-and-isolation.md rename to skills/swift-testing-expert/references/parallelization-and-isolation.md diff --git a/swift-testing-expert/references/parameterized-testing.md b/skills/swift-testing-expert/references/parameterized-testing.md similarity index 100% rename from swift-testing-expert/references/parameterized-testing.md rename to skills/swift-testing-expert/references/parameterized-testing.md diff --git a/swift-testing-expert/references/performance-and-best-practices.md b/skills/swift-testing-expert/references/performance-and-best-practices.md similarity index 100% rename from swift-testing-expert/references/performance-and-best-practices.md rename to skills/swift-testing-expert/references/performance-and-best-practices.md diff --git a/swift-testing-expert/references/traits-and-tags.md b/skills/swift-testing-expert/references/traits-and-tags.md similarity index 100% rename from swift-testing-expert/references/traits-and-tags.md rename to skills/swift-testing-expert/references/traits-and-tags.md diff --git a/swift-testing-expert/references/xcode-workflows.md b/skills/swift-testing-expert/references/xcode-workflows.md similarity index 100% rename from swift-testing-expert/references/xcode-workflows.md rename to skills/swift-testing-expert/references/xcode-workflows.md diff --git a/swift-testing-expert b/swift-testing-expert new file mode 120000 index 0000000..0a2fe0f --- /dev/null +++ b/swift-testing-expert @@ -0,0 +1 @@ +skills/swift-testing-expert \ No newline at end of file