git:20260125.0fa8930 to git:20260205.4c0e8af

- Skulto is an offline-first tool for syncing and managing agent skills. It scrapes GitHub for AI skill files, indexes them with SQLite FTS5, provides a Bubble Tea TUI, and translates skills between 6 AI platforms.

-

- | Attribute | Value |

- |-----------|-------|

- | **Package manager** | Go modules |

- | **Build system** | Make |

- | **Database** | SQLite with FTS5 (GORM) |

- | **TUI framework** | Bubble Tea + Lip Gloss |

- | **CI/CD** | GitHub Actions |

- | **Data location** | `~/.skulto/` (simplified from XDG) |

- ├── cmd/skulto/ # Main CLI entry point

- ├── internal/ # Private packages (see below)

- │ ├── cli/ # Cobra CLI commands (add, list, pull, etc.)

- │ ├── config/ # Configuration (env vars only, no config file)

- │ ├── db/ # GORM + SQLite + FTS5 database layer

- │ ├── detect/ # AI tool detection on system

- │ ├── embedding/ # Embedding provider abstraction

- │ ├── installer/ # Skill installation via symlinks

- │ ├── llm/ # LLM provider abstraction (Anthropic, OpenAI, OpenRouter)

- │ ├── log/ # Structured logging

- │ ├── migration/ # Database migrations

- │ ├── models/ # Data structures (Skill, Tag, Source, etc.)

- │ ├── scraper/ # GitHub scraping (git clone + REST API)

- │ ├── search/ # Search service + background indexer

- │ ├── security/ # Security scanner for skills

- │ ├── skillgen/ # Skill generation utilities

- │ ├── telemetry/ # PostHog analytics (opt-in)

- │ ├── testutil/ # Test utilities (SkipAITests helper)

- │ ├── tui/ # Bubble Tea TUI

- │ │ ├── components/ # Reusable UI components

- │ │ └── views/ # Screen views (home, search, detail, etc.)

- │ └── vector/ # Vector store (chromem-go)

- ├── pkg/version/ # Version info (set via ldflags)

- ├── scripts/ # Build and release scripts

- ├── docs/ # Planning documents

- │ ├── completed/ # Finished implementation plans

- │ └── in-review/ # Plans under review

- └── .github/workflows/ # CI/CD pipelines

- ## Tooling & Setup

-

- ### Prerequisites

- - **Go 1.25+** (check with `go version`)

- - **Make** (for build automation)

- - **asdf** (optional, uses `.tool-versions`)

- ### Environment Variables

- Configuration is done entirely via environment variables (no config file).

- | Variable | Purpose | Required |

- |----------|---------|----------|

- | `GITHUB_TOKEN` | Higher GitHub API rate limits | Optional |

- | `OPENAI_API_KEY` | Embeddings for semantic search | Optional |

- | `ANTHROPIC_API_KEY` | LLM provider | Optional |

- | `OPENROUTER_API_KEY` | Alternative LLM provider | Optional |

- | `RUN_AI_TESTS` | Enable AI-dependent tests | Test only |

- | `SKULTO_TELEMETRY_TRACKING_ENABLED` | Set to `false` to disable telemetry (enabled by default) | Optional |

- ### Initial Setup

- # Install dependencies + golangci-lint

- # Build the binary

- make build

- # Run the TUI

- ./build/skulto

- ```

- ## Common Tasks

- | Task | Command | Description |

- |------|---------|-------------|

- | Build | `make build` | Production build to `./build/skulto` |

- | Dev build | `make dev` | Build with race detector (requires CGO) |

- | Run | `make run` | Build and run TUI |

- | Test | `make test` | Run all tests |

- | Test + race | `make test-race` | Tests with race detector |

- | Coverage | `make test-coverage` | Generate `coverage.html` |

- | Lint | `make lint` | Run golangci-lint |

- | Format | `make format` | Run `go fmt` |

- | Clean | `make clean` | Remove build artifacts |

- | Ship | `make ship_it` | Build, lint, test, then push |

- ### Running Specific Tests

- ```bash

- # Run all tests

- go test ./...

- # Run tests for a specific package

- go test ./internal/db/...

- # Run AI-dependent tests (requires API keys)

- RUN_AI_TESTS=1 go test ./...

- # Run with verbose output

- go test -v ./internal/config/...

- ## CLI Subcommands

- Skulto provides both an interactive TUI and CLI subcommands for scripting.

- | Command | Purpose |

- |---------|---------|

- | `skulto` | Launch the interactive Bubble Tea TUI |

- | `skulto add <repo>` | Add a skill repository and sync its skills |

- | `skulto list` | List all configured source repositories with skill counts |

