agentleFS
adamos486adamos486/skulto/AGENTS.md

skulto

AGENTS.md51 starsChanged 7 months agoMITView on GitHub

Scope: Root project (applies to all subdirectories unless overridden)

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. asteroid-belt/skulto★ 50100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository6 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    All CI checks must pass before merging.

    line 250
  2. Very specific:

    Follow standard Go conventions (gofmt, go vet)

    line 280
  3. Very specific:

    Run make format before committing

    line 281
  4. Distinctive:

    Write tests for new functionality

    line 282
  5. Distinctive:

    Keep functions focused and small

    line 284
  6. Distinctive:

    Update README.md when features, setup steps, or CLI commands change

    line 314
  7. Distinctive:

    Document new CLI commands with examples

    line 315
  8. Distinctive:

    Update this AGENTS.md when adding new packages or significant architecture changes

    line 316
  9. Distinctive:

    Before completing any task, verify:

    line 324

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Skulto Agent Guide

Scope: Root project (applies to all subdirectories unless overridden)

Quick Facts

ItemValue
Primary languageGo 1.25+
Package managerGo modules (go mod)
Build toolMake (make build, make build-mcp, make build-all)
CLI frameworkCobra + Fang
TUI frameworkBubble Tea + Lip Gloss
MCP frameworkmcp-go v0.27+
DatabaseSQLite + GORM + FTS5 full-text search
Vector searchchromem-go (optional, for semantic search)
AnalyticsPostHog (opt-out via SKULTO_TELEMETRY_TRACKING_ENABLED=false)
Primary binariesskulto (CLI/TUI), skulto-mcp (MCP server)
CI/CDGitHub Actions (.github/workflows/ci.yml)
Test commandmake test (coverage report: coverage.html)
Lint commandmake lint (golangci-lint v2.7.2)

Repository Tour

skulto/
├── cmd/
│   ├── skulto/              # Main CLI/TUI entry point
│   └── skulto-mcp/          # MCP server binary (JSON-RPC 2.0 over stdio)
├── internal/
│   ├── cli/                 # Cobra CLI commands (add, install, pull, scan, etc.)
│   │   └── prompts/         # Interactive CLI prompts (platform selector)
│   ├── config/              # Configuration (env vars only, no config file)
│   ├── db/                  # GORM + SQLite + FTS5 database layer
│   ├── detect/              # AI tool detection on system (command/dir checks)
│   ├── discovery/           # Skill discovery and ingestion from local dirs
│   ├── embedding/           # OpenAI embedding provider abstraction
│   ├── favorites/           # File-based favorites persistence (~/.agents/skulto/favorites.json)
│   ├── installer/           # Skill installation via symlinks (33 platforms)
│   ├── llm/                 # LLM provider abstraction (Anthropic, OpenAI, OpenRouter)
│   ├── log/                 # Structured logging
│   ├── mcp/                 # MCP server implementation (tools + resources)
│   ├── migration/           # Database migrations
│   ├── models/              # Data structures (Skill, Tag, Source, Security, etc.)
│   ├── scraper/             # GitHub scraping (git clone based, shallow clones)
│   ├── search/              # Hybrid search service (FTS5 + semantic)
│   ├── security/            # Security scanner (prompt injection detection)
│   ├── skillgen/            # Local skill scanning (~/.agents/skulto/skills, ./.skulto/skills)
│   ├── telemetry/           # PostHog analytics (opt-in events defined in events.go)
│   ├── testutil/            # Test utilities and helpers
│   ├── tui/                 # Bubble Tea TUI application
│   │   ├── components/      # Reusable UI components (dialogs, selectors)
│   │   ├── design/          # Design constants and skull ASCII art
│   │   └── views/           # Screen views (home, search, detail, onboarding, manage)
│   └── vector/              # Vector store abstraction for semantic search
├── pkg/version/             # Version info (set via ldflags at build time)
├── scripts/                 # Build and release scripts (ship-it.sh, release.sh)
├── docs/                    # Project documentation (overview, architecture, ADRs, glossary)
├── context/                 # Deep-dive technical documentation (see below)
├── plans/                   # Implementation plans (agent-detection, mcp-plan)
├── assets/                  # Demo GIFs for README
└── .github/workflows/       # CI/CD pipelines

