CLAUDE.md

Notes for AI coding agents working in this repo. Read before exploring.

What this is

A TUI written in Go that scans SKILL.md files across every supported agentic-CLI harness on a machine (Claude Code, Codex, Cursor, OpenCode, Antigravity) and shows them in three views (matrix / tree / diff) broken out by scope. The full design rationale lives in DESIGN.md and the original spec is in GOAL.md — read both before making non-trivial changes.

Layout

cmd/skillscope/           main, flag parsing, harness/view registration
internal/app/             event loop, model, keymaps, render glue
internal/harness/         the Harness interface + one subpkg per harness
internal/view/            matrix, tree, diff — each in its own subpkg
internal/scan/            walker that resolves Scopes → SkillRecords
internal/ops/             copy / move / delete on disk
internal/ui/              shared lipgloss styles + preview cache
testdata/                 fixtures used by `make demo` and tests

The two plugin surfaces

Adding a harness or a view is intentionally one file in one place:

• Harness: drop internal/harness/<id>/harness.go implementing the harness.Harness interface and calling harness.Register(h{}) in init(). Add a blank import in cmd/skillscope/main.go.
• View: drop internal/view/<id>/view.go implementing app.View and calling app.RegisterView(v{}) in init(). Same blank-import step.

No central switch statement, no factory map. If you find yourself editing the core to "register" something, you're doing it wrong.

Tooling

• Go 1.24.5+ (matches go.mod). CI's matrix pins "1.24" which picks the latest patch.
• make build / make test / make demo. make demo runs the TUI pointed at testdata/ — useful when verifying UI changes.
• Single static binary, no CGO. Cross-compiles cleanly to linux/macos/windows × amd64/arm64.
• Lint job runs gofmt -l ., go vet ./..., and staticcheck (pinned to 2025.1.1). Keep gofmt clean — CI rejects unformatted files.

Windows / cross-platform

All scope paths flow through filepath.Join(ctx.HomeDir, …) — HomeDir comes from os.UserHomeDir() which returns %USERPROFILE% on Windows. Hardcoding / separators or string-concatenating paths will break the Windows build. Cross-platform contract is locked by scanner_pathsep_test.go (every platform) and the build-tagged scanner_windows_test.go (Windows-only on CI).

House rules

• Never follow symlinks out of scope. scan.walkScope uses os.Lstat and refuses symlinked SKILL.md. ops.copyFile does the same on the source side. Don't loosen these — there are tests guarding both.
• Ops respect Scope.ReadOnly. Plugin scopes are read-only; Copy and Move must reject them. Same: tests guard this.
• Preview rendering is async. ui.Render is the heavyweight glamour pass — only call it from a tea.Cmd goroutine and store the result via m.Preview.Set. Never block Update or View on it.
• PR policy: PRs created by agents must be draft and stay draft. Use gh pr create --draft …. Don't gh pr ready.

Where to look first when…

• adding a new SKILL.md location for an existing harness → internal/harness/<id>/harness.go, edit the returned Scopes.
• changing matrix/tree/diff layout → internal/view/<id>/view.go.
• adding a keybinding → internal/app/update.go (handleKey).
• changing what shows in the preview pane → internal/ui/preview.go and internal/app/render.go::renderModalPreview.
• adding a CLI flag → cmd/skillscope/main.go.