- | `skulto pull` | Pull/sync all skill repositories and reconcile installed skills |

- | `skulto remove [repo]` | Remove a skill repository (uninstalls skills, deletes from DB and disk) |

- | `skulto scan` | Scan skills for security threats (prompt injection, dangerous patterns) |

- | `skulto update` | Combined `pull` + `scan` with enhanced change reporting |

- | `skulto info <slug>` | Show detailed information about a specific skill |

- ### Command Details

- **`skulto add <repo>`** - Add a skill repository

- - Parses GitHub URLs: `owner/repo`, `https://github.com/owner/repo`, `git@github.com:owner/repo.git`

- - Clones repository and scans for skills

- - Flag: `--no-sync` to defer cloning

- **`skulto pull`** - Sync all repositories

- - Clones/updates all registered repositories

- - Scans AI tool directories to detect installed skills

- - Reconciles database state with filesystem

- **`skulto remove [repo]`** - Remove a repository

- - Interactive selection if no repo specified

- - Uninstalls all skills (removes symlinks)

- - Deletes skill records, source record, and git clone

- - Flag: `--force` to skip confirmation

- **`skulto scan`** - Security scanning

- - Scans for prompt injection and dangerous code patterns

- - Flags: `--all`, `--skill <id>`, `--source <owner/repo>`, `--pending`

- - Reports threat levels: CRITICAL, HIGH, MEDIUM, LOW

- **`skulto update`** - Pull + scan with reporting

- - Phase 1: Pull repositories

- - Phase 2: Security scan on new/updated skills

- - Phase 3: Summary report with change details

- - Flag: `--scan-all` to scan all skills

- ## Testing & Quality Gates

- ### Test Categories

- 1. **Unit tests** - Fast, no external dependencies

- 2. **Integration tests** - May require network (git clone tests)

- 3. **AI tests** - Require API keys, gated by `RUN_AI_TESTS=1`

- ### AI Test Guard

- Tests requiring LLM/embedding API keys use `testutil.SkipAITests(t)`:

- ```go

- func TestSomethingWithAI(t *testing.T) {

- testutil.SkipAITests(t) // Skips unless RUN_AI_TESTS=1

- apiKey := os.Getenv("OPENAI_API_KEY")

- if apiKey == "" {

- t.Skip("OPENAI_API_KEY not set")

- }

- // ...

- }

- ```

- ### CI Pipeline

- The CI workflow (`.github/workflows/ci.yml`) runs:

- 1. `make deps` - Install dependencies

- 2. `make lint` - Linting with golangci-lint

- 3. `make test` - All tests

- 4. Cross-platform builds (linux/darwin, amd64/arm64)

- ### Coverage Expectations

- - Aim for meaningful coverage on business logic

- - Characterization tests exist for installer behavior

- - Integration tests cover scraper and search pipelines

- - Feature branches: `feature/<name>`

- - Bug fixes: `fix/<name>`

- chore(deps): update dependencies

- ### Pre-Push Checklist

- 1. `make format` - Format code

- 2. `make lint` - Pass linting

- 3. `make test` - Pass all tests

- 4. `make build` - Verify build succeeds

- Or use: `make ship_it` (runs build, lint, test, then pushes)

- ## Code Conventions

- ### Package Structure

- - `internal/` packages are private to the module

- - Each package has a primary file matching the package name (e.g., `db/db.go`)

- - Tests are co-located with source files (`*_test.go`)

- ### Error Handling

- - Wrap errors with context: `fmt.Errorf("operation failed: %w", err)`

- - Return early on errors

- - Use `require.NoError(t, err)` in tests

- ### Configuration

- - All config flows through `internal/config`

- - Configuration is read from environment variables only (no config file)

- - `Config.BaseDir` is the root for all data (`~/.skulto/`)

- - Repositories are cloned to `~/.skulto/repositories/`

- - Use `config.GetPaths(cfg)` for derived paths

- ### Database

- - GORM with SQLite backend

- - FTS5 for full-text search on skills

- - Models in `internal/models/`

- - Database operations in `internal/db/`

- ## Documentation Duties

- ### When to Update README.md

- - New user-facing features

- - Changed CLI commands or flags

- - Updated installation steps

- - Modified keybindings

- After completing any task:

- - [ ] Run `make format` and `make lint`

- - [ ] Run `make test` to verify no regressions

- - [ ] Update `README.md` and `AGENTS.md` if user-facing/project-changes changes were made

- - [ ] Update relevant docs if architecture changed

- - [ ] Commit with conventional commit format

- ### Commit Template

- <type>(<scope>): <description>

- [optional body]

- Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`