swift-code-reviewer-skill 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to the Swift Code Reviewer Agent Skill will be documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-04-10
+
+### Added
+
+- **`init` command**: Scaffold review agent + `/review` slash command into any project via `npx swift-code-reviewer-skill init`
+- **templates/ directory**: Bundled agent (`swift-code-reviewer.md`) and command (`review.md`) templates
+- `setup` alias for `init` in both installers
+- `npx skills add` as primary installation method in README
+
+### Changed
+
+- README rewritten with `npx skills add` as primary install, `init` as step 2
+- `install-skill.sh` and `bin/install.js` now show `init` hint after install
+- Post-install message updated to guide users toward project scaffolding
+
 ## [1.1.1] - 2026-03-24
 
 ### Fixed
@@ -210,6 +225,7 @@ Provided complete examples for:
 
 ## Version History Summary
 
+- **1.2.0** (2026-04-10): Add `init` command with agent + /review scaffolding, `npx skills` as primary install
 - **1.1.1** (2026-03-24): Fix incorrect `install-skill.sh` (was XcodeBuildMCP installer)
 - **1.1.0** (2026-03-16): Increase adjusts from Dimillian skill and more scenarios to cover
 - **1.0.0** (2026-02-10): Initial release with comprehensive review capabilities

package/README.md

@@ -7,19 +7,43 @@ A code review skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-
 
 ## Quick Start
 
+### 1. Install the skill (global, once)
+
 ```bash
-npx swift-code-reviewer-skill
+npx skills add Viniciuscarvalho/swift-code-reviewer-skill
+```
+
+### 2. Add the review agent to your project (optional)
+
+```bash
+cd ~/Projects/YourApp
+npx swift-code-reviewer-skill init
 ```
 
-That's it. The skill is installed and ready to use. Run it again anytime to update to the latest version.
+This scaffolds two files into your project:
+
+```
+.claude/
+  agents/swift-code-reviewer.md   # review agent
+  commands/review.md              # /review slash command
+```
+
+Existing files are never overwritten.
+
+### The review flow
+
+```
+You code  -->  /review before push (free, local)  -->  done
+```
 
-> No cloning, no manual setup. NPX always fetches the latest version automatically.
+- `/review` runs the full review checklist against your staged or unstaged Swift changes
+- `@swift-code-reviewer` invokes the agent directly for deeper analysis
 
 ## Usage
 
 ![Swift Code Reviewer in action](assets/demo.png)
 
-Just ask Claude to review your code:
+Ask Claude to review your code:
 
 ```
 Review this PR
@@ -29,6 +53,12 @@ Review all ViewModels in the Features folder
 Check if this follows our coding standards
 ```
 
+Or use the slash command after running `init`:
+
+```
+/review
+```
+
 The skill automatically activates, reads your `.claude/CLAUDE.md` for project standards, and generates a structured report with severity levels, code examples, and prioritized action items.
 
 ### Example Output
@@ -42,11 +72,11 @@ The skill automatically activates, reads your `.claude/CLAUDE.md` for project st
 
 ## File: LoginViewModel.swift
 
-✅ **Excellent Modern API Usage** (line 12)
+Pass **Excellent Modern API Usage** (line 12)
 
 - Using @Observable instead of ObservableObject
 
-🟡 **Force Unwrap Detected** (line 89)
+Issue **Force Unwrap Detected** (line 89)
 Current: `let user = repository.currentUser!`
 Fix:
 guard let user = repository.currentUser else {
@@ -54,7 +84,7 @@ logger.error("No current user")
 return
 }
 
-🔴 **Violates Design System Standard** (line 45)
+Issue **Violates Design System Standard** (line 45)
 Current: `.foregroundColor(.blue)`
 Fix: `.foregroundColor(AppColors.primary)`
 
@@ -77,12 +107,12 @@ Fix: `.foregroundColor(AppColors.primary)`
 
 ### Severity Levels
 
-| Icon | Severity | Action                  |
-| ---- | -------- | ----------------------- |
-| 🔴   | Critical | Must fix before merge   |
-| 🟡   | High     | Should fix before merge |
-| 🟠   | Medium   | Fix in current sprint   |
-| 🔵   | Low      | Consider for future     |
+| Icon     | Severity | Action                  |
+| -------- | -------- | ----------------------- |
+| Critical | Critical | Must fix before merge   |
+| High     | High     | Should fix before merge |
+| Medium   | Medium   | Fix in current sprint   |
+| Low      | Low      | Consider for future     |
 
 ## Platform Support
 