Key Directories by Function

PathOwner/Purpose
internal/cli/CLI command implementations - each file is a Cobra command
internal/tui/views/TUI screens - Bubble Tea models for each view
internal/mcp/MCP server - handlers expose CLI/TUI functionality to AI agents
internal/installer/Cross-platform skill installation - symlink management for 33 AI tools
internal/telemetry/PostHog event tracking - events in events.go, client in client.go
internal/db/Database operations - GORM models and FTS5 search queries
internal/security/Security scanner - regex patterns for prompt injection detection
internal/scraper/Repository manager - git clone/fetch, skill file parsing

Architecture Overview

Three Interfaces, One Codebase

Skulto exposes identical functionality through three interfaces that share services:

┌─────────────────────────────────────────────────────────────────┐
│                        User Interfaces                          │
├─────────────────┬─────────────────┬─────────────────────────────┤
│   CLI (Cobra)   │   TUI (Bubble)  │   MCP (mcp-go over stdio)   │
│   cmd/skulto    │   internal/tui  │   cmd/skulto-mcp            │
├─────────────────┴─────────────────┴─────────────────────────────┤
│                      Shared Services                            │
├─────────────────────────────────────────────────────────────────┤
│  InstallService (installer/)  │  SearchService (search/)        │
│  Scraper (scraper/)           │  SecurityScanner (security/)    │
│  Database (db/)               │  Telemetry (telemetry/)         │
└─────────────────────────────────────────────────────────────────┘

See: context/architecture.md for detailed component interactions.

Platform Support (33 AI Coding Tools)

Skulto detects and installs skills to platforms defined in internal/installer/platform.go:

  • Original 6: Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, OpenCode
  • Extended 27: Amp, Kimi CLI, Antigravity, Moltbot, Cline, Roo Code, Gemini CLI, Kiro CLI, Continue, Goose, Junie, Kilo Code, MCPJam, Mux, OpenHands, Pi, Qoder, Qwen Code, Trae, Zencoder, Neovate, Pochi, CodeBuddy, Command Code, Crush, Droid, Kode

Each platform defines: command name, project dir, global dir, and platform-specific paths.

See: context/platforms.md for platform registry details.

Security Scanner

The security scanner (internal/security/) detects prompt injection threats:

CategorySeverityExamples
Instruction OverrideHIGH"ignore previous instructions", "disregard rules"
JailbreakCRITICALDAN jailbreak, developer mode, unrestricted AI
Data ExfiltrationHIGHRequests to leak system prompts or context
Dangerous CommandsMEDIUM-HIGHShell execution, file operations

Scoring uses base severity weights with context mitigation (e.g., educational content reduces score).

See: context/security.md for pattern details.

Telemetry System

Events are tracked consistently across all interfaces:

  1. Define event in internal/telemetry/events.go
  2. Add method to both posthogClient and noopClient
  3. Add signature to Client interface in client.go
  4. Call from CLI, TUI, AND MCP handlers

Current event categories: CLI, TUI, Session, Shared (cross-interface), MCP-specific.

See: context/telemetry.md for event catalog.

Tooling & Setup

Requirements

  • Go 1.25 or higher
  • Make
  • (Optional) GITHUB_TOKEN for higher GitHub API rate limits
  • (Optional) OPENAI_API_KEY for semantic search embeddings

Install Dependencies

make deps

Downloads Go modules, runs go mod tidy, and installs golangci-lint to ./bin/.

Environment Variables

VariablePurpose
GITHUB_TOKENHigher GitHub API rate limits
OPENAI_API_KEYEmbeddings for semantic search
SKULTO_TELEMETRY_TRACKING_ENABLEDSet to false to disable telemetry
SKULTO_POSTHOG_API_KEYPostHog API key (set at build time via ldflags)

Data Directory

Skulto stores data in ~/.agents/skulto/:

PathPurpose
~/.agents/skulto/skulto.dbSQLite database
~/.agents/skulto/skulto.logLogfile
~/.agents/skulto/repositories/{owner}/{repo}/Cloned git repositories
~/.agents/skulto/favorites.jsonFavorite skills (persists across DB resets)
~/.agents/skulto/skills/User's local skills directory

