mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
Add a shared instruction kernel and byte-budgeted topic router so agents load only task-relevant repository guidance. Wire drift checks into local and CI workflows and point project skills at the routed topics.
3.6 KiB
3.6 KiB
Repository Architecture
Use when deciding which layer should own a change, tracing CLI or Web API data flow, or building an initial mental model of the codebase.
Product Boundaries
skillshare's source of truth is either the global configuration directory (~/.config/skillshare/ by default on macOS/Linux) or project-local .skillshare/ state. The CLI transforms or synchronizes skills, agents, extras, MCP servers, and plugins into each AI tool's native locations. Never infer runtime behavior from README files or documentation alone; verify the current implementation and embedded configuration.
Repository Map
| Path | Responsibility |
|---|---|
cmd/skillshare/ |
CLI entry point, flag parsing, mode routing, TUIs, and command orchestration |
internal/config/ |
Global/project configuration, registry, migrations, and target resolution; targets.yaml defines built-in targets |
internal/<domain>/ |
Domain logic such as install, sync, audit, MCP, plugins, and backup |
internal/server/ |
Dashboard HTTP API; routes are registered in server.go and handlers live in handler_*.go |
internal/testutil/ |
Shared isolated Sandbox and CLI runner for integration tests |
tests/integration/ |
CLI integration tests |
ui/ |
React 19 and Vite dashboard; its API client corresponds to internal/server/ |
website/ |
Docusaurus public documentation and marketing pages |
ai_docs/tests/ |
Reproducible CLI E2E runbooks |
skills/skillshare/ |
Built-in skill for skillshare users, not internal development instructions |
schemas/ |
Public YAML/JSON schemas; inspect these when configuration shapes change |
scripts/, Makefile, mise.toml |
Build, test, devcontainer, and verification entry points |
Request Flow
A typical CLI request follows this path:
- The
commandsmap incmd/skillshare/main.godispatches the command. cmd/skillshare/<command>.goparses flags and selects global or project mode.cmd/skillshare/<command>_*.gocomposes domain operations, prompts, and output.internal/<domain>/performs filesystem, Git, configuration, or audit logic.- Mutating operations write to
operations.logthroughinternal/oplog; security scans use the audit log.
A typical dashboard request follows this path:
ui/src/api/client.tssends the request.- A route registered in
internal/server/server.goentershandler_<domain>.go. - The handler uses the same
internal/domain package as the CLI. Do not duplicate core behavior in the frontend or handler. - Project/global differences use the server mode and existing helpers rather than a separate data model.
Sources of Truth
- Command flags and behavior:
cmd/skillshare/*.go. - Target names, aliases, and default paths:
internal/config/targets.yaml. - Built-in audit rules:
internal/audit/rules.yamland related table-driven analyzers. - Public configuration contracts:
schemas/*.jsonand configuration parsing/validation code. - Dashboard design values:
ui/src/components.cssandui/src/index.css. - Website design values:
website/src/css/custom.cssand page CSS modules. - Build and test commands:
Makefile,mise.toml, and CI workflows.
Trace Checklist
Before changing code:
- Search for the existing symbol, flag, or route and find its definition, callers, and tests.
- Determine whether both global and project mode are affected.
- If the CLI and Web API expose the same behavior, verify that they share domain logic.
- For state changes, inspect backup, rollback, oplog, dry-run, and audit implications.
- Load
documentationfor public contract changes,cli-developmentfor implementation, andtestingbefore execution.