@@ -116,23 +146,21 @@ Add a `.claude/CLAUDE.md` to your project and the skill will validate against yo
 ## Alternative Installation
 
 <details>
-<summary>Clone this repository</summary>
+<summary>NPX installer (installs skill only)</summary>
 
 ```bash
-git clone https://github.com/Viniciuscarvalho/swift-code-reviewer-skill.git ~/.claude/skills/swift-code-reviewer-skill
+npx swift-code-reviewer-skill
 ```
 
 </details>
 
 <details>
-<summary>Manual installation</summary>
+<summary>Clone this repository</summary>
 
 ```bash
-mkdir -p ~/.claude/skills/swift-code-reviewer-skill/references
+git clone https://github.com/Viniciuscarvalho/swift-code-reviewer-skill.git ~/.claude/skills/swift-code-reviewer-skill
 ```
 
-Download the files from this repository into the directory, then restart Claude.
-
 </details>
 
 <details>
@@ -152,8 +180,9 @@ This skill optionally leverages **swift-best-practices**, **swiftui-expert-skill
 
 1. Edit `SKILL.md` for main skill logic
 2. Update reference files in `references/` for specific checklists
-3. Test with real Swift/SwiftUI code
-4. Submit a pull request
+3. Add/modify templates in `templates/` for agent and command scaffolding
+4. Test with real Swift/SwiftUI code
+5. Submit a pull request
 
 ## License
 
@@ -161,7 +190,7 @@ MIT License - See [LICENSE](LICENSE) file for details.
 
 ---
 
-**Made with ❤️ for the Swift community**
+**Made with care for the Swift community**
 
 If this skill helps your code reviews, please star the repository!
 

package/SKILL.md

@@ -1,6 +1,23 @@
 ---
 name: swift-code-reviewer
-description: Perform thorough code reviews for Swift/SwiftUI code, analyzing code quality, architecture, performance, security, and adherence to Swift 6+ best practices, SwiftUI patterns, navigation architecture, sheet routing, theming, async state, iOS/macOS platform guidelines, and project-specific coding standards from .claude/CLAUDE.md. Use when reviewing code changes, performing quality audits, or providing structured feedback on Swift codebases with all severity levels and positive feedback.
+description: >
+  Multi-layer code review agent for Swift and SwiftUI projects. Analyzes PRs,
+  diffs, and files across six dimensions: Swift 6+ concurrency safety, SwiftUI
+  state management and modern APIs, performance (view updates, ForEach identity,
+  lazy loading), security (force unwraps, Keychain, input validation), architecture
+  compliance (MVVM/MVI/TCA, dependency injection), and project-specific standards
+  from .claude/CLAUDE.md. Outputs structured reports with Critical/High/Medium/Low
+  severity, positive feedback, and prioritized action items with file:line
+  references and before/after code examples.
+
+  ALWAYS use this skill when the user says "review this PR", "review my code",
+  "review my changes", "check this file", "code review", "review against our
+  standards", "audit this codebase", "check code quality", mentions reviewing
+  any .swift file, asks about Swift best practices violations in existing code,
+  or wants feedback on Swift/SwiftUI code — even if they don't explicitly say
+  "code review". Also trigger when the user asks to "check if this follows our
+  coding standards", "review uncommitted changes", "review all ViewModels",
+  or mentions reviewing navigation, sheets, theming, or async patterns in Swift.
 ---
 
 # Swift/SwiftUI Code Review Skill
@@ -775,6 +792,6 @@ For runtime analysis, recommend using Instruments or other profiling tools.
 
 ## Version
 
-**Version**: 1.1.1
-**Last Updated**: 2026-03-16
+**Version**: 1.2.0
+**Last Updated**: 2026-04-10
 **Compatible with**: Swift 6+, SwiftUI (iOS 17+, macOS 14+, watchOS 10+, tvOS 17+, visionOS 1+)

package/bin/install.js