Common Tasks

Build

make build           # Build skulto binary → ./build/skulto
make build-mcp       # Build MCP server → ./build/skulto-mcp
make build-all       # Build both binaries
make dev             # Development build with race detector (requires CGO_ENABLED=1)

Run

./build/skulto           # Launch TUI (default)
./build/skulto <cmd>     # Run CLI command
./build/skulto-mcp       # Run MCP server (stdio)

Test

make test            # Run all tests with coverage → coverage.html
make test-race       # Run tests with race detector (CGO_ENABLED=1)
go test ./internal/cli/...    # Test specific package
go test -v -run TestSearch    # Run specific test

Lint & Format

make lint            # Run golangci-lint (5m timeout)
make format          # Format code with gofmt
make vet             # Run go vet

Clean

make clean           # Remove build artifacts, coverage files, and release dir

Ship (Pre-push Validation)

make ship_it         # Build, lint, test, then push (via scripts/ship-it.sh)

Testing & Quality Gates

Test Organization

Tests are co-located with source files in *_test.go files:

  • Unit tests: foo_test.go alongside foo.go
  • Characterization tests: *_characterization_test.go for snapshot-style testing
  • Integration tests: *_integration_test.go (may require network)

Coverage

After running make test:

  • coverage.out - Raw coverage data
  • coverage.html - HTML report (open in browser)

CI Expectations

CI (.github/workflows/ci.yml) runs on every push to main and all PRs:

  1. Lint - make lint (golangci-lint)
  2. Test - make test with coverage
  3. Build matrix - Cross-compile for linux/darwin on amd64/arm64

All CI checks must pass before merging.

Workflow Expectations

Branching

  • main is the primary branch
  • Feature branches: feature/description or topic/description
  • PRs require passing CI checks

Commit Messages

Follow Conventional Commits:

feat(scraper): add support for nested skill directories
fix(tui): correct keybinding conflict for search
docs(readme): update MCP server configuration
refactor(installer): extract platform detection to service
test(db): add FTS5 ranking characterization tests
chore(deps): update go-openai to v1.41
perf(search): cache FTS query preparation

Types: feat, fix, docs, style, refactor, test, chore, perf

Scopes: cli, tui, mcp, db, installer, scraper, search, security, telemetry, deps

Code Style

  • Follow standard Go conventions (gofmt, go vet)
  • Run make format before committing
  • Write tests for new functionality
  • Document exported functions
  • Keep functions focused and small

Documentation

Project Documentation (docs/)

FileTopic
docs/overview.mdProject identity, purpose, key features, status
docs/architecture.mdSystem design, components, data flow, external dependencies
docs/getting-started.mdPrerequisites, installation, configuration, first run
docs/development.mdRepository structure, workflow, testing, CI/CD, distribution
docs/adr/README.mdArchitecture Decision Records index
docs/glossary.mdDomain terminology and acronyms

Deep-Dive Documentation (context/)

The context/ directory contains detailed technical documentation:

FileTopic
context/architecture.mdSystem architecture, data flow, component interactions
context/platforms.mdPlatform registry, detection logic, installation paths
context/security.mdSecurity scanner patterns, scoring, threat levels
context/telemetry.mdEvent catalog, tracking implementation, opt-out
context/database.mdSchema, FTS5 setup, GORM models, migrations
context/mcp-server.mdMCP tools, resources, handler implementation

Documentation Duties

  • Update README.md when features, setup steps, or CLI commands change
  • Document new CLI commands with examples
  • Update this AGENTS.md when adding new packages or significant architecture changes
  • Project-level docs (overview, architecture, getting started, development) go in docs/
  • Architecture Decision Records go in docs/adr/
  • Plan documents go in plans/
  • Deep-dive technical docs go in context/

Finish the Task Checklist

Before completing any task, verify:

  • Code passes linter (make lint)
  • Code is formatted (make format)
  • All new code has tests
  • All tests pass (make test)
  • No new warnings introduced
  • Telemetry events added for new user-facing features (if applicable)
  • Update relevant docs (& README.md if significant changes)
  • Summarize changes in conventional commit format

Commit Summary Template

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

<optional body explaining the "why">

<optional footer with breaking changes or issue refs>

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.