AI agent skill · by @Shpigford

Setup

Get a new developer up and running with the Chops codebase — prerequisites, build, architecture, and common tasks.

Archived 2026-10-23 · Source updated 2026-08-23. Check the original repository for the latest version.

SKILL.md instructions

Set up the Chops development environment and orient a new contributor to the codebase.

## Instructions

### Step 1: Check prerequisites

Verify these are installed. If any are missing, tell the user what to install and stop.

1. **macOS 15+** — `sw_vers -productVersion` (must be ≥ 15.0)
2. **Xcode CLI tools** — `xcode-select -p` (if missing: `xcode-select --install`)
3. **Homebrew** — `which brew` (if missing: direct them to https://brew.sh)
4. **xcodegen** — `which xcodegen` (if missing: `brew install xcodegen`)

### Step 2: Generate Xcode project

```bash
xcodegen generate
```

This reads `project.yml` (the source of truth for all Xcode project settings) and generates `Chops.xcodeproj`. Re-run this anytime `project.yml` changes. Never edit the `.xcodeproj` directly.

### Step 3: Build and run

```bash
xcodebuild -scheme Chops -configuration Debug build
```

Or open in Xcode and hit Cmd+R:

```bash
open Chops.xcodeproj
```

### Step 4: Orient the developer

Share this architecture overview:

**Entry point:** `Chops/App/ChopsApp.swift` — sets up SwiftData ModelContainer (Skill + SkillCollection), starts Sparkle updater, injects AppState into environment.

**State:** `Chops/App/AppState.swift` — `@Observable` singleton holding UI state (selected tool, selected skill, search text, sidebar filter).

**Models (SwiftData):**
- `Chops/Models/Skill.swift` — a discovered skill file, uniquely identified by resolved symlink path
- `Chops/Models/Collection.swift` — user-created groupings of skills
- `Chops/Models/ToolSource.swift` — enum of supported tools with display names, icons, colors, and filesystem paths

**Services:**
- `Chops/Services/SkillScanner.swift` — probes tool directories, parses frontmatter, upserts into SwiftData. Deduplicates via resolved symlink paths.
- `Chops/Services/FileWatcher.swift` — FSEvents via DispatchSource, triggers re-scan on file changes
- `Chops/Services/SkillParser.swift` — dispatches to FrontmatterParser (.md) or MDCParser (.mdc)
- `Chops/Services/SearchService.swift` — in-memory full-text search

**Views:** Three-column NavigationSplitView (Sidebar → List → Detail). Editor wraps NSTextView for native text editing. Cmd+S save via FocusedValues.

**Key design decisions:**
- No sandbox — the app needs unrestricted filesystem access to read dotfiles across ~/
- Symlink dedup — same file in multiple tool dirs shows as one skill with multiple tool badges
- No test suite — validate manually by building, running, and observing

**Scanned tool paths:**

| Tool | Paths |
|------|-------|
| Claude Code | `~/.claude/skills/`, `~/.agents/skills` |
| Cursor | `~/.cursor/skills/`, `~/.cursor/rules` |
| Windsurf | `~/.codeium/windsurf/memories/`, `~/.windsurf/rules` |
| Codex | `~/.codex` |
| Amp | `~/.config/amp` |

Copilot and Aider detect project-level skills only (no global paths).

## Common tasks to be aware of

**Add a new tool:** Add a case to `ToolSource` enum in `Chops/Models/ToolSource.swift`. Fill in `displayName`, `iconName`, `color`, `globalPaths`. Update `SkillScanner` if the tool uses a non-standard file layout.

**Modify parsing:** Frontmatter → `Chops/Utilities/FrontmatterParser.swift`. Cursor .mdc → `Chops/Utilities/MDCParser.swift`. Dispatch logic → `Chops/Services/SkillParser.swift`.

**Change UI:** Views are in `Chops/Views/` (Sidebar/, Detail/, Settings/, Shared/). Main layout is `Chops/App/ContentView.swift`.

## Important Rules

- `project.yml` is the source of truth for Xcode settings — never edit `.xcodeproj` directly
- Sparkle (auto-updates) is the only external dependency — pulled automatically via SPM
- There is no test suite — always validate changes by building and running the app manually
- The app runs without sandbox — this is intentional and required