@@ -38,16 +38,7 @@ function copyRecursive(src, dest) {
   }
 }
 
-function install() {
-  log('\n  Swift Code Reviewer Skill Installer', colors.cyan + colors.bright);
-  log('  ====================================\n', colors.cyan);
-
-  // Determine paths
-  const homeDir = os.homedir();
-  const skillsDir = path.join(homeDir, '.claude', 'skills');
-  const targetDir = path.join(skillsDir, SKILL_NAME);
-
-  // Find package root (where SKILL.md is located)
+function findPackageRoot() {
   let packageRoot = __dirname;
   while (!fs.existsSync(path.join(packageRoot, 'SKILL.md'))) {
     const parent = path.dirname(packageRoot);
@@ -57,14 +48,23 @@ function install() {
     }
     packageRoot = parent;
   }
+  return packageRoot;
+}
+
+function install() {
+  log('\n  Swift Code Reviewer Skill Installer', colors.cyan + colors.bright);
+  log('  ====================================\n', colors.cyan);
+
+  const homeDir = os.homedir();
+  const skillsDir = path.join(homeDir, '.claude', 'skills');
+  const targetDir = path.join(skillsDir, SKILL_NAME);
+  const packageRoot = findPackageRoot();
 
-  // Check if Claude Code skills directory exists
   if (!fs.existsSync(skillsDir)) {
     log(`  Creating skills directory: ${skillsDir}`, colors.yellow);
     fs.mkdirSync(skillsDir, { recursive: true });
   }
 
-  // Check for existing installation
   if (fs.existsSync(targetDir)) {
     log(`  Updating existing installation at:`, colors.yellow);
     log(`  ${targetDir}\n`, colors.yellow);
@@ -74,10 +74,8 @@ function install() {
     log(`  ${targetDir}\n`, colors.blue);
   }
 
-  // Create target directory
   fs.mkdirSync(targetDir, { recursive: true });
 
-  // Files to copy
   const filesToCopy = [
     'SKILL.md',
     'README.md',
@@ -86,10 +84,8 @@ function install() {
     'CHANGELOG.md'
   ];
 
-  // Directories to copy
   const dirsToCopy = ['references'];
 
-  // Copy files
   for (const file of filesToCopy) {
     const src = path.join(packageRoot, file);
     const dest = path.join(targetDir, file);
@@ -100,7 +96,6 @@ function install() {
     }
   }
 
-  // Copy directories
   for (const dir of dirsToCopy) {
     const src = path.join(packageRoot, dir);
     const dest = path.join(targetDir, dir);
@@ -111,10 +106,11 @@ function install() {
     }
   }
 
-  // Success message
   log('\n  Installation complete!', colors.green + colors.bright);
   log('\n  The skill is now available in Claude Code.', colors.reset);
-  log('  Use it by asking Claude to:', colors.reset);
+  log('  To add the review agent and /review command to a project, run:', colors.reset);
+  log('\n    npx swift-code-reviewer-skill init\n', colors.cyan);
+  log('  Or use it directly by asking Claude to:', colors.reset);
   log('\n    - "Review this PR"', colors.cyan);
   log('    - "Review LoginView.swift"', colors.cyan);
   log('    - "Review my uncommitted changes"', colors.cyan);
@@ -124,6 +120,69 @@ function install() {
   log('  Documentation: https://github.com/Viniciuscarvalho/swift-code-reviewer-skill\n', colors.blue);
 }
 
+function init() {
+  log('\n  Swift Code Reviewer — Project Setup', colors.cyan + colors.bright);
+  log('  =====================================\n', colors.cyan);
+
+  const packageRoot = findPackageRoot();
+  const cwd = process.cwd();
+
+  // Verify we're in a git repo (likely a real project)
+  if (!fs.existsSync(path.join(cwd, '.git'))) {
+    log('  Warning: Not a git repository. Running anyway.\n', colors.yellow);
+  }
+
+  const claudeDir = path.join(cwd, '.claude');
+  const agentsDir = path.join(claudeDir, 'agents');
+  const commandsDir = path.join(claudeDir, 'commands');
+
+  const templateAgentSrc = path.join(packageRoot, 'templates', 'agents', 'swift-code-reviewer.md');
+  const templateCommandSrc = path.join(packageRoot, 'templates', 'commands', 'review.md');
+
+  // Check templates exist
+  if (!fs.existsSync(templateAgentSrc)) {
+    log('  Error: Agent template not found. Reinstall the skill with:', colors.red);
+    log('    npx swift-code-reviewer-skill\n', colors.cyan);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(agentsDir, { recursive: true });
+  fs.mkdirSync(commandsDir, { recursive: true });
+
+  let created = 0;
+  let skipped = 0;
+
+  // Copy agent
+  const agentDest = path.join(agentsDir, 'swift-code-reviewer.md');
+  if (fs.existsSync(agentDest)) {
+    log('  Skipped: .claude/agents/swift-code-reviewer.md (already exists)', colors.yellow);
+    skipped++;
+  } else {
+    fs.copyFileSync(templateAgentSrc, agentDest);
+    log('  Created: .claude/agents/swift-code-reviewer.md', colors.green);
+    created++;
+  }
+
+  // Copy command
+  const commandDest = path.join(commandsDir, 'review.md');
+  if (fs.existsSync(commandDest)) {
+    log('  Skipped: .claude/commands/review.md (already exists)', colors.yellow);
+    skipped++;
+  } else {
+    fs.copyFileSync(templateCommandSrc, commandDest);
+    log('  Created: .claude/commands/review.md', colors.green);
+    created++;
+  }
+
+  log(`\n  Done! ${created} file(s) created, ${skipped} skipped.`, colors.green + colors.bright);
+
+  if (created > 0) {
+    log('\n  Usage:', colors.reset);
+    log('    /review          — run a full code review before pushing', colors.cyan);
+    log('    @swift-code-reviewer — invoke the agent directly\n', colors.cyan);
+  }
+}
+
 function uninstall() {
   log('\n  Uninstalling Swift Code Reviewer Skill', colors.yellow + colors.bright);
   log('  ======================================\n', colors.yellow);
@@ -146,11 +205,13 @@ function showHelp() {
   log('  Usage: npx swift-code-reviewer-skill [command]\n', colors.reset);
   log('  Commands:', colors.bright);
   log('    (none)     Install the skill to ~/.claude/skills/', colors.reset);
+  log('    init       Scaffold agent + /review command into current project', colors.reset);
   log('    uninstall  Remove the skill from ~/.claude/skills/', colors.reset);
   log('    help       Show this help message\n', colors.reset);
   log('  Examples:', colors.bright);
-  log('    npx swift-code-reviewer-skill', colors.cyan);
-  log('    npx swift-code-reviewer-skill uninstall\n', colors.cyan);
+  log('    npx swift-code-reviewer-skill              # install skill globally', colors.cyan);
+  log('    npx swift-code-reviewer-skill init          # add agent + command to project', colors.cyan);
+  log('    npx swift-code-reviewer-skill uninstall     # remove skill\n', colors.cyan);
 }
 
 // Parse command line arguments
@@ -158,6 +219,10 @@ const args = process.argv.slice(2);
 const command = args[0];
 
 switch (command) {
+  case 'init':
+  case 'setup':
+    init();
+    break;
   case 'uninstall':
   case 'remove':
     uninstall();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swift-code-reviewer-skill",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Claude Code skill for comprehensive Swift/SwiftUI code reviews with multi-layer analysis",
   "keywords": [
     "claude",
@@ -9,9 +9,21 @@
     "swift",
     "swiftui",
     "code-review",
+    "code-quality",
+    "architecture-review",
+    "performance-audit",
+    "security-analysis",
+    "swift-6",
+    "async-await",
+    "sendable",
+    "concurrency",
     "ios",
     "macos",
-    "apple"
+    "apple",
+    "dependency-injection",
+    "testing",
+    "accessibility",
+    "best-practices"
   ],
   "author": "Vinicius Carvalho",
   "license": "MIT",
@@ -29,6 +41,7 @@
   "files": [
     "bin/",
     "references/",
+    "templates/",
     "SKILL.md",
     "README.md",
     "LICENSE",

package/templates/agents/swift-code-reviewer.md

@@ -0,0 +1,78 @@
+# Swift Code Review Agent
+
+You are a senior Swift/SwiftUI code reviewer. Your job is to review code changes before they are pushed to the remote repository.
+
+## Skills
+
+Load and follow the rules from `~/.claude/skills/swift-code-reviewer-skill/SKILL.md` and all files in its `references/` directory.
+
+## Workflow
+
+When invoked, execute these steps in order:
+
+### 1. Collect the diff
+
+```bash
+git diff --staged -- '*.swift'
+```
+
+If nothing is staged, fall back to:
+
+```bash
+git diff HEAD -- '*.swift'
+```
+
+If still empty, tell the user there are no Swift changes to review.
+
+### 2. Run SwiftLint (if available)
+
+```bash
+if command -v swiftlint &>/dev/null; then
+  swiftlint lint --config .swiftlint.yml --quiet 2>/dev/null || swiftlint lint --quiet
+fi
+```
+
+Collect any warnings or errors. If SwiftLint is not installed, skip and note it.
+
+### 3. Review
+
+Analyze the diff using the swift-code-reviewer-skill rules. Focus on:
+
+- **Architecture**: MVVM compliance, separation of concerns, dependency injection
+- **SwiftUI**: proper use of @State/@Binding/@Observable, view composition, performance
+- **Safety**: force unwraps, force casts, retain cycles, unhandled optionals
+- **Naming**: clarity, Swift API Design Guidelines compliance
+- **Concurrency**: proper async/await, MainActor usage, data races
+- **Tests**: coverage gaps for new/changed logic
+
+### 4. Output format
+
+```markdown
+## Summary
+
+<what changed in 1-2 sentences>
+
+## Issues
+
+<list issues with file:line, grouped by severity>
+
+## SwiftLint
+
+<summarize lint findings or "Clean">
+
+## Suggestions
+
+<actionable improvements>
+
+## Verdict
+
+Ready to push | Fix warnings first | Do not push
+```
+
+### 5. Rules
+
+- Be direct. No filler, no praise for basic competence.
+- Every issue must include the file and line number.
+- If the diff is clean, say so — don't invent problems.
+- Prioritize issues that would break production or cause bugs.
+- Ignore generated files, Pods, and third-party code.

package/templates/commands/review.md

@@ -0,0 +1,56 @@
+# /review — Swift Code Review
+
+Use the agent defined in .claude/agents/swift-code-reviewer.md as your primary review rules. Combine its skill-based analysis with the checklist below.
+
+Run the full code review checklist against current Swift changes.
+
+## Behavior
+
+When invoked:
+
+1. **Identify changed files** — use `git diff --name-only` (staged + unstaged), filter to `*.swift`.
+2. **Load CLAUDE.md** — read project conventions if `.claude/CLAUDE.md` exists.
+3. **Run SwiftLint** — if available, collect warnings/errors.
+4. **Run the universal checklist** against the diff.
+5. **Run Swift-specific checks** using the swift-code-reviewer-skill rules.
+6. **Run CLAUDE.md-specific checks** — any custom rules defined in the project.
+7. **Report findings** using the signal system.
+
+## Output Format
+
+```
+Code Review — [N files changed]
+
+Universal:
+  Pass  Naming: consistent with project conventions
+  Pass  Error handling: all errors handled
+  Issue Edge case: `processItems` doesn't handle empty array
+  Suggestion Complexity: `calculateTotal` could extract tax logic
+
+Swift/SwiftUI:
+  Pass  No force unwraps
+  Issue Retain cycle: closure in `fetchData` captures self strongly
+  Pass  Accessibility labels present
+
+CLAUDE.md:
+  Convention Line 23: uses `if let` but CLAUDE.md requires `guard let` for early returns
+  Pass  Architecture: follows MVVM pattern
+
+Result: 2 issues to fix, 1 suggestion
+```
+
+## Signal Words
+
+| Signal         | Meaning                            |
+| -------------- | ---------------------------------- |
+| **Pass**       | Item satisfied                     |
+| **Suggestion** | Optional improvement, non-blocking |
+| **Issue**      | Must be fixed before commit        |
+| **Convention** | Violation from CLAUDE.md           |
+
+## Important
+
+- Only flag items relevant to actual changes, not the entire codebase
+- One line per item — be thorough but concise
+- After listing issues, offer to help fix them
+- If no issues found, confirm with a clean summary