Contributor

Contributing to Skillet

Architecture

Skillet is a single Rust binary (skillet) that serves as both CLI and MCP server. Package name is skillet-mcp, binary name is skillet.

Module map:

src/
  main.rs        # CLI (clap), MCP server setup
  lib.rs         # Library root, re-exports
  state.rs       # AppState, SkillIndex, SkillEntry, SkillVersion, SkillMetadata
  index.rs       # Directory walking, SKILL.md/frontmatter parsing, config loading
  search.rs      # SkillSearch: BM25 full-text search over skill metadata
  bm25.rs        # Vendored BM25 engine
  cache.rs       # Persistent disk cache for SkillIndex
  config.rs      # Configuration loading (SkilletConfig)
  error.rs       # Error types (thiserror)
  git.rs         # Git operations: clone, pull, head
  prompts.rs     # DynamicPromptRegistry integration, skills as MCP prompts
  project.rs     # skillet.toml unified manifest types and loading
  repo.rs        # Repo management: init, load, merge
  resolve.rs     # Release model resolution (tags/releases/main)
  scaffold.rs    # init-skill, init-registry, init-project scaffolding
  suggest.rs     # [[suggest]] decentralized discovery graph walker
  tools/         # MCP tools: search_skills, list_categories, etc.

Key types:

• AppState -- holds RwLock<SkillIndex>, RwLock<SkillSearch>, repo paths, config
• SkillIndex -- maps (owner, name) to SkillEntry with merge() for multi-repo
• SkillSearch -- wraps BM25 index, rebuilt on refresh
• SkillSource -- variants: Registry, Embedded

Data flow: repos (local/remote) are loaded into SkillIndex, merged first-match-wins, then SkillSearch is built from the merged index. MCP tools query the search index; skills are served as MCP prompts.

Development Setup

git clone https://github.com/joshrotenberg/skillet.git
cd skillet
cargo build
cargo test --lib --all-features

Running Tests

The test suite is organized across multiple files:

# Unit tests (in src/)
cargo test --lib --all-features

# CLI integration tests
cargo test --test cli --all-features

# Scenario tests (multi-step workflows)
cargo test --test scenarios --all-features

# MCP integration tests
cargo test --test mcp --all-features

# HTTP transport tests
cargo test --test http --all-features

# All tests
cargo test --test '*' --all-features

Test fixtures are dynamically generated via testutil.rs.

Pre-commit Checklist

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --lib --all-features
cargo test --test '*' --all-features

PR Workflow

1. Create a feature branch: git checkout -b feat/description
2. Make changes, run the pre-commit checklist
3. Commit with conventional format: feat: add thing, fix: resolve issue
4. Push and open a PR against main
5. Ensure CI passes (fmt, clippy, all tests)

Branch naming conventions:

• feat/ -- new features
• fix/ -- bug fixes
• refactor/ -- code refactoring
• test/ -- test improvements
• docs/ -- documentation

Design Principles

• Tool-first: skillet is the tool, repos are data
• Zero-config-first: only SKILL.md is truly required
• Frontmatter-primary: metadata lives in SKILL.md YAML frontmatter
• Owner/name namespacing: owner/skill-name directories
• Git-backed: repos are git repos, auditable by default