Your AI agent skills, finally organized. A macOS app to browse, edit, and manage skills across Claude Code, Cursor, Codex, Windsurf, and Amp.
docs: expand README with developer onboarding and add setup skill (#7)
Josh Pigford3c80ea81b9bd
diff --git a/.claude/skills/setup/SKILL.md b/.claude/skills/setup/SKILL.mdnew file mode 100644index 0000000..9aca63b--- /dev/null+++ b/.claude/skills/setup/SKILL.md@@ -0,0 +1,90 @@+---+name: setup+description: Get a new developer up and running with the Chops codebase — prerequisites, build, architecture, and common tasks.+---++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 requireddiff --git a/README.md b/README.mdindex ba0681a..35c022d 100644--- a/README.md+++ b/README.md@@ -27,26 +27,157 @@ One macOS app to discover, organize, and edit coding agent skills across Claude- **Full-text search** — Search across name, description, and content- **Create new skills** — Generates correct boilerplate per tool-## Requirements+## Prerequisites-- macOS 15 (Sequoia) or later+- **macOS 15** (Sequoia) or later+- **Xcode** with command-line tools (`xcode-select --install`)+- **Homebrew** ([brew.sh](https://brew.sh))+- **xcodegen** — `brew install xcodegen`-## Development+Sparkle (auto-update framework) is the only external dependency and is pulled automatically by Xcode via Swift Package Manager. No manual setup needed.++## Quick Start```bash-brew install xcodegen-xcodegen generate-open Chops.xcodeproj+git clone https://github.com/Shpigford/chops.git+cd chops+brew install xcodegen # skip if already installed+xcodegen generate # generates Chops.xcodeproj from project.yml+open Chops.xcodeproj # opens in Xcode+```++Then hit **Cmd+R** to build and run.++> **Note:** The Xcode project is generated from `project.yml`. If you change `project.yml`, re-run `xcodegen generate`. Don't edit the `.xcodeproj` directly.++### CLI build (no Xcode GUI)++```bash+xcodebuild -scheme Chops -configuration Debug build+```++## Project Structure++```+Chops/+├── App/+│ ├── ChopsApp.swift # @main entry — SwiftData ModelContainer + Sparkle+│ ├── AppState.swift # @Observable singleton — filters, selection, search+│ └── ContentView.swift # Three-column NavigationSplitView, kicks off scanning+├── Models/+│ ├── Skill.swift # @Model — a discovered skill file+│ ├── Collection.swift # @Model — user-created skill groupings+│ └── ToolSource.swift # Enum of supported tools, their paths and icons+├── Services/+│ ├── SkillScanner.swift # Probes tool directories, upserts skills into SwiftData+│ ├── SkillParser.swift # Dispatches to FrontmatterParser or MDCParser+│ ├── FileWatcher.swift # FSEvents listener, triggers re-scan on changes+│ └── SearchService.swift # In-memory full-text search+├── Utilities/+│ ├── FrontmatterParser.swift # Extracts YAML frontmatter from .md files+│ └── MDCParser.swift # Parses Cursor .mdc files+├── Views/+│ ├── Sidebar/ # Tool filters, collection list+│ ├── Detail/ # Skill editor, metadata display+│ ├── Settings/ # Preferences & update UI+│ └── Shared/ # Reusable components (ToolBadge, NewSkillSheet)+├── Resources/ # Asset catalog (tool icons, colors)+└── Chops.entitlements # Disables sandbox (intentional)++project.yml # xcodegen config — source of truth for Xcode project settings+scripts/ # Release pipeline (release.sh)+site/ # Marketing website (Astro 6)```## Architecture-- **SwiftUI** + **SwiftData** — native macOS, zero web views-- **Sparkle** — auto-updates via GitHub Releases-- **FSEvents** — file watching via DispatchSource-- **No sandbox** — direct access to dotfile directories+**SwiftUI + SwiftData**, native macOS with zero web views.++### App lifecycle++1. `ChopsApp` initializes a SwiftData `ModelContainer` (persists `Skill` and `SkillCollection`)+2. Sparkle updater starts in the background+3. `AppState` is created and injected into the SwiftUI environment+4. `ContentView` renders and calls `startScanning()`+5. `SkillScanner` probes all tool directories and upserts discovered skills+6. `FileWatcher` attaches FSEvents listeners — on any change, the scanner re-runs automatically++### Key design decisions++- **No sandbox.** The app needs unrestricted filesystem access to read dotfiles across `~/`. This is intentional and required for core functionality. The entitlements file explicitly disables the app sandbox.+- **Dedup via symlinks.** Skills are uniquely identified by their resolved symlink path. If the same file is symlinked into multiple tool directories, it shows up as one skill with multiple tool badges.+- **No test suite.** Validate changes manually — build, run, trigger the feature you changed, observe the result.++### State management++`AppState` is an `@Observable` class that holds all UI state: selected tool filter, selected skill, search text, sidebar filter mode. It's injected via `@Environment` and accessible from any view.++### UI layout++Three-column `NavigationSplitView`:+- **Sidebar** — tool filters and collections+- **List** — filtered/searched skill list+- **Detail** — skill editor (wraps `NSTextView` for native text editing with Cmd+S save)++## Supported Tools++Chops scans these directories for skills:++| Tool | Global 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 are also supported but only detect project-level skills (no global paths). Custom paths can be added for any tool.++Tool definitions live in `Chops/Models/ToolSource.swift` — each enum case knows its display name, icon, color, and filesystem paths.++## Common Dev Tasks++### Add support for a new tool++1. Add a new case to the `ToolSource` enum in `Chops/Models/ToolSource.swift`+2. Fill in `displayName`, `iconName`, `color`, and `globalPaths`+3. Optionally add a logo to the asset catalog and return it from `logoAssetName`+4. Update `SkillScanner` if the new tool uses a non-standard file layout++### Modify skill parsing++- **Frontmatter (`.md`)** — edit `Chops/Utilities/FrontmatterParser.swift`+- **Cursor `.mdc` files** — edit `Chops/Utilities/MDCParser.swift`+- **Dispatch logic** — edit `Chops/Services/SkillParser.swift` (decides which parser to use)++### Change the UI++Views are in `Chops/Views/`, organized by column (Sidebar, Detail) and shared components. The main layout is in `Chops/App/ContentView.swift`.++## Testing++No automated test suite. Validate manually:++1. Build and run the app (Cmd+R)+2. Trigger the exact feature you changed+3. Observe the result — check for correct behavior and error messages+4. Test edge cases (empty states, missing directories, malformed files)++## Website++The marketing site lives in `site/` and is built with [Astro](https://astro.build/).++```bash+cd site+npm install # first time only+npm run dev # local dev server+npm run build # production build → site/dist/+```++## AI Agent Setup++This repo includes a Claude Code skill at `.claude/skills/setup.md` that gives AI coding agents full context on the project — architecture, key files, and common tasks. If you're using Claude Code, it'll pick this up automatically.## LicenseMIT — see [LICENSE](LICENSE).-